@evolvehq/docflow 0.5.0 → 0.6.0

package/USAGE.md

@@ -233,6 +233,32 @@ it no longer applies); to make it enforceable, add the test command to
 the verify gate. Any other "we should always X" practice is enabled the
 same way — `/add-convention` is the single path.
 
+### Concurrent ADR/plan creation (the numbering race)
+
+ADR and `plan/todo` numbers are contiguous and chosen at authoring time,
+so two branches/worktrees can both grab the same "next" number and
+collide at merge. docflow keeps the numbers (they stay short, ordered,
+and the stable cross-reference key — no UUIDs, no rename-breaks-refs) and
+closes the race with **process guardrails** instead of a new identity
+scheme:
+
+- **G1 — decide before do** *(recommended):* prefer to land an ADR + its
+  plan items on `main` before implementation work begins.
+- **G2 — check before merge** *(primary defence):* before integrating,
+  sync onto the current `main` and run the audit; if your number now
+  clashes with what landed, renumber locally **before** merging — a
+  trivial change (a new ADR/plan names its own number only in its file
+  and `INDEX.md`).
+- **G3 — gate backstop:** the single-threaded merge gate rejects a
+  duplicate; the later author renumbers.
+
+`bootstrap` **pre-wires** these into `CONVENTIONS.md` + an `AGENTS.md`
+hard rule **only** for multi-agent (mode 2/3) or PR-based repos.
+**Single-agent / direct-to-main repos have no race by construction** and
+get none of this ceremony. Numbers are immutable once merged. (For
+orchestrated runs, `agent-wave` additionally *reserves* disjoint number
+blocks up front, so G2/G3 rarely fire.)
+
 ## 6. Customising or extending
 
 The templates are deliberately small and self-contained. To customise:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolvehq/docflow",
