plan: #3075

plans/plan-3075.md

@@ -0,0 +1,38 @@
+# Archivist + Curation Pass (Sibling-Repo Write)
+
+## Summary
+Add the archivist pass that runs at the end of every research cycle and emits a keep/discard/expand decision (with rationale) per scratch artifact. Kept artifacts graduate from feature-branch scratch into the sibling research repo via the storage abstraction delivered by parent-sibling Issue #3072. This Issue also owns the first cross-platform write proof (a non-`github↔github` combo) for the research-storage seam.
+
+## Problem / Motivation
+Research passes accumulate scratch under `research/scratch/<apex-id>/` on the feature branch (per parent #3071). Without curation, scratch either bloats the feature branch or is auto-pruned at apex close with no durable record — research effort is lost. We need a deterministic curation step that decides what graduates to the long-lived sibling research repo and enriches each kept artifact with the citation metadata (source URL, capture date, freshness signal) required for downstream Obsidian/Johnny-Decimal use (#3077). Because this is the first write into the sibling repo, it is also the first opportunity to prove the cross-platform leg of the storage abstraction end-to-end.
+
+## Proposed Approach
+1. **Archivist agent** — a new agent invoked at the end of a research cycle. It reads the scratch directory for the current apex and emits, per artifact, a structured `{decision: keep|discard|expand, rationale, relevance_signals}` record. Relevance signals cover the five axes called out in the parent: domain, codebase, technology stacks, ecosystem, linkability. Output is JSON-schema-validated so downstream code is deterministic.
+2. **Promotion writer + citation enrichment** — a deterministic pass (called from the research sub-workflow, not the agent) that consumes `keep` decisions and writes the artifact through the storage abstraction from #3072. It enriches each kept article with `source_url`, `capture_date` (UTC ISO-8601), and a `freshness` signal (e.g., `fetched_at` + a coarse staleness band). `discard` is a no-op (scratch is auto-pruned at apex close); `expand` is recorded in the run artifact for the researcher loop-back wired in #3076 — this Issue does not own the loop-back itself.
+3. **Cross-platform proof** — add a harness scenario (preferred over live CI) under `tests/harness/scenarios/` that drives the full curation→write path against a non-`github↔github` combo. Tentative: source-on-GitHub + research-on-ADO. The plan records the chosen combo and the harness scenario id; the run artifact captures the combo at execution time so reviewers can verify which leg was exercised.
+
+File/seam touch list (grounded — verify during impl):
+- `workflows/` — wire archivist + promotion node into the research sub-workflow (owned by #3073; this Issue contributes the node definitions).
+- `src/Polyphony/...` — promotion writer + citation enrichment helper (deterministic, not agent code).
+- `tests/harness/scenarios/` — cross-platform write scenario.
+- `.polyphony-config/` — no schema changes here; `research:` block is owned by #3072.
+
+## Acceptance Criteria
+- [ ] Archivist produces a `keep | discard | expand` decision per scratch artifact with a recorded rationale, validated against a JSON schema.
+- [ ] Kept articles are written into the sibling research repo through the storage abstraction from #3072 (no direct git/platform calls in this Issue's code).
+- [ ] Each kept article carries `source_url`, `capture_date`, and a freshness signal in its front matter or sidecar metadata.
+- [ ] An end-to-end cross-platform write is proven in the harness (or CI) for a combination other than `github↔github`; the chosen combo is recorded in this plan and emitted in the run artifact.
+- [ ] Build passes with zero errors and warnings; new tests cover archivist decision shape, promotion writer behaviour, and citation enrichment.
+- [ ] All existing tests pass.
+
+## Child Tasks
+- task-1 — Archivist agent + decision schema
+- task-2 — Promotion writer + citation enrichment (consumes `keep` decisions, writes via #3072 abstraction)
+- task-3 — Cross-platform end-to-end write proof (harness scenario, non-`github↔github` combo)
+
+## Dependencies
+- Parent-sibling **#3072** — Research storage abstraction + per-repo `research:` config. task-2 cannot land before #3072's read/write/list API is available. task-3 requires both legs of that abstraction to be selectable by the platform router.
+- Parent-sibling **#3073** — Research sub-workflow + `research-assistant` agent provides the host workflow into which the archivist + promotion nodes are wired. If #3073 is not yet landed when this Issue starts, task-1 and task-2 can still ship as standalone agent + helper; wiring the nodes into the sub-workflow may need a small follow-up.
+
+## Context
+Parent Epic: #3071 — Research-augmented planning cycle. Parent description establishes the hybrid storage model (feature-branch scratch + sibling research repo, Obsidian-friendly, Johnny-Decimal, academic-style citations) and the cross-platform requirement (source-on-ADO ↔ research-on-GitHub and inverse). This Issue is the first writer of the sibling repo, so the cross-platform proof criterion is anchored here by deliberate parent-level design.