@evolvehq/docflow 0.9.0 → 0.9.2

package/README.md

@@ -80,8 +80,10 @@ set keeps numbering contiguous **per repo** while a federation-wide
 identity is the cross-repo key. The `rollup` skill aggregates every
 member's catalogue into one product-wide view, and `audit` gains
 cross-repo checks (membership, identity collisions, dangling references,
-roll-up drift). No tool writes across a repo boundary; consistency is
-declared at the edges and enforced by audit. See the
+roll-up drift, convention drift). Work and status cross repos the same way:
+a cross-repo decision is one plan item per affected repo, and its aggregate
+status ("2 of 3 repos") surfaces in the roll-up. No tool writes across a
+repo boundary; consistency is declared at the edges and enforced by audit. See the
 [methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories)
 for the full model.
 

package/USAGE.md

@@ -239,6 +239,7 @@ picks; a fully-specified request lets you skip straight through.
 | `/audit` | Lints the repo against its own conventions and reports a punch list — numbering, INDEX sync, plan coverage, section completeness, status validity, cross-refs, language mandate, and **ADR-privacy leaks into user-visible code**. Offers to fix the mechanical issues. |
 | `/brainstorm` | Decomposes a problem into candidate ADRs + plan items with dependency edges and ordering. Proposes drafts only; writes nothing until approved, then hands off to `/new-adr` and `/new-plan`. |
 | `/agent-wave` | Orchestrates parallel worktree subagents over the queue. Asks wave width, budget (items/waves; hours as a soft cap), and supervision (checkpoint vs. continuous). Requires multi-agent mode; refuses mode 1. |
+| `/rollup` | For a **multi-repo product**: from the home repo, aggregate every member repo's `INDEX` into one derived, product-wide roll-up. Members not checked out are listed as "not aggregated this run". |
 
 ### agent-wave: what it can and can't do
 
@@ -254,6 +255,40 @@ It requires a multi-agent mode (Q5 mode 2 or 3) and works best in mode
 Continuous-unsupervised runs are recommended only with PR-based
 integration, so CI gates each merge.
 
+### Multi-repo products (federation)
+
+A single product spread across several repos runs as a **federation**.
+Bootstrap asks whether the repo is standalone or part of a multi-repo
+product, and — if the latter — whether it is **establishing** a new
+federation or **joining** an existing one. A joining repo writes only its
+own `federation.md` back-pointer; it never writes into another repo, and
+it inherits the topology and identity scheme rather than re-choosing them.
+
+- **Topology** (chosen at establishment): a central decisions repo · a
+  distributed set · or a home repo with local decisions alongside (the
+  default).
+- **Identity & numbering.** Numbering stays contiguous *per repo*; a
+  federation-wide identity — by default a repo-prefixed slug
+  `<repo-id>/NNNN-slug` — is the cross-repo key, so two repos never
+  collide.
+- **References.** Cross-repo links use the logical identity, resolved via
+  the home's `federation-index.md`; same-repo links stay relative.
+- **Work & status.** A cross-repo decision is one plan item **per affected
+  repo**, each tracing to the owning ADR by its federation identity (no
+  umbrella record); the decision's aggregate status ("2 of 3 repos") is a
+  derived roll-up column, `Implemented` only when every per-repo item ships.
+- **`/rollup`** aggregates every member's catalogue into one product-wide
+  view; **`/audit`** gains cross-repo checks (bidirectional membership,
+  identity collisions, dangling references, roll-up drift, convention
+  drift).
+- **Conventions** are copied at bootstrap and kept honest by audit
+  drift-detection — referenceable from the home, never force-pushed.
+
+No tool writes across a repo boundary: consistency is declared at the
+edges and enforced by audit. See the
+[methodology](https://evolvehq.github.io/docflow/methodology/#5-scaling-to-many-repositories)
+for the formal model.
+
 ### Enabling an optional convention later (worked example: TDD)
 
 docflow's bootstrap is deliberately lean — practices such as

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.9.0",
-  "description": "ADR-driven documentation workflow: scaffold an Architecture Decision Record (ADR) catalogue, a plan/ queue, and AGENTS.md conventions into any repo, then author, queue, ship, and audit ADRs with lifecycle skills. Works with the pi coding agent and Claude Code.",
+  "version": "0.9.2",
+  "description": "ADR-driven documentation workflow: scaffold an Architecture Decision Record (ADR) catalogue, a plan/ queue, and AGENTS.md conventions into any repo, then author, queue, ship, audit, and roll up ADRs with lifecycle skills — across one repo or a multi-repo product. Works on Claude Code, Claude Cowork, pi, Codex, and OpenCode.",
   "keywords": [
     "pi-package",
     "adr",
     "architecture-decision-records",
     "documentation",
-    "claude-code"
+    "claude-code",
+    "multi-repo"
   ],
   "license": "MIT",
   "author": "Eugenio Minardi",

package/plugins/docflow/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit
-description: Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches), and — for a multi-repo product — cross-repo federation checks (bidirectional membership, identity collisions, dangling cross-repo references, roll-up drift). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", "are the ADRs in sync", or invokes /audit.
+description: Audit a documentation-led repo against its own conventions — contiguous ADR numbering, INDEX sync, plan/ coverage, required sections, status validity, cross-reference resolution, language mandate, ADR-privacy leaks into user-visible code, cross-worktree collisions (duplicate numbers, duplicate plan ownership, same ADR edited on two branches), and — for a multi-repo product — cross-repo federation checks (bidirectional membership, identity collisions, dangling cross-repo references, roll-up drift, convention drift). Reports a punch list and offers to fix the mechanical issues. Use when the user says "audit the ADRs", "lint the conventions", "check repo consistency", "are the ADRs in sync", or invokes /audit.
 ---
 
 # audit
