From c270f330f22cbd08341532f94c5aff606d73b360 Mon Sep 17 00:00:00 2001 From: Daniel Green Date: Mon, 11 May 2026 06:24:58 -0700 Subject: [PATCH] plan(3075): write plan-3075.md --- plans/plan-3075.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 plans/plan-3075.md diff --git a/plans/plan-3075.md b/plans/plan-3075.md new file mode 100644 index 00000000..5949493b --- /dev/null +++ b/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//` 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.