feat: add thread research briefs (#8)

Author: N0zoM1z0

README.md

@@ -132,11 +132,12 @@ gitcontribute search code "context.WithTimeout" --repo golang/go
 
 ### 2. Investigate
 
-Build a dossier, inspect repository health, record a hypothesis, and check for
-duplicate or competing work before committing time.
+Build a dossier or per-thread research brief, inspect repository health, record
+a hypothesis, and check for duplicate or competing work before committing time.
 
 ```sh
 gitcontribute dossier build owner/repo
+gitcontribute research brief issue:owner/repo#42 --format markdown
 gitcontribute health owner/repo --json
 gitcontribute investigation start owner/repo --json
 gitcontribute hypothesis add --title="Fix retry timeout" \
@@ -195,7 +196,7 @@ MCP capabilities are deliberately separate:
 
 | Capability | Examples |
 | --- | --- |
-| **Offline reads** | Search, inspect repositories and threads, read dossiers, explain matches, inspect evidence and opportunities. |
+| **Offline reads** | Search, inspect repositories and threads, build research briefs, read dossiers, explain matches, inspect evidence and opportunities. |
 | **Network reads** | Sync repositories, hydrate threads, start crawls, and acquire workspaces. |
 | **Local writes** | Start investigations, record hypotheses, promote opportunities, define validations, and prepare drafts. |
 | **Execution** | Run a validation only when the request includes `execute: true`. |
@@ -208,7 +209,7 @@ application and adapter boundaries.
 
 | Operation | Network | Local write | Runs a process | GitHub write |
 | --- | :---: | :---: | :---: | :---: |
-| Search, health, dossier inspection | — | — | — | — |
+| Search, health, dossier and research-brief inspection | — | — | — | — |
 | Investigations, evidence, lenses | — | ✓ | — | — |
 | Sync, crawl, hydrate | ✓ | ✓ | — | — |
 | Acquire or create a workspace | remote-dependent | ✓ | `git` only | — |
@@ -327,7 +328,7 @@ enforces size limits, and rejects dirty worktrees.
 </details>
 
 <details>
-<summary><strong>Radar, search, dossiers, health, seeds, and lenses</strong></summary>
+<summary><strong>Radar, research briefs, search, dossiers, health, seeds, and lenses</strong></summary>
 
 ```sh
 gitcontribute radar owner/repo --limit 20
@@ -341,6 +342,8 @@ gitcontribute search all "retry" --repo owner/repo
 gitcontribute dossier build owner/repo
 gitcontribute dossier export owner/repo --format markdown \
   --output owner-repo-dossier.md
+gitcontribute research brief owner/repo#42
+gitcontribute research brief pr:owner/repo#108 --json
 gitcontribute health owner/repo --stale-after 336h --json
 gitcontribute seeds owner/repo --json
 ```
@@ -361,6 +364,23 @@ Radar scores carry a version (`radar.v1`) so saved JSON remains auditable when
 ranking semantics evolve. It never syncs, hydrates, executes repository code,
 or writes to GitHub.
 
+`research brief` is also a strict offline read. Its versioned
+`research-brief.v1` output has fixed sections for state, stored problem fields,
+acceptance hints, participants, timeline, explicit/duplicate references,
+linked PRs, indexed code, contribution guidance, health, coverage gaps, and
+next commands. Every section carries source references or an explicit unknown
+reason. Checkboxes and maintainer phrases remain source extracts—not fabricated
+or complete acceptance criteria. Markdown output redacts common credentials and
+quotes untrusted source text; JSON ordering is deterministic.
+
+Missing child facets and code stay visible instead of triggering hidden work:
+
+```sh
+gitcontribute archive hydrate owner/repo#42 --with issue_comments
+gitcontribute index owner/repo /path/to/clean-checkout
+gitcontribute research brief issue:owner/repo#42 --json
+```
+
 Use a lens to apply saved filters and weighted ranking to a bounded population:
 
 ```sh

docs/architecture.md

@@ -22,7 +22,7 @@ TUI ---------+              |
                   observations + projections
                             |
                             v
-              offline search, radar, health, dossiers,
+              offline search, radar, health, dossiers, thread briefs,
              investigations, evidence, and drafts
 ```
 
@@ -43,7 +43,7 @@ application and domain packages expose product-owned values and interfaces.
 
 | Capability | Examples | Network | Local write | Process execution | GitHub mutation |
 | --- | --- | ---: | ---: | ---: | ---: |
-| Corpus read | search, health, dossier show, MCP resources | no | no | no | no |
+| Corpus read | search, health, dossier show, research brief, MCP resources | no | no | no | no |
 | Corpus write | investigations, evidence, lenses, tracking | no | yes | no | no |
 | GitHub read | sync, crawl, hydrate | yes | yes | no | no |
 | Git acquisition | acquire, workspace create | remote-dependent | yes | `git` only | no |
@@ -153,8 +153,11 @@ uses a bounded population and therefore does not support cursor pagination.
 Contribution Radar similarly ranks a bounded open-issue population, separates
 eligibility from score, and reports positive signals, risks, blockers, and
 unknown evidence. Missing coverage is never silently converted into a negative
-signal. Health metrics and dossier generation also operate only on stored facts
-and report partial or missing coverage when required facets are incomplete.
+signal. Health metrics, dossier generation, and thread research briefs also
+operate only on stored facts and report partial or missing coverage when
+required facets are incomplete. A research-brief section must carry a source
+reference or an explicit unknown reason; untrusted thread text remains data and
+cannot grant an adapter additional authority.
 
 ## Schema changes
 

internal/app/control.go

@@ -44,7 +44,7 @@ func (s *Service) Metadata(ctx context.Context) (*cli.MetadataResult, error) {
 	capabilities := []string{
 		"archive", "clustering", "collections", "contribution-radar", "dossiers", "evidence",
 		"github-read", "investigations", "local-search", "mcp-stdio",
-		"validation", "workspaces",
+		"thread-research-brief", "validation", "workspaces",
 	}
 	sort.Strings(capabilities)
 	return &cli.MetadataResult{
@@ -62,6 +62,7 @@ func (s *Service) Metadata(ctx context.Context) (*cli.MetadataResult, error) {
 			"github_mutations":   false,
 			"mcp_stdio":          true,
 			"semantic_search":    false,
+			"thread_research":    true,
 			"validation_exec":    true,
 		},
 	}, nil

internal/app/control_test.go

@@ -41,6 +41,9 @@ func TestMetadataIsLocalAndDoesNotCreateCorpus(t *testing.T) {
 	if !result.Features["contribution_radar"] || !containsString(result.Capabilities, "contribution-radar") {
 		t.Fatalf("radar capability missing from metadata: %+v", result)
 	}
+	if !result.Features["thread_research"] || !containsString(result.Capabilities, "thread-research-brief") {
+		t.Fatalf("thread research capability missing from metadata: %+v", result)
+	}
 	if _, err := os.Stat(result.CorpusPath); !os.IsNotExist(err) {
 		t.Fatalf("metadata created corpus %q: %v", result.CorpusPath, err)
 	}

internal/app/research.go

@@ -0,0 +1,22 @@
+package app
+
+import (
+	"context"
+	"errors"
+
+	"github.com/morluto/gitcontribute/internal/cli"
+	"github.com/morluto/gitcontribute/internal/research"
+)
+
+// ThreadResearchBrief builds a deterministic brief from the local corpus. It
+// performs no network access, local mutation, or process execution.
+func (s *Service) ThreadResearchBrief(ctx context.Context, ref research.ThreadRef) (*research.Brief, error) {
+	brief, err := research.NewBuilder(&corpusReader{s: s}, s.now).Build(ctx, ref)
+	if err == nil {
+		return brief, nil
+	}
+	if errors.Is(err, errRepositoryNotFound) || errors.Is(err, research.ErrThreadNotFound) || errors.Is(err, research.ErrThreadKindMismatch) {
+		return nil, cli.NewCLIError(cli.ExitNotFound, err)
+	}
+	return nil, err
+}