feat: publish reviewed architecture and ADR batch

Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a058f3-8ba0-7692-a042-9a870fc3d663
2026-08-31 21:34:23 +02:00 · 2026-08-31 21:34:23 +02:00 · 93608c1f17
commit 93608c1f17
parent 023badb512
120 changed files with 17791 additions and 727 deletions
--- a/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html
+++ b/build/adr/custodian-workplans-as-repo-artefacts/v1/index.html
@ -1,7 +1,7 @@
 <!doctype html>
 <html lang="en"><meta charset="utf-8">
-<meta name="policy-source-revision" content="4039c9d1c08c92014ecc0a65dda63cc73ba187bb">
-<meta name="policy-source-digest" content="64b11785b683cf21ba2aca18e3b8f3301d6070e6a022df6efc722597a8547334">
+<meta name="policy-source-revision" content="44500fc85cf29d8e9b2ee5c91994032ed3d04e5b">
+<meta name="policy-source-digest" content="183023ee57bae9c29e726fec5ee0361633fe3a2b182436a57869ae4b2a27af24">
 <title>Workplans and Work Items Are Repository Artefacts</title>
 <style>
 :root{
@ -191,108 +191,67 @@ a:focus-visible,.rail a:focus-visible{outline:2px solid var(--brass);outline-off
@media (prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}

 </style>
-<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-001</span> <span class="stat">accepted · accepted-1</span> <span>the-custodian</span> <span>reviewed 2026-02-28</span><span>generated from canonical source — do not edit</span></div><h1>Workplans and Work Items Are Repository Artefacts</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</code></p><p class="sub">Review due: 2026-08-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#workplan-file-convention"><span class="n">·</span>Workplan File Convention</a></li><li><a href="#rebuild-principle"><span class="n">·</span>Rebuild Principle</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives Considered</a></li><li><a href="#workplan-closure-protocol"><span class="n">·</span>Workplan Closure Protocol</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
-<p>Accepted.</p>
+<div class="wrap"><header><div class="eyebrow"><span>CUST-ADR-001</span> <span class="stat">accepted · accepted-2</span> <span>the-custodian</span> <span>reviewed 2026-08-31</span><span>generated from canonical source — do not edit</span></div><h1>Workplans and Work Items Are Repository Artefacts</h1><p class="sub">Source: <code>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b</code></p><p class="sub">Review due: 2027-02-28</p></header><div class="layout"><nav class="rail" aria-label="Sections"><ol><li><a href="#status"><span class="n">·</span>Status</a></li><li><a href="#context"><span class="n">·</span>Context</a></li><li><a href="#decision"><span class="n">·</span>Decision</a></li><li><a href="#workplan-closure"><span class="n">·</span>Workplan closure</a></li><li><a href="#consequences"><span class="n">·</span>Consequences</a></li><li><a href="#migration"><span class="n">·</span>Migration</a></li><li><a href="#alternatives-considered"><span class="n">·</span>Alternatives considered</a></li><li><a href="#related"><span class="n">·</span>Related</a></li></ol></nav><main><section id="status"><h2>Status</h2>
+<p>Accepted 2026-02-28.</p>
+<p>Amended 2026-08-31 to distinguish file-backed work records from hub-native records, identify the Forge default branch as the central projection baseline, and align identity, lifecycle, reconciliation, and closure with ADR-007, ADR-010, ADR-011, ADR-012, and the work-record standards. The central decision is unchanged.</p>
 </section>
 <section id="context"><h2>Context</h2>
-<p>During early State Hub development (v0.1–v0.4), workstreams and tasks were created directly in the PostgreSQL database via MCP bootstrap tools (<code>create_workstream</code>, <code>create_task</code>). This made the database the <strong>origin</strong> of work items — not a cache or index. The pattern was convenient for rapid bootstrapping but is architecturally wrong for a system built on the values of auditability, reversibility, and local-first sovereignty.</p>
-<p>The trigger for formalising this decision was the creation of the v0.5 workplan ("Dynamic Domains &amp; Multi-Repo") directly in the state-hub database without a corresponding file artefact in any repository.</p>
+<p>During early State Hub development, workstreams and tasks were created directly in PostgreSQL through bootstrap APIs. This made a database the origin of durable work rather than a projection of repository-owned artefacts. The pattern was convenient, but it made work difficult to audit, review, recover, and carry between generations of tooling.</p>
+<p>The original decision correctly moved durable workplans and their work items into repositories. It overstated the consequence, however, by saying that the entire Hub database and every item that matters for coordination must be reconstructible from repository files. Later decisions established two different persistence classes:</p>
+<ul><li><strong>file-backed records</strong>, whose durable meaning originates in a repository;</li><li><strong>hub-native records</strong>, such as append-only progress and runtime facts, whose durable meaning originates in the Hub.</li></ul>
+<p>Later decisions also established that a central projection reads the pushed default branch in Forgejo. An arbitrary workstation checkout is a workspace, not the shared baseline. Unpushed local work may be represented only as an explicit preliminary overlay.</p>
 </section>
 <section id="decision"><h2>Decision</h2>
-<p><strong>Workplans and work items MUST originate as Markdown files in the repository that owns them.</strong> The Custodian State Hub indexes and caches those artefacts but is never their origin.</p>
-<p>Formally: the state-hub must (theoretically, given sufficient compute and time) be able to <strong>rebuild its full representation</strong> of repositories, their workplans, tasks, decisions, and dependencies by reading only the files in the registered repositories. No information that matters for coordination should exist solely in the database.</p>
-<h3>Corollaries</h3>
-<ol><li><strong>Repository is authoritative.</strong> A workplan file is the canonical record. The state-hub database row is a materialized cache of that file.</li></ol>
-<ol><li><strong>Database is disposable.</strong> Dropping and re-creating the database from registered repository files must produce an equivalent state. The database is an operational convenience, not a primary store.</li></ol>
-<ol><li><strong>MCP bootstrap tools become index/sync tools.</strong> <code>create_workstream</code> and <code>create_task</code> are acceptable as convenience wrappers only if they write the file first and then register the row. Using them to write DB-only records violates this ADR.</li></ol>
-<ol><li><strong>The rebuild principle implies a sync mechanism.</strong> There must be a defined path (<code>make sync-workplans</code> or equivalent) by which the state-hub reads workplan files from registered repositories and upserts its database state.</li></ol>
+<h3>1. File-backed work originates in the owning repository</h3>
+<p>Workplans and their file-backed work items <strong>MUST originate as repository artefacts in the repository that owns the work</strong>. The Hub indexes and projects those artefacts but is not their origin.</p>
+<p>This includes the workplan, embedded tasks, declared dependencies, residual handoffs, and durable governed decision artefacts when those are represented as files. No authoritative field of a file-backed record may exist solely in a Hub database.</p>
+<p>The owning repository is identified by repository identity, not merely by a domain or topic. Domains and topics classify work; they do not own its source.</p>
+<h3>2. Authority is explicit per persistence class</h3>
+<p>Every record contract must declare whether the record is file-backed or hub-native. The same record must not be writable as authoritative in both places.</p>
+<ul><li>For a <strong>file-backed record</strong>, the repository artefact is authoritative and the Hub row is derived state.</li><li>For a <strong>hub-native record</strong>, the Hub is authoritative. Progress events, messages, token events, run history, and similar runtime facts are not made fictional repository records merely to satisfy a rebuild slogan.</li></ul>
+<p>The word <code>decision</code> is used by more than one subsystem. Architecture decisions and other governed decision artefacts remain files. A runtime decision event may be hub-native only where its schema says so explicitly; it does not replace the governed artefact.</p>
+<p>This replaces the original blanket rejection of a hybrid architecture. The architecture is hybrid <strong>by declared record class</strong>, never ambiguous within one record.</p>
+<h3>3. Forge is the central projection baseline</h3>
+<p>For the shared central view, the source is the pushed default-branch state held by Forgejo, as decided by ADR-012. Every projected record must be attributable to its source repository, path, and commit.</p>
+<p>A working copy remains the authoring workspace. Unpushed work may appear in the Hub only as an attributed preliminary overlay. It must not silently replace or be presented as the Forge-derived baseline. When its commit reaches Forge, the baseline absorbs it and the overlay retires.</p>
+<h3>4. Mutations of file-backed state are file-first</h3>
+<p>Creating or changing a file-backed work record means changing its repository artefact first. A convenience tool or API is conformant only when it performs a governed repository mutation and leaves a reviewable file and commit. Writing only the projected database row is not a durable update.</p>
+<p>Direct Hub APIs remain valid for hub-native records. They may also provide diagnostics or propose repository patches, but a successful database PATCH is not evidence that a file-backed status changed.</p>
+<h3>5. The rebuild guarantee applies to the projection, not the whole database</h3>
+<p>Given a repository and a specific Forge commit, the system must be able to reconcile that repository's file-derived projection so that it is equivalent to the records derived from that commit. Reconciliation must be idempotent, verifiable, and scoped per repository; a fleet operation is iteration over the same per-repository operation.</p>
+<p>Reconciliation retires file-derived records that no longer derive. It does not delete hub-native history attached to them. It must refuse and report a repository whose records exist only in the projection until those records have an explicit disposition. A Forge rebuild does not reconstruct preliminary overlays and must disclose their retirement before proceeding.</p>
+<p>Therefore the <strong>file-derived projection is disposable</strong>. The database as a whole is not disposable when it also contains hub-native facts.</p>
+<h3>6. Identity and lifecycle are delegated contracts</h3>
+<p>This ADR does not define a second identity or lifecycle schema.</p>
+<ul><li>Workplan and task identity follow ADR-007 as amended by ADR-011: global identity is namespace-aware, and derivable Hub identifiers are governed by that contract. Existing historical identifiers are grandfathered according to its migration rules.</li><li>Work-record kinds, locations, lifecycle values, and residual handling follow <code>canon/standards/work-record-types_v0.1.md</code> and <code>canon/standards/workplan-terminology-fleet_v0.1.md</code>.</li></ul>
+<p>New normative text uses <code>workplan</code> and <code>work record</code>. <code>workstream</code> remains only as a metered compatibility term for legacy database and API surfaces.</p>
+<h3>7. Reconciliation belongs at the repository boundary</h3>
+<p>Repo Manager owns discovery, parsing, identity checks, and reconciliation for file-backed records. State Hub owns the projection and hub-native records. The implementation may distribute fetch and parse work, but it must preserve that authority boundary.</p>
+<p>Legacy <code>create_workstream</code>, <code>create_task</code>, workstation-driven <code>sync-workplans</code>, and similarly named commands are not normative interfaces. They are conformant only if their current implementation satisfies decisions 3 and 4; otherwise they are transitional or retired.</p>
 </section>
-<section id="workplan-file-convention"><h2>Workplan File Convention</h2>
-<p>Each workplan lives in a <code>workplans/</code> directory in the repository that owns the work. The owning repository is identified by domain.</p>
-<h3>Location</h3>
-<pre>&lt;repo-root&gt;/workplans/&lt;id&gt;-&lt;slug&gt;.md</pre>
-<p>Examples:</p>
-<ul><li><code>the-custodian/workplans/CUST-WP-0005-dynamic-domains.md</code></li><li><code>railiance/workplans/RAIL-WP-0001-three-phoenix.md</code></li></ul>
-<h3>Frontmatter Schema</h3>
-<pre>---
-id: CUST-WP-0005            # human-readable workplan ID, unique per repo
-type: workplan
-title: &quot;State Hub v0.5 — Dynamic Domains &amp; Multi-Repo&quot;
-domain: custodian            # must match a registered domain slug
-status: active               # active | completed | archived
-owner: custodian
-topic_slug: custodian        # maps to a state-hub Topic slug
-created: &quot;2026-02-28&quot;
-updated: &quot;2026-02-28&quot;
---</pre>
-<h3>Task Items</h3>
-<p>Tasks are embedded in the workplan file as headed sections. Each task section carries its own YAML block:</p>
-<pre>## P1.1 — Create `domains` table + Alembic migration
-</pre>
-<p>id: CUST-WP-0005-T001 status: todo priority: high</p>
-<pre>
-Task description prose here.</pre>
-<p>The state-hub parses these embedded task blocks during ingestion and upserts rows in the <code>tasks</code> table. The <code>id</code> field is the stable external key; the state-hub UUID is internal and opaque.</p>
-<h3>Decision Items</h3>
-<p>Decisions are separate files or embedded sections following the same pattern, using <code>type: decision</code> in frontmatter.</p>
-</section>
-<section id="rebuild-principle"><h2>Rebuild Principle</h2>
-<p>The rebuild sequence for a clean state-hub:</p>
-<ol><li><code>make migrate</code> — create schema</li><li><code>make seed-domains</code> — insert domain rows (domains.yaml in canon/)</li><li>For each registered repository: <code>make sync-workplans REPO=&lt;slug&gt;</code> — parse workplan files and upsert workstreams, tasks, decisions</li><li><code>make sync-progress</code> — replay progress events from episodic memory logs</li></ol>
-<p>After step 4 the database must be functionally equivalent to the live state.</p>
+<section id="workplan-closure"><h2>Workplan closure</h2>
+<p>A workplan cannot be marked <code>finished</code> merely by changing its Hub row. Before closure, the responsible worker must:</p>
+<ol><li>review the source file and the projected view for unfinished tasks;</li><li>record completed and cancelled outcomes in the source task blocks using the canonical task lifecycle;</li><li>turn every actionable carry-forward item into a live work record with <code>origin: residual</code> and an <code>origin_ref</code>, or into another explicitly linked workplan;</li><li>set the source workplan to <code>finished</code>, update it, and commit the result;</li><li>publish the commit to Forge for the shared baseline and verify that the projection reconciles to that commit.</li></ol>
+<p>A local reconciliation before push may expose preliminary state, but it does not complete step 5.</p>
+<p>Automated stale-task cleanup must report file/projection drift. It may not silently cancel a file-backed task only in the database. An automated repair may change such a task only through the same governed repository mutation and commit path as any other file-backed change. Cleanup of hub-native records is governed by their own retention contract.</p>
 </section>
 <section id="consequences"><h2>Consequences</h2>
-<h3>Immediate</h3>
-<ul><li>The v0.5 and v0.3 workplans created DB-first in this session are <strong>legacy records</strong> that violate this ADR. Remediation: write the corresponding workplan files, then mark the DB rows as <code>source: db-legacy</code> until a sync mechanism can reconcile them.</li></ul>
-<ul><li>The state-hub CLAUDE.md design-boundary note must be updated: the MCP bootstrap tools are permitted only as write-through tools (file + DB), never as DB-only tools.</li></ul>
-<h3>Medium Term</h3>
-<ul><li>A <code>make sync-workplans</code> command must be implemented as part of the managed-repos / contribution-tracking infrastructure (see v0.3 workplan).</li></ul>
-<ul><li>The <code>managed_repos</code> table is the prerequisite: the state-hub must know which repositories to scan.</li></ul>
-<ul><li>Workplan file format must be versioned and parsed by a dedicated loader (<code>state-hub/scripts/sync_workplans.py</code>).</li></ul>
-<h3>Long Term</h3>
-<ul><li>When the state-hub grows to cover multiple users or teams, this principle ensures that no coordination state can be lost by a database failure. Every repository is its own resilient shard of the coordination graph.</li></ul>
-<ul><li>This is the foundation for the "transgenerational" property: workplans in git survive database migrations, cloud provider changes, and system rebuilds.</li></ul>
+<h3>Positive</h3>
+<ul><li>Durable work remains inspectable, reviewable, and recoverable through Git.</li><li>The central view has an exact repository and commit provenance instead of reflecting whichever workstation synced most recently.</li><li>Reconciliation can be exercised per repository without destroying progress history or other hub-native evidence.</li><li>Multiple contributors share a published baseline while retaining an honest representation of preliminary work.</li><li>Service ownership is clearer: repositories own file-backed truth; the Hub owns runtime facts and projection services.</li></ul>
+<h3>Negative</h3>
+<ul><li>File-backed changes require a repository mutation and normally a push before they become shared baseline state.</li><li>Forge availability affects projection freshness, although it does not prevent local authoring.</li><li>Preliminary, stale, and retired projection states must be visible in APIs and user interfaces.</li><li>Git merge conflicts become the explicit conflict mechanism for simultaneous edits to the same authoritative artefact.</li><li>Tools that previously corrected only database state must be changed to emit a diagnostic or perform a governed repository update.</li></ul>
 </section>
-<section id="alternatives-considered"><h2>Alternatives Considered</h2>
-<p><strong>Database-first with export:</strong> Create in DB, export to files on demand. Rejected: export is easily skipped and files become secondary/stale.</p>
-<p><strong>Files-only, no database:</strong> Parse files on every query. Rejected: impractical at scale; the database is a necessary cache for cross-repo aggregation and real-time dashboard queries.</p>
-<p><strong>Hybrid with explicit sync flag:</strong> Mark some records as "db-authoritative" and others as "file-authoritative." Rejected: introduces ambiguity about which records matter; violates the "single source of truth" principle.</p>
+<section id="migration"><h2>Migration</h2>
+<p>No bulk rename, UUID rewrite, or historical file rewrite is required by this amendment. Existing identifiers and legacy terminology retain the grandfathering rules of ADR-007, ADR-011, and the terminology standard.</p>
+<p>Implementations must audit and retire DB-first creation, closure, and stale-task cleanup paths. Existing file-backed projection rows without a Forge source commit are migration state: they must be matched to a repository artefact or explicitly dispositioned before reset. Forge-derived reconciliation and preliminary overlays are implemented under ADR-012 rather than duplicated here.</p>
+<p>The <code>accepted-1</code> publication remains the immutable historical revision. This document is <code>accepted-2</code>.</p>
 </section>
-<section id="workplan-closure-protocol"><h2>Workplan Closure Protocol</h2>
-<p>When a workplan is about to be marked <code>finished</code>, the responsible agent MUST perform a closure review before writing the status change. This prevents the stale-task accumulation that this ADR was designed to make detectable.</p>
-<h3>Steps</h3>
-<ol><li><strong>Query all non-done tasks</strong> in the workplan via <code>GET /tasks/?workplan_id=&lt;uuid&gt;</code> (legacy alias: <code>workstream_id</code>; filter for <code>todo</code>, <code>in_progress</code>, <code>blocked</code>).</li></ol>
-<ol><li><strong>Classify each task</strong> into one of three outcomes:</li></ol>
-<div class="scroll"><table><thead><tr><th>Outcome</th><th>Action</th></tr></thead><tbody><tr><td><strong>Done</strong> — work was completed, DB record just wasn't updated</td><td><code>PATCH /tasks/{id}/ {&quot;status&quot;: &quot;done&quot;}</code></td></tr><tr><td><strong>Cancelled</strong> — dropped, superseded, or out of scope</td><td><code>PATCH /tasks/{id}/ {&quot;status&quot;: &quot;cancelled&quot;, &quot;blocking_reason&quot;: &quot;&lt;why&gt;&quot;}</code></td></tr><tr><td><strong>Carry-forward</strong> — genuinely unfinished, belongs in the next run</td><td>Leave open; note in closure review; trigger new workplan</td></tr></tbody></table></div>
-<ol><li><strong>Append a <code>## Closure Review</code> section</strong> to the workplan file:</li></ol>
-<pre>   ## Closure Review — YYYY-MM-DD
-
-   **Outcome:** All tasks completed / N tasks carried forward / N tasks dropped.
-
-   ### Completed (DB updated)
-   - TASK-ID — title
-
-   ### Cancelled (dropped)
-   | Task | Reason |
-   |------|--------|
-   | TASK-ID — title | Superseded by X |
-
-   ### Carried forward
-   | Task | Target workplan |
-   |------|----------------|
-   | TASK-ID — title | CUST-WP-XXXX |</pre>
-<ol><li><strong>If any tasks are carried forward</strong>: do not mark the workplan <code>finished</code> yet. Create the new workplan file (or amend an existing active one), then close the current workplan.</li></ol>
-<ol><li><strong>Update the workplan frontmatter</strong> <code>status: finished</code> and <code>updated:</code> date.</li></ol>
-<ol><li><strong>Mark the workplan <code>finished</code></strong> in the state hub via MCP or API (<code>update_workplan_status</code>).</li></ol>
-<h3>Daily Stale-Task Cleanup</h3>
-<p>As a safety net for cases where the closure review was skipped or incomplete, a cleanup script cancels any surviving open tasks in completed/archived workstreams:</p>
-<pre>cd ~/the-custodian/state-hub
-make cleanup-stale            # run immediately
-# or add to cron:
-# 0 3 * * * cd ~/the-custodian/state-hub &amp;&amp; make cleanup-stale</pre>
-<p>The script (<code>scripts/cleanup_stale_tasks.py</code>) emits a <code>cleanup</code> progress event recording which tasks were cancelled and in which workstreams. Tasks cancelled by the cleanup carry a <code>blocking_reason</code> noting they should be verified against the workplan file.</p>
-<p>The closure review is the primary mechanism; the cleanup is the fallback. If the cleanup regularly cancels tasks, it signals that closure reviews are being skipped — that is the process failure to address, not just the stale tasks.</p>
+<section id="alternatives-considered"><h2>Alternatives considered</h2>
+<p><strong>Database-first with export.</strong> Rejected. Export can be skipped, making the reviewable artefact secondary and stale.</p>
+<p><strong>Files only, with no projection database.</strong> Rejected. Cross-repository queries, runtime views, and append-only operational facts need indexed services.</p>
+<p><strong>Treat every Hub record as reconstructible from Git.</strong> Rejected. This either loses runtime truth during rebuild or creates artificial files whose only purpose is mirroring a database.</p>
+<p><strong>Let working copies push authoritative projection rows.</strong> Rejected by ADR-012. It makes the baseline depend on the last workstation to reconcile and cannot be audited against a shared commit.</p>
 </section>
 <section id="related"><h2>Related</h2>
-<ul><li>Custodian Constitution v0.1 §2 (Powers) — canon changes require review gate</li><li>ADR-000 (forthcoming) — overall Custodian architecture principles</li><li>State Hub v0.3 workplan — <code>sync_workplans.py</code> is a Phase 4 deliverable</li><li><code>canon/values/foundational_values_v0.1.md</code> — Local-first, Auditability, Reversibility</li></ul>
-</section><footer><span>CUST-ADR-001 · accepted-1 · accepted</span><span>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 4039c9d1c08c92014ecc0a65dda63cc73ba187bb</span></footer></main></div></div></html>
+<ul><li>ADR-003 — materialized and derived state</li><li>ADR-005 — cross-repository work ownership</li><li>ADR-007 — workplan identity and repository worker topology</li><li>ADR-010 — Hub authority and local cache model</li><li>ADR-011 — namespace-aware federation and reconciliation limits</li><li>ADR-012 — Forge projection source and preliminary overlay</li><li><code>canon/standards/work-record-types_v0.1.md</code> — work-record kinds, lifecycle, residuals, and reconciliation</li><li><code>canon/standards/workplan-terminology-fleet_v0.1.md</code> — canonical terminology</li><li><code>canon/values/foundational_values_v0.1.md</code> — local-first operation, auditability, and reversibility</li></ul>
+</section><footer><span>CUST-ADR-001 · accepted-2 · accepted</span><span>the-custodian · canon/architecture/adr-001-workplans-as-repo-artefacts.md · 44500fc85cf29d8e9b2ee5c91994032ed3d04e5b</span></footer></main></div></div></html>