-  "version": "0.5.0",
+  "version": "0.6.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.",
   "keywords": [
     "pi-package",

package/skills/agent-wave/SKILL.md

@@ -102,9 +102,14 @@ every merge.
 Spawn N subagents in parallel, each in an isolated worktree
 (`isolation: worktree`). Brief each with: its assigned queue item, the
 instruction to follow `_agent/prompts/autonomous.md` end-to-end for that
-one item (orient → implement → verify → integrate per the repo's model →
-ship), and to report back a structured result (item, pass/fail, HEAD or
-PR link, any blocker).
+one item (orient → implement → verify → **check before merge (G2)** →
+integrate per the repo's model → ship), and to report back a structured
+result (item, pass/fail, HEAD or PR link, any blocker). The G2 step:
+before integrating, sync onto the current `main` and run the **audit**
+skill; if the item's new ADR/plan number now clashes with what landed,
+renumber locally
+before merging. (Reservation in Step 2 makes this rare; G2 catches what
+slips through, e.g. an out-of-band ADR landing mid-wave.)
 
 ## Step 4 — Collect and checkpoint
 

package/skills/audit/SKILL.md

@@ -49,9 +49,11 @@ relevant):
 11. **Cross-worktree collisions** (mode 3, or when auditing across
     unmerged branches). These catch semantic conflicts that a
     line-level git merge cannot:
-    - **Duplicate ADR numbers** — two ADR files (across branches/
-      worktrees) claiming the same `NNNN`. Distinct from check 1, which
-      only sees one tree.
+    - **Duplicate ADR or plan/todo numbers** — two ADR files, or two
+      `plan/todo/` items, (across branches/worktrees) claiming the same
+      `NNNN`. Distinct from check 1, which only sees one tree. This is the
+      collision the concurrency guardrails (G2 pre-merge / G3 gate) guard
+      against; flag it so the later author renumbers.
     - **Duplicate plan ownership** — two `plan/todo/` items naming the
       same owning ADR for the same scope, i.e. two worktrees building
       the same thing.

package/skills/bootstrap/SKILL.md

@@ -240,8 +240,12 @@ template, fill its placeholders from the assessment answers, then
 write it into the repo.
 
 1. `CONVENTIONS.md` — from `templates/CONVENTIONS.md`. Spec other files
-   reference.
-2. `AGENTS.md` — from `templates/AGENTS.md`.
+   reference. Include the **§Concurrency Guardrails** section only if Q5
+   is mode 2/3 **or** Q4b is PR-based; omit it for single-agent
+   direct-to-main repos (no numbering race).
+2. `AGENTS.md` — from `templates/AGENTS.md`. Include the concurrency
+   guardrails hard-rule bullet (G2/G3) under the same condition as the
+   CONVENTIONS section above; omit otherwise.
 3. `CLAUDE.md` — from `templates/CLAUDE.md` (single line `@AGENTS.md`).
 4. `adr/0000-template.md` — from `templates/adr-capability.md`.
 5. `adr/NNNN-template.md` — from `templates/adr-technology.md`, only if

package/skills/bootstrap/templates/AGENTS.md

@@ -118,6 +118,18 @@ Coordination rules:
   Add your row when you start, remove it when the worktree closes.
 -->
 
+<!-- Concurrency guardrails hard rule — bootstrap INCLUDES this bullet
+ONLY for multi-agent (mode 2/3) OR PR-based repos (omit for single-agent
+direct-to-main). See CONVENTIONS.md §Concurrency Guardrails.
+
+- **Before integrating, check for number collisions (G2/G3).** Sync onto
+  the current `main` and run `/audit`; if your ADR or `plan/todo` number
+  now clashes with what landed on `main`, renumber locally before
+  integrating. The single-threaded merge gate rejects a duplicate as the
+  backstop. Numbers are immutable once merged. (G1 — landing the ADR
+  before implementation — is recommended guidance, in CONVENTIONS.md.)
+-->
+
 ## Plan folder
 
 - A pending item gets a `plan/todo/NNNN-<slug>.md` file BEFORE work

package/skills/bootstrap/templates/CONVENTIONS.md

@@ -139,6 +139,34 @@ When a `plan/todo/` item ships, the file moves to `plan/done/` AND the
 owning ADR(s)' `status:` advances from `Accepted` to `Implemented`.
 `INDEX.md` is regenerated to match.
 
+<!-- Concurrency Guardrails — bootstrap INCLUDES this section (uncommented)
+ONLY for multi-agent (mode 2/3) OR PR-based repos. Single-agent
+direct-to-main repos have no numbering race by construction and OMIT it.
+Adapt "integrate" to the integration model (PR merge / ff-push / pull
+before commit in a shared checkout).
+
+## Concurrency Guardrails
+
+ADR and `plan/todo` numbers are contiguous and assigned at authoring
+time, so concurrent branches can pick the same next number. These
+guardrails keep numbering collision-free **without changing the identity
+scheme** — the number stays the stable cross-reference key, immutable
+once merged:
+
+- **G1 — decide before do (recommended).** Prefer to merge an ADR and its
+  plan items to `main` before implementation work begins, so work
+  branches start from a `main` that already carries the numbered ADR.
+- **G2 — check before merge.** Before integrating, sync onto the current
+  `main` (`git fetch` + rebase, or pull in a shared checkout) and run
+  `/audit`. If your ADR number or `plan/todo` slot now clashes with what
+  landed on `main`, renumber locally **before** integrating — a trivial,
+  local change (a new ADR/plan names its own number only in its own file
+  and `INDEX.md`).
+- **G3 — gate backstop.** Integration is single-threaded; it rejects a
+  duplicate number as the last line of defence, and the later author
+  renumbers.
+-->
+
 ## Audit Trail Policy
 
 Every substantive change to an Accepted ADR appends a new row to its

package/skills/bootstrap/templates/_agent-prompts-autonomous.md

@@ -42,6 +42,18 @@ footer required on any commit touching an ADR.
 
 ## Step 6 — Integrate
 
+<!-- Concurrency guardrail G2 (multi-agent / PR-based repos) — keep this
+step if CONVENTIONS.md has a §Concurrency Guardrails section; drop it for
+single-agent direct-to-main repos:
+
+- **Check before merge (G2).** Sync onto the current `main`
+  (`git fetch` + rebase, or pull in a shared checkout) and run `/audit`.
+  If your new ADR or `plan/todo` number now clashes with what landed on
+  `main`, renumber locally — in your ADR/plan file and `INDEX.md` —
+  before integrating. The merge gate (G3) rejects a duplicate as the
+  backstop.
+-->
+
 <!-- Integration model per Q4b — keep ONE of the two blocks below,
 delete the other. -->