@@ -16,9 +16,10 @@ This is the enforcement `AGENTS.md` cannot guarantee on its own.
    language mandate, optional artefacts present (GLOSSARY, domains/),
    and any Q10 domain hard rules.
 3. If a `federation.md` exists, this repo is part of a multi-repo
-   product. Note whether it is the **home** or a **member** and read the
-   recorded identity scheme; the cross-repo checks (check 12) run from
-   the home repo.
+   product. Note its `Role` (`central` / `home` / `coordinator`
+   index-holder, or a plain `member`) and read the recorded identity
+   scheme; the cross-repo checks (check 12) run from the index-holding
+   repo.
 
 ## Step 1 — Run the checks (read-only)
 
@@ -67,22 +68,35 @@ relevant):
     Cross-check against `_agent/IN_FLIGHT.md`: every collision should
     correspond to a reservation/ownership violation recorded there.
 12. **Cross-repo (federation) checks** — only when a `federation.md`
-    exists; run from the **home** repo. Reach each member through the
-    local checkout named in `federation-index.md`. A member not checked
+    exists; run from the **index-holding** repo (`Role: central`, `home`,
+    or `coordinator` — whichever holds `federation-index.md`). Reach each
+    member through the local checkout named in `federation-index.md`. A member not checked
     out locally is reported **"unverified this run"** — never silently
     passed, never a hard failure.
     - **Bidirectional membership.** Every repo listed in the member index
-      carries a `federation.md` back-pointer to this home, and every repo
-      whose back-pointer names this home is listed in the index. Flag
-      either half-edge (in-index-without-back-pointer, or
-      points-home-but-unlisted).
-    - **Identity collisions.** No two ADRs across the federation resolve
-      to the same identity under the recorded identity scheme.
-    - **Dangling cross-repo references.** Every cross-repo link resolves
-      to a real ADR in the named member; flag a target that does not
-      exist. (Same-repo relative links are check 7.)
+      carries a `federation.md` back-pointer to this index-holder, and
+      every repo whose back-pointer names this repo is listed in the
+      index. Flag either half-edge (in-index-without-back-pointer, or
+      points-here-but-unlisted).
+    - **Identity collisions.** Under the repo-prefixed scheme an identity
+      is `repo-id` + local number, so the only reachable collision is a
+      **duplicate `repo-id`**. Flag any repo-id that appears on more than
+      one `federation-index.md` row or in two members' `federation.md`
+      back-pointers.
+    - **Dangling cross-repo references.** Resolve each cross-repo link
+      along `repo-id → Pointer → adr/NNNN-*.md` — look up the repo-id's
+      Pointer in `federation-index.md`, then the ADR file under that repo.
+      A repo-id with **no index row** is a dangling reference. If the row
+      exists but the **checkout is absent**, report it **"unverified this
+      run"** (not dangling); only an **absent ADR in a present checkout**
+      is a true dangling reference. (Same-repo relative links are
+      check 7.)
     - **Roll-up drift.** The roll-up agrees with each member's `INDEX.md`
       metadata; flag rows that are stale, missing, or extra.
