/nexus

chronicle — Commit-history reverse-engineering → era timeline + narrative storylines + lens deep-dives + repository history document set

Purpose: Full phase contract for the chronicle Recipe — take a repository (or a path/component within it) and its commit history, reverse-engineer how it evolved over time from the git record itself, carve the history along two axes — the time axis (coherent eras) and the theme axis (narrative storylines that run through them: how features were added, how defects were fought, how the code was improved, and how key decisions were made) — excavate the turning-point commits and thread beats, and produce a history document set (docs/history/<slug>/): a narrated overview (README.md) of how the repo got from its first commit to its current HEAD — visual era timeline, per-storyline narratives, reconstructed decision log — plus per-lens deep-dive files (lenses/<lens>.md): dedicated documents that re-read the same history through the default analysis lenses — security · domain-design · architecture · performance · design-ux · issues — each a split file so the overview stays an overview and the depth lives in its own document. Writes no product code — the deliverable is documentation, grounded in commit evidence. The temporal member of the Comprehend family: where cartograph maps how a system is architected across space (a bird's-eye snapshot of how it works today), chronicle maps how a repo evolved across time (the arc of how it got here).

Two-axis model (the source of story-ness): eras are the acts (horizontal time segments — "Bootstrapping", "Rapid expansion", "Hardening"); storylines are the plot lines that weave through the acts (vertical theme threads). The story is the weave of the two — not a flat log, and not only a phase list. The default storyline set (each narrated as a mini-arc: origin → developments-per-era → current state → open threads):

• Feature lineage (feat) — how capabilities were added and grew; feature families and their milestones.
• Defect & resilience (fix, hotfixes, reverts, regressions) — recurring problem areas, notable incidents, and how the codebase hardened over time (trail's regression/bisect archaeology is the native engine).
• Improvement & refactor (refactor/perf/style, kaizen-type change) — the quality / performance / architecture-hygiene story.
• Decisions (direction changes, architecture pivots, dependency/framework swaps, conventions adopted) — reconstructed into an ADR-style decision log, each with what was decided · why · why-not-the-alternative (observed-if-stated / inferred / UNKNOWN).

Third axis — deep-dive lenses (the source of file-split depth): orthogonal to eras (time) and storylines (theme), the lens set re-reads the whole history through a specialist discipline and writes each read to its own file. Default lens set (each an era-by-era evolution narrative + key-commit ledger + current-state + open-risks, grounded like everything else):

• security — vulnerability fixes, dependency/CVE responses, authz/authn changes, the hardening arc.
• domain-design — domain model / entity / schema / ubiquitous-language evolution; how the domain understanding deepened.
• architecture — module boundaries, layering, dependency-structure and build-topology evolution; links into the decision log.
• performance — perf work, regressions fought, caching/indexing/optimization arc.
• design-ux — UI/UX surface evolution, design-system adoption, interaction/a11y trajectory.
• issues — the repo's unfinished business: recurring defect hotspots, revert/regression loops, long-lived TODO/FIXME accretion, stalled or abandoned threads, deferred/UNKNOWN decisions and accumulated tech debt — each issue cited to commit evidence and severity-tiered, an open-problems register mined from the history (not a speculative wishlist).

Read when: Executing the chronicle Recipe. Authored to reference/recipe-contract.md (all 8 elements).

What chronicle is for

A repository has accumulated hundreds or thousands of commits and no document explains its history — the phases it went through, the features that grew, the bugs it fought, the improvements it absorbed, the decisions that turned it, the shape of its evolution. A new team member wants to understand "how did we get here"; a lead wants a retrospective grounded in what actually happened; an auditor or acquirer wants the arc of a codebase they didn't watch grow; a maintainer wants a narrative changelog richer than git log; an architect wants the decision history — what was chosen, and why-not-the-alternative — that no one wrote an ADR for. The deliverable is a named Chronicle, every element grounded in a commit SHA, tag, or PR — see Output — Chronicle for the full enumeration.

chronicle exists because reconstructing a repo's history into a coherent narrative has a method distinct from the single-agent history tools. trail investigates one regression via bisect/blame; launch reports one period's PR activity; tome turns one diff into a teaching doc; none of them read the full history, cluster it into eras, excavate the turning points, and synthesize a grounded arc + timeline document. That is exactly a controlled multi-agent protocol: scope the repo + window + audience → survey the quantitative shape → segment into eras → excavate the turning points → synthesize the arc → deep-dive each lens into its own file → draw the timeline → author the document set → verify every claim is grounded.

Grounded-by-construction (doc-grade discipline): every era boundary, turning point, metric, and stated rationale traces to a commit SHA / tag / PR at a pinned HEAD. What a commit changed (from its diff/message) is observed (high confidence, cited); why it happened is inferred (marked, evidence-linked) unless the commit/PR body states it; where the record doesn't reveal the answer, the recipe writes UNKNOWN, never a plausible fabrication (doc-quality-protocol W4-W6). A turning point with no commit behind it, or a causal claim the git record doesn't support, is a defect — not a helpful guess.

People-neutral by contract (inherited from trail/launch): the Chronicle narrates changes and decisions, not individuals. Contributor data appears only as aggregate era context ("solo author → small team", "contributor count grew ~3×") — never a leaderboard, ranking, or per-person productivity judgment. This is a hard rule, not a preference (see Failure Modes Prevented).

Default Mode: AUTORUN (with a SCOPE gate)

chronicle writes no product code and ships nothing executable (read-only over git; writes only the doc under docs/history/), so it runs autonomously by default — but a history read starts with an ambiguous boundary (which repo/path, how far back, at what granularity, for whom), so the SCOPE gate is contract-level: the resolved repo/path + time window + granularity + lens set + audience + artifact set is confirmed before the expensive survey/excavation fan-out. Unlike spec/delve this is a scope/blast-radius gate, not a knowledge-juncture dialogue — chronicle is a comprehension recipe, not a dialogue recipe. The one optional human touchpoint beyond it is the Mode-conditional intent confirmation in EXCAVATE/SYNTHESIZE (GUIDED/INTERACTIVE only): a lightweight validation of an inferred turning-point rationale by someone who was there — still not a dialogue, skipped under headless AUTORUN. Escalate to GUIDED (confirm-before-launch) when the history is large (default > 1500 commits) or spans multiple repos. There is no destructive-action gate (read-only over git; writes only the document set under docs/history/<slug>/, or docs/history/<slug>.md with lenses=none).

Scope resolution

• chronicle — full-history summary of the current repo, first commit → HEAD. The default form.
• chronicle since=<tag|date|sha> — bounded window (e.g. since=v1.0.0, since=2026-04-01): the history since a release/date/commit, for release-cadence retrospectives or "what changed this cycle" at narrative altitude (richer than release notes).
• chronicle <path> — scope to a subtree/component's history (git log -- <path>): the evolution of one module, not the whole repo. The temporal analog of scoping cartograph to one feature.
• chronicle repos=a,b,c — multi-repo: survey + excavate each repo's history in parallel (hub-spoke), then synthesize one cross-repo timeline (aligned on shared tags/dates). Defaults to confirm-before-launch.
• chronicle lenses=<set> — control the deep-dive lens set (e.g. lenses=security,performance for a focused pair; lenses=none to skip DEEPEN and ship a single-file overview-only Chronicle). Default: all six (security · domain-design · architecture · performance · design-ux · issues), confirmed at the SCOPE gate.
• chronicle resume — re-enter from the last checkpoint (see Resume).

File layout: with any lens in scope (the default), the Chronicle is a document set at docs/history/<slug>/ — README.md (the overview) + lenses/<lens>.md (one file per in-scope lens). With lenses=none, the legacy single file docs/history/<slug>.md.

Granularity (set in SCOPE, calibrates SEGMENT): eras (default — cluster into thematic phases) · releases (tag-anchored — one segment per release) · periodic (monthly/quarterly buckets). Audience (calibrates the doc's altitude, doc-quality W1-W3): onboarding "how-did-we-get-here" · retrospective · narrative changelog / release story · architecture-decision archaeology · due-diligence/audit.

History-integrity note: chronicle grounds on the git record as it exists. A squash-merge workflow, a rebase-heavy history, an Initial commit that imports a pre-existing codebase, subtree/vendored merges, or a shallow clone create blind spots — real evolution the record flattened or omits. These are detected in SURVEY and recorded as history-integrity gaps, never silently narrated over (see VERIFY).

Phase contract

SCOPE → SURVEY → SEGMENT → EXCAVATE → SYNTHESIZE → DEEPEN → DISTILL → DIAGRAM → DOCUMENT → VERIFY

Judgment/comprehension throughout — Claude-owned (Trail/Launch/Tome/Magi/Atlas?/sentinel?/lens?/bolt?/palette?/flux?/saga?/Canvas/Scribe/Judge); there is no code-gen phase, so no Codex routing for production. The one exception is VERIFY: the grounding gate may route its sampled-claim check to a second engine for prior-diversity on high-stakes chronicles — verification is not code generation (see Phase 10). SEGMENT + EXCAVATE are the distinctive core (the analog of cartograph's CORRELATE): carving the history into eras (time) × storylines (theme) and digging into why the direction changed — the value a single history tool can't produce. SEGMENT + EXCAVATE + SYNTHESIZE each work both axes (era + thread). DEEPEN works the third axis (lenses): per-discipline deep-dive files that reuse the era skeleton without re-reading the whole history. DISTILL is the deepest, most inferential layer — it reads the project's implicit ethos / worldview off the patterns in the synthesized history (the interpretive read, held to the recipe's strictest grounding discipline). Story-ness comes from the weave (eras × storylines); meaning-ness comes from DISTILL.

Phase 1 — SCOPE (resolve repo/path + window + granularity + audience + pinned HEAD)

Establish what history to read, how far back, at what granularity, for whom, and at which revision before reading it — an unbounded "summarize everything" is the recipe's first failure mode (engine calls: see Chain template). Produce a scope sheet:

• the repo/path set (+ each repo's role for multi-repo) + the pinned HEAD SHA + read timestamp — the baseline the Chronicle is grounded against, so it can state "accurate as of <sha> read at <ts>" and staleness is later detectable;
• the time window (first-commit / since=… / explicit range);
• the granularity (eras · releases · periodic);
• the storyline set (which theme threads to trace — default all four: feature-lineage · defect-&-resilience · improvement · decisions; the audience may prioritize one, e.g. decision-archaeology → decision thread deep, others summarized) — the theme axis, orthogonal to eras;
• the lens set (which deep-dive files to produce — default all six: security · domain-design · architecture · performance · design-ux · issues; lenses=… narrows, lenses=none skips DEEPEN) — the third axis, orthogonal to both;
• the audience (onboarding · retrospective · changelog · decision-archaeology · audit) — calibrates altitude + glossary depth in DOCUMENT (doc-quality W1-W3);
• the intended artifact set (era timeline diagram · storyline timelines · decision log · lens deep-dive files (DEEPEN; default on — the file-split depth layer) · ethos / philosophy inference (DISTILL; default on — skip only for a quick factual timeline) · velocity/composition charts · turning-point ledger · narrative arc — default all);
• the doc outline;
• a one-line history-integrity note (squash/rebase/import/shallow flags from Trail) seeded for VERIFY.
• SCOPE gate (contract-level; AUTORUN cannot skip): present the scope sheet (3-7 lines: repo/path + pinned HEAD, window, granularity, storyline set, lens set, audience, artifact set). The user confirms/corrects before the survey/excavation fan-out. Summarizing the wrong window or granularity — or fanning five lens deep-dives out over the wrong scope — is the expensive mistake this gate prevents. > 1500 commits or repos ≥ 2 → confirm-before-launch (may escalate to GUIDED).
• Draft init: on confirmation, write docs/history/<slug>/README.draft.md (status draft, scope sheet filled incl. pinned HEAD + lens set + audience; lenses=none → docs/history/<slug>.draft.md). See Resume.

Phase 2 — SURVEY (the quantitative shape — cheap, whole-history)

Read the shape of the whole history without deep-reading every commit — this is the skeleton the narrative hangs on and the source of both candidate era boundaries and the storyline threads, via Launch (volume/composition/tags/DORA) + Trail (churn/hotspot timeline, merge/revert density) — engine calls: see Chain template. Cheap aggregation only (git log --stat/--shortstat/--numstat, --grep by type, tag list, name counts) — no per-commit deep read yet. Distinguish substantive commits from noise (merges, version bumps, formatting, reverts) so velocity reflects real work. Thread seeding: the type composition is the raw material for the storylines — bucket commits into candidate thread pools (feat→feature-lineage, fix/revert/hotfix→defect-&-resilience, refactor/perf/style→improvement, and message/tag heuristics for direction/dependency changes→decisions). This is cheap --grep/trailer classification, not a deep read — the pools are candidates EXCAVATE later samples. Lens seeding (same cheap pass): bucket commits into candidate lens pools via path/keyword heuristics — auth/crypto/token/dependency-bump/CVE → security; entity/model/schema/migration → domain-design; module moves/layering/build-topology/framework swaps → architecture; perf/cache/index/benchmark → performance; UI components/styles/interaction/a11y → design-ux; revert/hotfix loops, repeated fixes on the same area, TODO/FIXME/deprecation markers, long-dormant threads → issues — candidates DEEPEN later samples, never a deep read here. Output: the history shape — a velocity/composition/churn timeline + candidate era boundaries (velocity inflection points, tag clusters, hotspot shifts, composition pivots e.g. feat-heavy → fix-heavy) + candidate thread pools (per-storyline commit candidate sets) + candidate lens pools (per-lens commit candidate sets) + an aggregate contributor-count trend (people-neutral: counts, not names/rankings).

Phase 3 — SEGMENT (carve the history — eras × storylines — the distinctive phase)

The first distinctive phase: carve the continuous history along both axes.

• Time axis — eras: Magi clusters SURVEY's candidate boundaries + tag/theme signals into a small set of named eras (each named by its dominant theme, e.g. "Bootstrapping", "Rapid feature expansion", "Hardening & refactor", "Stabilization"); Trail confirms each boundary sits on a real inflection, cited (engine calls: see Chain template). Each era carries: a span (first→last commit SHA + dates), a theme name, a one-line character, and the candidate turning point(s) on its boundary. Prefer 3-7 eras (too many = periodic bucketing in disguise; too few = loses the arc).
• Theme axis — storylines: Magi defines, from SURVEY's candidate thread pools, the storyline set in scope (default feature-lineage · defect-&-resilience · improvement · decisions) and sketches each one's shape across the eras — when it was active, dormant, or dominant. Each storyline carries: its type, a one-line premise (what this thread is about in this repo), and the candidate beats (the notable commits per era from its pool — feature milestones, notable fixes/incidents/regressions, key refactors, decision commits). A storyline that never fires (e.g. no meaningful perf work) is recorded as absent, not fabricated.
• The weave: the era set × storyline set forms an era×thread skeleton — for each (era, storyline) cell, which beats fired. This skeleton is what makes the final document a story (acts × plot lines) rather than a flat log.
• Output: the two-axis structure — the era set + the storyline set + the era×thread weave skeleton, all cited to SURVEY signals (deep-read deferred to EXCAVATE).

Phase 4 — EXCAVATE (turning points + thread beats & the why — the distinctive core, parallel)

The headline phase: deep-read only the selected commits (+ their diff/message/PR) along both axes and reconstruct what changed and why. Bounded by construction — deep-read the turning-point set (era boundaries: ≤ top-N per era, N=3 by impact) plus the thread-beat set (per storyline: ≤ top-M per era, M=3 notable commits from its SURVEY pool), not every commit — the two caps together are the cost governor. Per selected commit, in parallel (hub-spoke, no shared mutable state per _common/PARALLEL.md): Trail does code archaeology (what the diff changed, blame/follow, defect beats get bisect/regression lineage); Tome extracts intent & decision from the message/PR body where the record states it; Atlas shapes decisions-storyline beats into ADR-style entries (context · decision · alternatives-considered · consequences) — engine calls: see Chain template.

• Observed vs inferred discipline: what changed is observed (cited to the SHA); why is inferred and labeled unless the commit/PR body states it (then it's observed-rationale, cited). Where neither shows intent, write UNKNOWN — never invent a motive for a commit (doc-quality W4-W6). The why-not-the-alternative of a decision is almost always inferred or UNKNOWN unless the PR discussion is in-repo — label it honestly rather than inventing a rejected option.
• Owner-ratification (Mode-conditional checkpoint; not contract-level): under GUIDED/INTERACTIVE — or whenever someone who was there is in the loop — present the inferred/UNKNOWN rationales (turning points + decision beats, ≤ 5-7 lines) for ratification. A ratified item becomes confirmed-by-owner (promoted out of inferred/UNKNOWN) — the cheapest, highest-value grounding upgrade chronicle has, because a participant frequently knows the "why" (and the "why-not") the git record doesn't show. A validation checkpoint, not dialogue — skipped under headless AUTORUN; never fabricate a confirmation.
• Output (two ledgers): the turning-point ledger (per turning point: SHA/tag/PR · era boundary · what changed · why · impact) + the thread-beat ledger (per storyline, per era: the beats, each cited, forming the storyline's mini-arc) + the decision log (the decisions storyline as ADR-style entries).

Phase 5 — SYNTHESIZE (the arc + the storylines — weaving both axes)

Magi weaves the two-axis structure into the story: (a) the overall arc — the through-line from first commit to HEAD, the shifts in direction, how the current state (from SCOPE's Lens anchor) is the sum of these moves; and (b) each storyline's mini-arc — feature-lineage (how capabilities accreted), defect-&-resilience (the problems fought and how it hardened), improvement (the quality/perf trajectory), decisions (how the decision log's entries chain into a direction). The story is the interplay: e.g. "the fix-heavy era was the resilience storyline's climax, triggered by the feature storyline's rapid-expansion era". Saga optionally shapes the arc + storylines into a readable narrative (a story frame, e.g. Story Spine) only when the audience is onboarding/retrospective/changelog and a compelling read adds value — engine calls: see Chain template. Narrative discipline (guards the just-so-story failure mode): the arc and every storyline are a lens on the evidence, not fiction — Saga may order and phrase, never invent causation or impose a cleaner story than the commits support. Every arc/storyline beat still resolves to an era / turning-point / thread-beat already grounded in Phase 3-4; a beat with no evidence behind it is cut. Completeness self-check: does the synthesis account for every era (incl. any low-activity "quiet" era), every in-scope storyline (incl. any recorded absent), and every history-integrity gap from SURVEY? Gaps feed the VERIFY loop. Output: the woven narrative — the overall arc + each storyline's mini-arc + how they interconnect + the residual gaps/UNKNOWNs, all evidence-linked.

Phase 6 — DEEPEN (per-lens deep-dive files — the third axis, parallel, capped)

Beyond the overview, re-read the history through each in-scope lens (default: security · domain-design · architecture · performance · design-ux · issues) and produce a per-lens dossier — the source of each split file in DOCUMENT. Runs after SYNTHESIZE so every lens inherits the era skeleton and the woven narrative as its frame (no lens re-derives eras). Per lens, in parallel (hub-spoke, one dossier per lens, no shared mutable state per _common/PARALLEL.md):

• Selection (cost-capped): from SURVEY's candidate lens pool, deep-read ≤ top-K commits per era (K=3) by lens-relevance/impact; reuse any overlapping EXCAVATE ledger entry verbatim (a turning point that is also a security fix is not deep-read twice).
• Engines per lens — Trail[lens-scoped archaeology on the selected commits] paired with the discipline specialist:
  • security → Sentinel[read each fix/hardening change for what it closed; classify the hardening arc; dependency/CVE response posture]
  • domain-design → Lens[how the domain model/entities/language evolved; where the domain understanding visibly deepened or pivoted]
  • architecture → Atlas[boundary/layering/dependency-structure evolution; cross-link each architectural shift to its decision-log entry]
  • performance → Bolt/Tuner[the optimization arc — what was measured, what was fixed, what regressed and returned]
  • design-ux → Palette[UI/UX surface evolution, design-system adoption, interaction/a11y trajectory]
  • issues → Omen[the open-problems register — recurring defect hotspots and revert/regression loops (from the defect storyline + churn timeline), TODO/FIXME/tech-debt accretion, stalled/abandoned threads, deferred/UNKNOWN decisions; each issue: evidence pattern (cited) · current status (open/mitigated/unknown) · severity tier]. Input discipline: draws only on SURVEY pools + the EXCAVATE ledgers (already produced) — never on sibling lens dossiers, so DEEPEN's parallel isolation holds. Issues are mined, not invented: an issue with no commit-evidence pattern behind it is cut (same UNKNOWN-over-fabrication rule).
• Discipline (inherited from EXCAVATE): observed change vs inferred why vs UNKNOWN, every claim cited to a SHA/tag/PR; people-neutral. A lens whose pool is empty or trivial is recorded absent (a one-paragraph stub stating so) — never padded into a fake narrative.
• Output: per-lens dossiers — each: lens summary · era-by-era evolution · key-commit ledger (cited) · current state · open threads & risks · gaps/UNKNOWNs.

Phase 7 — DISTILL (infer the ethos & worldview — the deepest, most inferential read)

From the synthesized history (eras + storylines + decision log + turning points), infer the project's implicit ethos — the values, principles, conventions, and worldview the evolution reveals but no one wrote down. This is what makes the Chronicle explain not just what happened but who this project is. Magi[multi-perspective deliberation over the decision log + storyline trajectories — Logos: the consistent technical trade-off resolutions; Pathos: what the project cares about for its users/domain; Sophia: the enduring principles vs the phase-specific tactics] + Flux?[reframe — surface a non-obvious worldview the literal reading misses]. Dimensions distilled (each a pattern-grounded inference, never a fact):

• Design philosophy / architectural values — what the code consistently optimizes for (e.g. simplicity > flexibility; explicit > clever; composability), read from repeated refactor direction + what reverts rejected.
• Value hierarchy (revealed priorities) — when two goods conflicted, which won and how consistently (e.g. "readability beat raw performance in 7 of 9 conflicting decisions") — read from the decision log.
• Conventions / operating ethos — commit discipline, testing posture, dependency philosophy (minimal vs rich), how breaking changes are treated.
• Product thesis / worldview — what the project believes about its domain, read from feature-lineage direction + what was deliberately not built or was removed (a worldview is defined as much by refusals as by features).
• Ethos evolution — did the philosophy shift across eras? The ethos has its own arc (e.g. "move-fast → stability-first"); tie each shift to the era where it turned.
• Stated vs revealed (optional): if declared-values docs exist (README / CONTRIBUTING / CLAUDE.md / manifesto), Lens[extract the stated values] and DISTILL contrasts revealed-behavior against stated-intent — surfacing alignment and divergence ("states 'minimal dependencies' but the history shows steady dependency growth"). The revealed ethos (from commits) is primary; the stated ethos is a comparison point, never a substitute.

Inference discipline (the recipe's most speculative layer — strictest grounding):

• Pattern-grounded, not point-grounded: each tenet cites a pattern of ≥ 3 independent events (commits / decisions / reverts) across the history. A one-commit "value" is not a value — it's an anecdote, and is cut.
• Mandatory counter-evidence sweep: for every tenet, actively find and record where the project violated it. A tenet with strong counter-evidence is downgraded or dropped — no cherry-picking.
• Confidence tier per tenet: well-supported (consistent pattern, little counter-evidence) · tentative (real support, notable exceptions) · speculative (suggestive but thin). The ethos is always labeled as interpretation, never asserted as the project's official philosophy.
• Adversarial refutation (_common/ADVERSARIAL_REFUTATION.md, refute-polarity — here load-bearing, not the light pass EXCAVATE uses): a 2-3 skeptic panel tries to refute each tenet — real value, or pattern-matching noise, or the analyst's own values projected onto the repo? Default-to-refuted on evidence claims. A tenet that cannot survive is dropped or demoted to speculative.
• Owner-ratification (Mode-conditional): the invoker who knows the project's actual values can ratify, correct, or reject each tenet (inferred → confirmed-by-owner, or corrected). The highest-value grounding upgrade for the softest claims — a participant's correction outranks any pattern inference.
• Output: the Ethos — a small set (default ≤ 5-7) of tenets, each with: statement · confidence tier · supporting evidence pattern (cited ≥ 3) · counter-evidence · refutation survival · optional owner-ratification — plus the ethos-evolution note (how the philosophy shifted across eras) and, when run, the stated-vs-revealed contrast.

Phase 8 — DIAGRAM (the visual timeline)

Canvas renders the visuals from the two-axis model (Mermaid by default; timeline/gitgraph/gantt/xychart per canvas conventions) — multiple types, each a different altitude:

• Era timeline — the headline artifact: a timeline/gantt of the named eras with their spans + turning points marked (the at-a-glance history overview).
• Storyline timelines / thread×era matrix — the theme axis: per-storyline timeline swimlanes (feature-lineage · defect-&-resilience · improvement · decisions) laid against the eras, or a compact era×thread matrix showing which beats fired in each cell — the visual that makes the weave legible (which act each plot line peaked in).
• Velocity / composition chart(s) — an xychart of commit velocity over time and/or conventional-commit type composition per era (from SURVEY — this doubles as the storylines' quantitative backdrop: feat vs fix vs refactor share per era).
• Milestone gitgraph — tags/releases and the turning-point commits on the branch line, where a tag history exists.
• Decision log — the decisions storyline as a chronological table (rendered in DOCUMENT), each row a reconstructed ADR-style entry.
• Ethos-evolution (when DISTILL ran) — a compact visual of how the tenets held/shifted across the eras (a tenet×era matrix or an annotated note on the era timeline), so the philosophy's own arc is legible; each cell tied to the tenet's evidence.
• Per-lens era strip (when DEEPEN ran) — optionally, a compact per-lens timeline (the lens's key commits across the eras) embedded in that lens's file, from its dossier.
• Every diagram element is traceable to a model element (era / turning point / thread beat / lens dossier entry / tenet) which is itself cited; no era, milestone, storyline beat, or tenet the SEGMENT/EXCAVATE/DEEPEN/DISTILL phases didn't establish.

Phase 9 — DOCUMENT (the history document set — split files)

Scribe authors the Chronicle — pitched to the audience fixed in SCOPE: an onboarding "how we got here", a retrospective, a narrative changelog, and an audit doc differ in altitude and glossary depth — embedding the DIAGRAM artifacts (engine call: see Chain template). Follows reference/doc-quality-protocol.md (reader contract W1-W3, grounding W4-W6, coherence W7-W9, summary-first readability W10-W11).

File split contract: with any lens in scope (the default), the deliverable is a document set at docs/history/<slug>/:

• README.md — the overview (the outline below). The overview stays an overview: for each lens it carries a 2-4 line summary + a link to the lens file, never the full depth (no wholesale duplication — W7-W9 coherence across files).
• lenses/security.md · lenses/domain-design.md · lenses/architecture.md · lenses/performance.md · lenses/design-ux.md · lenses/issues.md — one file per in-scope lens, authored from its DEEPEN dossier: lens summary (summary-first) → era-by-era evolution → key-commit ledger (cited table) → current state → open threads & risks → gaps/UNKNOWNs (the issues file swaps the middle for an open-problems register: per issue — statement · evidence pattern (cited) · first-seen/last-seen era · status · severity tier). An absent lens ships as its stub. Each lens file back-links to README.md and to the decision-log entries it touches.
• lenses=none → the legacy single file docs/history/<slug>.md (overview outline only).

Overview (README.md) outline:

• Overview — what the repo is today + the era-timeline diagram + the one-paragraph arc, summary-first.
• The arc — the narrative through-line (SYNTHESIZE), first commit → HEAD.
• Eras — per era: span (SHA range + dates) · theme · character · the velocity/composition shape · aggregate team context (people-neutral).
• Storylines — one subsection per in-scope thread, each a mini-arc pitched to the audience:
  • Feature lineage — how capabilities were added and grew (feature families, their milestone commits/tags).
  • Defect & resilience — recurring problem areas, notable incidents/regressions and the fixes that closed them, how the code hardened.
  • Improvement — the refactor/perf/quality trajectory.
  • Decisions — narrative pointer into the decision log below.
  • (An absent storyline is stated as such, not padded.)
• Deep-dives (lens index) — one entry per in-scope lens (security · domain-design · architecture · performance · design-ux · issues): a 2-4 line summary + link to lenses/<lens>.md; absent lenses marked.
• Decision log — the ADR-style table (from EXCAVATE): per decision, context · decision · alternatives-considered · consequences, each field labeled observed/inferred/confirmed-by-owner/UNKNOWN + citation (SHA/tag/PR). The artifact the architect audience comes for.
• Philosophy & worldview (inferred) — from DISTILL, clearly framed as interpretation: the tenets (design philosophy · value hierarchy · conventions · product thesis), each with its confidence tier · evidence pattern · counter-evidence · refutation survival; the ethos-evolution across eras; and, when run, the stated-vs-revealed contrast. This section answers "who is this project, and what does it believe?" — the deepest read, and the one most explicitly labeled as inferred, never asserted as the project's official stance.
• Turning points — the ledger: per turning point, what changed (observed) · why (labeled) · impact · citation.
• By the numbers — the metrics shape (velocity, composition, churn hotspots over time), people-neutral aggregates.
• Open questions & gaps — UNKNOWN rationales, history-integrity gaps (squash/rebase/import/shallow blind spots), not-excavated long-tail (turning-point + thread-beat caps) — recorded honestly. (The recipe's own blind spots — distinct from lenses/issues.md, which registers the repo's open problems.)
• Glossary — domain/era terms.

Phase 10 — VERIFY (grounding gate — the recipe's quality bar)

The output is only as good as its grounding. Producer ≠ verifier (the checker is not Scribe/Canvas/Saga, nor the lens's own DEEPEN specialist):

• Grounding check: Judge/Attest[sample the era boundaries, turning-point claims, storyline beats, lens dossier claims, decision-log entries, arc beats, and metrics → each must resolve to a real commit SHA / tag / PR at the pinned HEAD]. A fabricated turning point or storyline beat, an era boundary on no real inflection, an invented rejected alternative in the decision log, an inferred motive presented as fact, or a metric that doesn't match git log fails the gate. This is chronicle's core discipline (the analog of clone's differential-parity): claims are evidence-bound, anything unverified is labeled. confirmed-by-owner rationale is exempt from citation resolution but recorded as owner-attested, not record-grounded.
• People-neutrality check: the doc contains no ranking / leaderboard / per-person productivity claim — contributor data is aggregate era-context only. A violation fails the gate (hard rule).
• Narrative-fidelity check: every arc beat maps to a grounded era/turning point; no beat asserts causation the record doesn't support (guards the just-so-story failure).
• Ethos-grounding check (DISTILL — the softest claims get the hardest check): every tenet cites a pattern of ≥ 3 independent events, records its counter-evidence sweep, carries a confidence tier, and survived adversarial refutation; no tenet is asserted as fact (all labeled inferred / confirmed-by-owner). A tenet grounded in a single commit, missing its counter-evidence, cherry-picked past its exceptions, or presented as the project's stated philosophy fails the gate.
• Cross-engine grounding (option — prior-diversity): on a high-stakes chronicle (audit/due-diligence deliverable, multi-repo, or > 1500 commits), route the sampled-claim check to a second engine so the verifier's priors differ from the Claude producer's (same discipline as _common/ADVERSARIAL_REFUTATION.md). Verification is not code generation.
• Doc Quality Gate (W12): the Chronicle passes the reader-contract / coherence / grounding checks of reference/doc-quality-protocol.md.
• Coverage check: every era appears in the doc; every in-scope storyline is present-or-marked-absent (no silently dropped thread); every in-scope lens file exists and is present-or-marked-absent (no silently dropped lens); every history-integrity gap is recorded; the excavated turning-point set (top-N per era), thread-beat set (top-M per storyline per era), and lens set (top-K per lens per era) are stated with their caps so the not-excavated long-tail is explicit, never implied-complete.
• Cross-file consistency check (lens split): every lens-index link in README.md resolves; no lens file contradicts the overview, the decision log, or another lens file on a shared commit/claim; the overview does not wholesale-duplicate lens depth (W7-W9 across the file set).
• Coverage / grounding loop: if the gate finds fabricated/unsupported elements, a broken metric, a people-neutrality violation, an ungrounded/refuted tenet, or missing coverage, loop back to EXCAVATE (missing/ungrounded turning point), SEGMENT (mis-drawn era boundary), DEEPEN (ungrounded/missing lens claim or dropped lens), or DISTILL (ungrounded / cherry-picked / refuted tenet). Termination bound: loop ≤ 3 cycles (default 3) (recipe-contract §2); exit on ACCEPT/target-met (fully grounded + coverage-complete + people-neutral) · diminishing-returns (Δ < ε) · cap-reached · BLOCK (a claim is unverifiable without history the repo doesn't retain — e.g. squashed-away detail). On any non-ACCEPT exit, finalize the Chronicle with the UNKNOWNs / integrity gaps / residual gap explicit — never silently ship an ungrounded history, never loop past marginal value.
• Finalize: promote the draft set → docs/history/<slug>/ (README.md + lenses/*.md; lenses=none → docs/history/<slug>.md) with diagrams embedded/linked and the pinned HEAD stamped in a provenance attestation (<sha>, read at <timestamp>) in the README (lens files inherit it by back-link).

Termination bound

The one bounded loop is Phase 10's grounding/coverage loop — cap, exit vocabulary, and loop-back targets are defined there (recipe-contract §2). Every other phase is single-pass: SURVEY/EXCAVATE fan out per era / repo / turning point / thread beat, DEEPEN per lens, DISTILL runs a bounded refutation panel per tenet, but none of them loop.

Confirm / safety gate

Default Mode AUTORUN, with two touchpoints, both specified where they fire: the contract-level SCOPE gate (Phase 1 — the scope sheet is confirmed before the survey/excavation fan-out; > 1500 commits or repos ≥ 2 escalates it to confirm-before-launch) and the Mode-conditional owner-ratification checkpoints (Phase 4 for turning-point rationales, Phase 7 for ethos tenets — skipped under headless AUTORUN, never auto-confirmed). No destructive-action gate: chronicle is read-only over git and writes only under docs/history/ (same posture as cartograph/delve/charter).

Resume

Checkpoint-resume (recipe-contract §4): each phase's output — as defined in § Phase contract — is persisted at its boundary to the draft (docs/history/<slug>/README.draft.md, or docs/history/<slug>.draft.md with lenses=none) with a current-phase marker. chronicle resume reads the draft, summarizes progress in 3-5 lines, and continues from the last successful boundary — never silently restarts from SCOPE. On VERIFY-ACCEPT the draft is promoted (Phase 10 Finalize) and the .draft.md archived/removed.

Output — Chronicle

NEXUS_COMPLETE with the base ## Nexus Execution Report plus the named Chronicle. Each element's content and shape is defined in the phase named after it — the history document set itself is authored to the Phase 9 DOCUMENT outline, which is canonical and not restated here:

• Scope sheet (Phase 1) · Era timeline, diagram + prose (Phases 3 + 8) · Storylines (Phases 3-5 + 8) · Decision log (Phase 4) · Turning-point ledger (Phase 4) · Narrative arc (Phase 5) · Ethos (Phase 7) · By the numbers (Phase 2) · Lens deep-dives, one lenses/<lens>.md per in-scope lens (Phases 6 + 9) · Open questions & gaps (Phase 9).
• History document set — the full Chronicle at docs/history/<slug>/ (README.md overview + lenses/*.md; lenses=none → single docs/history/<slug>.md), authored to the Phase 9 outline (DOCUMENT).
• Provenance attestation — the Phase 10 VERIFY result: sampled-claim resolution at the pinned HEAD (<sha>, read at <timestamp>), the people-neutrality / narrative-fidelity / ethos-grounding check verdicts, cross-engine verifier if used, loop trajectory + exit reason.
• Follow-ups — recommended next recipe per gap (cartograph to map how the current system is architected · delve to evolve a feature whose history the chronicle surfaced · anneal to brush up a design weakness an era introduced · charter to turn "where we are" into a delivery plan · tome to deep-teach one turning-point diff).

Failure Modes Prevented

Boundaries / vs neighbors

• vs cartograph — the family sibling: spatial-structure-snapshot (code-grounded) vs chronicle's temporal-evolution-arc (SHA-grounded). chronicle → cartograph for "how it's built now". Full detail: see Decision tree.
• vs delve — delve excavates one feature via dialogue for evolution directions (forward, INTERACTIVE, no docs); chronicle reconstructs the whole history autonomously into a timeline document (backward). chronicle → delve when a turning point surfaces a feature worth evolving. Full detail: see Decision tree.
• vs charter — charter plans forward work from a repo; chronicle produces a backward history. chronicle → charter when "where we are" becomes the input to a plan. Full detail: see Decision tree.
• vs pdm (agent) — pdm reconciles planned scope vs implemented code (present-tense gap report); chronicle reconstructs the past from git. Full detail: see Decision tree.
• vs launch (agent) — Launch reports one period's PR data; chronicle clusters the whole history into eras + turning points + arc, using Launch as its SURVEY engine. A period report → launch direct. Full detail: see Decision tree.
• vs tome (agent) — tome teaches one diff deeply; chronicle narrates the whole arc, using Tome to extract intent at each turning point. One change → tome direct. Full detail: see Decision tree.
• vs trail (agent) — trail investigates one regression via bisect/blame; chronicle orchestrates Trail across the whole timeline. A "which commit broke X" hunt → trail direct. Full detail: see Decision tree.
• vs atlas (agent) — atlas authors forward ADRs/RFCs for decisions being made now (a decision record for a choice in front of you). chronicle reconstructs past decisions from the git history into a decision log, labeling why/why-not as observed/inferred/UNKNOWN — it uses Atlas as its decision-log engine, but the direction is backward (recover) not forward (author). A new ADR for a live decision → atlas direct; the decision history mined from commits → chronicle.
• vs magi (agent) — magi deliberates a decision (Logos/Pathos/Sophia → a Go/No-Go or a recommendation for a question in front of you). chronicle's DISTILL uses Magi as an engine to infer a descriptive ethos model — the values the history reveals — not to decide anything. magi answers "what should we choose?"; chronicle-DISTILL answers "what has this project, by its actions, actually valued?" (backward, descriptive, evidence-pattern-grounded, refutation-gated). A live judgment call → magi direct; the project's revealed philosophy from its history → chronicle.
• vs release notes / changelog — a changelog lists what shipped per version (flat, per-release). chronicle explains why the repo evolved the way it did (narrative, era-level, with causation and an arc). chronicle since=<tag> produces a narrative changelog when a richer-than-flat story is wanted.

Decision tree:

Want to understand a repo's PAST from its commit history (no code changes)?
  NO  → how the system is architected NOW (across repos)?  → cartograph
        evolve ONE shipped feature (dialogue)?              → delve
        plan the work next / design a team?                 → charter
        what's built vs planned (present status)?           → pdm
  YES → one period's PR report / release notes?             → launch direct (minimum viable chain)
        one diff/PR to teach deeply?                        → tome direct
        which commit caused X / one archaeology question?   → trail direct
        the WHOLE history → eras + turning points + arc + timeline doc?
              → chronicle
                    chronicle                → full history, first commit → HEAD
                    chronicle since=<tag|date> → bounded window (narrative changelog)
                    chronicle <path>         → one component's history
                    chronicle repos=a,b,c    → cross-repo timeline (confirm-before-launch)
                    a mapped-now follow-up   → chronicle → cartograph
                    a feature to evolve       → chronicle → delve

Scale

4-21 agents × the grounding loop (≤ 3 cycles). The low end is a scoped chronicle <path> with lenses=none, a single-storyline focus (e.g. decision-archaeology only), or a small-history repo with DISTILL skipped (SCOPE → Launch+Trail survey → Magi segment → Trail+Tome on a handful of turning points + thread beats → Magi weave → Canvas → Scribe → one grounding check ≈ 5-7 agents). The high end is a multi-repo or > 1500 commit full history, all four storylines, all six DEEPEN lenses (Trail + each lens's discipline specialist per Phase 6 ≈ +6-12 agents), Atlas decision-log shaping, DISTILL (Magi deliberation + Flux reframe + a 2-3 skeptic refutation panel per tenet), Saga narrative, the full diagram set, and a grounding loop. Cost scales with era count × (turning-points + storylines × beats + lenses × K) per era — the EXCAVATE + DEEPEN fan-out — plus the DISTILL tenet×refutation pass (bounded: ≤ 5-7 tenets × 2-3 skeptics) — not commit count — SURVEY is cheap aggregation, EXCAVATE is capped (top-N turning points per era + top-M beats per storyline per era), and DEEPEN is capped (top-K commits per lens per era, EXCAVATE overlaps reused), so a 2000-commit repo and a 500-commit repo cost similarly at the same era/thread/lens budget. SCOPE (window + granularity + storyline set + lens set — narrowing to the audience's priority thread/lens is the biggest lever) and the top-N/top-M/top-K caps are the cost governors. Read-heavy, write-light; lighter than the execution recipes (no build/verify-code phases).

Shared protocols & Add-ons

• Shared: doc authoring & grounding → reference/doc-quality-protocol.md (W1-W12: reader contract, UNKNOWN-over-fabrication, coherence, summary-first, Doc Quality Gate). Evidence-bound claims / producer≠verifier → reference/autonomy-quality-protocol.md (Q9-Q11: independent verification, evidence-bound claims, Acceptance Provenance). Per-era/per-repo parallel isolation → _common/PARALLEL.md (hub-spoke, no shared mutable state across excavations). Diagram conventions (Mermaid timeline/gitgraph/gantt/xychart) → canvas skill. Contested inference → _common/ADVERSARIAL_REFUTATION.md — a light skeptic pass on high-stakes inferred causation in EXCAVATE, but load-bearing (refute-polarity, default-to-refuted on evidence claims) for every ethos tenet in DISTILL, where the whole layer is inference; also the prior-diversity basis for the optional cross-engine grounding check in VERIFY. Owner-ratification touchpoint (the Mode-conditional checkpoints only — turning-point rationales and ethos tenets) → reference/dialogue-protocol.md (checkpoint presentation, Provenance Gate — chronicle is otherwise a comprehension recipe, not a dialogue recipe).
• Add-ons: the six DEEPEN lens specialists (Sentinel · Lens · Atlas · Bolt/Tuner · Palette · Omen) are bound to their lenses in Phase 6, which is the sole owner of that mapping — they are add-ons only in the sense that a narrowed lenses= set drops the ones it excludes. Beyond DEEPEN: +Saga (narrative arc + per-storyline shaping in SYNTHESIZE, for onboarding/retrospective/changelog audiences), +Atlas (shape the decisions storyline into the ADR-style decision log in EXCAVATE — its native ADR/RFC capability; also anchor architectural turning points), +Flux (in DISTILL: reframe to surface a non-obvious worldview the literal reading misses), +Lens (anchor the current state in SCOPE so the arc has a known endpoint; and in DISTILL extract the stated values from README/CONTRIBUTING/CLAUDE.md for the stated-vs-revealed contrast), +Ripple (blast-radius annotation when a turning point is a precursor to a change the user plans next), +Attest (grounding/citation-conformance in VERIFY), +Sherpa (decompose a large multi-repo or periodic chronicle, or a per-storyline/per-lens pass, into independent sub-runs).

Chain template

SCOPE (Trail +Lens?) → ✓SCOPE-gate + draft-init → SURVEY (Launch + Trail) → SEGMENT ×2-axis (Magi + Trail) → EXCAVATE ∥per-turning-point ∥per-thread-beat (Trail +Tome +Atlas?, ✓owner-ratification) → SYNTHESIZE (Magi +Saga?) → DEEPEN ∥per-lens (Trail + the lens's discipline specialist) → DISTILL (Magi +Flux? +Lens?, ✓owner-ratification) → DIAGRAM (Canvas) → DOCUMENT (Scribe) → ⟲VERIFY (Judge/Attest) → promote docs/history/<slug>/ + pinned-HEAD attestation [NO CODE]

Each phase's inputs, caps, engine bindings, discipline rules, and outputs are canonical in § Phase contract; ∥ marks the parallel fan-outs (per turning point / thread beat / lens, hub-spoke per _common/PARALLEL.md). The ✓ markers are the SCOPE gate (Phase 1 — contract-level, AUTORUN cannot skip) and the two owner-ratification checkpoints (Phases 4 and 7 — Mode-conditional); ⟲ is the grounding/coverage loop (Phase 10 — loop ≤ 3, exit vocabulary and loop-back targets defined there). Resumable via chronicle resume from the draft's current-phase marker. Hands off to cartograph / delve / anneal / charter / tome per surfaced gap.