+    - **Convention drift.** Compare each member's **shared** conventions
+      against the index-holder's authoritative copy; flag a member whose
+      shared conventions have drifted from the source. Members' **local-only**
+      conventions are exempt.
 
 ## Step 2 — Report
 

package/plugins/docflow/skills/bootstrap/SKILL.md

@@ -60,8 +60,10 @@ questions.
 For a **multi-repo product** (one product spread across several repos —
 see Q11), two extra files appear: `federation.md`, a small back-pointer
 every member repo carries, and `federation-index.md`, the authoritative
-member list that lives only in the home/establishing repo. A standalone
-repo has neither.
+member list that lives only in the home/establishing repo. All federation
+artefacts — `federation.md`, `federation-index.md`, and the derived
+roll-up `ROLLUP.md` — are placed under the **configured artefact root**.
+A standalone repo has none of them.
 
 ## Step 3 — Conventions to install
 
@@ -246,12 +248,14 @@ lines and ask for sign-off before writing any files.
     The scheme is recorded in the federation config and applied by the
     authoring skills.
 
-    **Establish** designates this repo as the home/central repo, writes
-    the member index here, and records the topology **and identity
-    scheme** in the federation config. **Join** asks for the home pointer — **you confirm it; the
-    skill performs no cross-repo read and no host API call** — then
-    writes **only this repo's** back-pointer config and inherits the
-    topology without re-asking it. Joining never writes into any other
+    **Establish** sets this repo's role from the chosen topology —
+    **central** (A), **coordinator** (B), or **home** (C) — writes the
+    member index here, and records the topology **and identity scheme**
+    in the federation config. **Join** asks for the home pointer **and the federation's topology +
+    identity scheme** — **you supply them; the skill performs no
+    cross-repo read and no host API call** — then writes **only this
+    repo's** back-pointer config, recording those values (it does not
+    re-choose the topology). Joining never writes into any other
     repo; adding this repo to the member index is a deliberate edit in
     the home repo. A standalone repo (Q11 = No) writes none of these
     files and behaves exactly as a single-repo bootstrap.
@@ -326,18 +330,30 @@ write it into the repo.
     configured artefact root (repository root by default).
     - **Establish:** write `federation-index.md` (the member index, a
       Markdown table) from `templates/federation-index.md` into this
-      repo, seeded with this repo as the home member; and write
-      `federation.md` from `templates/federation-config.md` with
-      `Role: home`, the chosen topology, and the chosen identity scheme
-      (default repo-prefixed slug). Record the identity scheme in both
-      files so it is the same on every read.
+      repo, seeded with this repo as the first member; and write
+      `federation.md` from `templates/federation-config.md` with the
+      chosen topology, the chosen identity scheme (default repo-prefixed
+      slug), and this repo's **`Role` set from the topology**:
+      `central` for **A** (this repo holds all product-wide ADRs),
+      `coordinator` for **B** (this repo holds only the member index —
+      product-wide decisions are distributed and the roll-up is the
+      product-wide view), or `home` for **C** (this repo holds
+      product-wide ADRs; members keep local ADRs alongside). Record the
+      identity scheme in both files so it is the same on every read.
     - **Join:** write **only** `federation.md` from
       `templates/federation-config.md` with `Role: member`, the
       confirmed home pointer, and the topology **and identity scheme**
-      inherited from the federation (read them from the home, do not
-      re-ask). Write nothing into any other repo, and do **not** create a
-      member index. Tell the user to add this repo to the home repo's
-      `federation-index.md` (a deliberate edit there).
+      for the federation, **supplied by the operator at join** (recorded
+      into this repo's `federation.md`; no cross-repo read). Then apply
+      the **topology's member rule**: for **A**, this
+      repo references the central repo and does **not** hold product-wide
+      ADRs locally (its `adr/` is for local-implementation decisions
+      only); for **B**, this repo owns its own catalogue in full; for
+      **C**, this repo keeps local ADRs and references the home for
+      product-wide ones. Write nothing into any other repo, and do **not**
+      create a member index. Tell the user to add this repo to the
+      **index-holding repo's** `federation-index.md` — the home (C),
+      central (A), or coordinator (B) repo — a deliberate edit there.
 
 Commit each file (or logical group) with a Conventional Commit message;
 no `Co-Authored-By` trailer unless Q6 asked for one.

package/plugins/docflow/skills/bootstrap/templates/CONVENTIONS.md

@@ -177,13 +177,27 @@ This repo belongs to the **<product>** federation. Topology and the
 identity scheme are recorded in `federation.md`; the home repo's
 `federation-index.md` is the authoritative member list.
 
+- **Where product-wide decisions live depends on the topology** (recorded
+  in `federation.md`):
+  - **A — central:** a single central repo holds **all** product-wide
+    ADRs; every other repo references them and never duplicates a
+    product-wide decision locally.
+  - **B — distributed:** **no** repo holds product-wide ADRs; each repo
+    owns its own catalogue and the roll-up is the product-wide view.
+  - **C — home + local:** the home repo holds product-wide ADRs; members
+    keep purely-local ADRs alongside and reference the home for
+    product-wide ones.
 - **Numbering is per-repo contiguous.** Each member repo numbers its own
   ADRs contiguously from `0001`; numbers are **not** unique across the
   federation. The cross-federation key is the **identity scheme** recorded
   in `federation.md` — default repo-prefixed slug `<repo-id>/NNNN-slug`.
 - **Cross-repo references use the logical identity**, resolved through the
-  member index (`repo-id → location`); they survive a target repo move
-  (edit one index row, not the references). **Same-repo references stay
+  member index along `repo-id → Pointer (repo root) → adr/NNNN-*.md`: look
+  up the repo-id's `Pointer` in `federation-index.md`, then find
+  `adr/NNNN-*.md` under that repo. They survive a target repo move (edit
+  one index row, not the references). A **member repo holds no index**, so
+  it first reaches `federation-index.md` via its own `federation.md`
+  `Home` pointer, then resolves as above. **Same-repo references stay
   relative paths** (`adr/NNNN-*.md`).
 - `supersedes:` / `superseded-by:` may point across repos using the
   logical identity.
@@ -191,6 +205,24 @@ identity scheme are recorded in `federation.md`; the home repo's
   `federation.md` back-pointer; adding it to the home's
   `federation-index.md` is a deliberate edit there. The two must agree —
   audit cross-checks both directions.
+- **Cross-repo work is one plan item per repo.** A decision implemented in
+  several repos gets one `plan/todo` item **per affected repo**, each in
+  the repo whose code it changes and naming the owning ADR by its
+  federation identity. The owning ADR is the single grouping point — its
+  per-repo items are discoverable from it; there is **no umbrella record**.
+  Per-repo "lower numbers first" ordering is unchanged.
+- **Aggregate status is derived in the roll-up.** A cross-repo decision is
+  `Implemented` only when **every** owning per-repo plan item has shipped
+  (each under its own repo's completion event); until then it is partially
+  implemented. The aggregate ("2 of 3 repos") is a **derived column in the
+  roll-up**, computed from per-repo plan-item state — never hand-written
+  into the ADR, so no cross-repo writes.
+- **Shared conventions come from one source.** Shared conventions and
+  templates are authoritative in the index-holding repo; members **copy
+  them at bootstrap** and may keep **local-only** conventions alongside.
+  Updates are **not** force-pushed — drift between a member's copy and the
+  source is **detected by audit**. Referenceable, not enforced; no
+  cross-repo writes.
 -->
 
 ## Audit Trail Policy

package/plugins/docflow/skills/bootstrap/templates/federation-config.md

@@ -9,7 +9,7 @@ is my home?"; the home repo's `federation-index.md` is the answer to
 - **Topology:** <A — central decisions repo | B — distributed + federation | C — home repo + local>
 - **Identity scheme:** <repo-prefixed slug `<repo-id>/NNNN-slug` (default) | other scheme chosen at establishment>
 - **Home:** <pointer to the home/central repo — URL or path; for the home repo itself, `this repo`>
-- **Role:** <home | member>
+- **Role:** <central | home | coordinator | member — the establishing repo's role is set by the topology (central for A, coordinator for B, home for C); every joining repo is `member`>
 - **Repo id:** <short identifier for this repo, used to qualify its records across the federation>
 
 <!-- Hand-maintained. Membership is declared, not auto-discovered: a

package/plugins/docflow/skills/bootstrap/templates/federation-index.md

@@ -11,7 +11,12 @@ skills read this to enumerate the product's repos.
 
 | Repo id | Repo | Role | Pointer |
 |---------|------|------|---------|
-| <id>    | <this repo> | home | this repo |
+| <id>    | <this repo> | <central\|home\|coordinator> | this repo |
+
+<!-- Role values: the establishing repo is `central` (topology A),
+`coordinator` (B), or `home` (C); every other member is `member`.
+Pointer `this repo` means the repo that holds this index (the
+index-holder); resolve every other Pointer relative to it. -->
 
 <!-- Each row should have a matching federation.md back-pointer in the
 named repo, and vice versa. The audit step cross-checks both directions. -->

package/plugins/docflow/skills/new-adr/SKILL.md

@@ -84,8 +84,8 @@ If this ADR replaces an existing one:
   History row noting the successor.
 - **Same-repo** links use relative paths (`adr/NNNN-*.md`). **In a
   federation**, a link to an ADR in another repo uses the logical
-  identity (`<repo-id>/NNNN-slug`), resolved via the member index — not
-  a relative path.
+  identity (`<repo-id>/NNNN-slug`), resolved via the member index along
+  `repo-id → Pointer → adr/NNNN-*.md` — not a relative path.
 - A pure deprecation (no successor) sets the target to `Deprecated`
   with a Revision History row — and is usually done directly, not via
   this skill.

package/plugins/docflow/skills/new-plan/SKILL.md

@@ -52,6 +52,12 @@ Questions (skip any the request already answers):
   still `Proposed`, warn — you can queue ahead of acceptance, but the
   work is not yet authorised. If it has no ADR at all, suggest running
   the **new-adr** skill first; plan items should trace to a decision.
+- **In a federation** (a `federation.md` exists): the owning ADR may live
+  in **another** repo (the home/central). Name it by its **federation
+  identity** (`<repo-id>/NNNN-slug`); the plan item itself lives in **this**
+  repo — the one whose code the work changes. A decision spanning several
+  repos gets **one item per affected repo**, each tracing to the same
+  owning ADR (the grouping point — no umbrella record).
 
 ## Step 2 — Pick number and position
 

package/plugins/docflow/skills/rollup/SKILL.md

@@ -12,11 +12,13 @@ from source, never hand-edited — treat it exactly like a repo's own
 
 ## Step 0 — Preconditions
 
-1. This skill runs in the **home repo** of a federation. Confirm a
-   `federation-index.md` (the authoritative member list) and a
-   `federation.md` with `Role: home` exist. If they do not, stop: either
-   this repo is standalone (nothing to roll up) or it is a member, not the
-   home — point the user at the home repo.
+1. This skill runs in the **index-holding repo** of a federation — the one
+   that carries `federation-index.md` (its `Role` is `central` for
+   topology A, `coordinator` for B, or `home` for C). Confirm
+   `federation-index.md` and a `federation.md` whose `Role` is `central`,
+   `home`, or `coordinator` exist. If they do not, stop: either this repo
+   is standalone (nothing to roll up) or it is a plain member — point the
+   user at the index-holding repo.
 2. Read `federation.md` to learn the **identity scheme** (default
    repo-prefixed slug `<repo-id>/NNNN-slug`); roll-up rows use it.
 
@@ -38,6 +40,12 @@ For every member whose checkout is **locally available** at its pointer:
 A member's own `INDEX.md` stays authoritative for that member; this skill
 only reads it.
 
+For the **aggregate status** of a product-wide decision (one with owning
+per-repo plan items across several members), also scan each member's
+`plan/todo/` (pending) and `plan/done/` (shipped) for items naming that
+decision's federation identity — that per-repo state feeds the aggregate
+column in Step 4.
+
 ## Step 3 — Handle unreachable members
 
 A member named in the index whose checkout is **not locally available** is
@@ -47,12 +55,17 @@ visible rather than silent.
 
 ## Step 4 — Write the roll-up
 
-Write the aggregate to a derived file in the home repo (e.g. `ROLLUP.md`):
+Write the aggregate to **`ROLLUP.md`** at the configured artefact root (the
+same root as `INDEX.md`), so every re-run overwrites the same file:
 
 - A header stating it is **generated — do not hand-edit**, with the run
   date and the set of members aggregated.
 - One table across the whole product: federation identity, title, status,
   owning repo, date. Group or sort by owning repo for readability.
+- For product-wide decisions, an **aggregate status** column **derived**
+  from per-repo plan-item state: `Implemented` only when every owning
+  per-repo plan item is in a member's `plan/done/`, otherwise `N of M
+  repos` shipped. This column is derived — never written back into any ADR.
 - The "Not aggregated this run" list from Step 3.
 
 Do not alter any member's `INDEX.md` and do not write into any other repo.