allye-pi 2.0.0 → 2.1.1

package/README.md

@@ -95,6 +95,8 @@ bootstrap/allye.md          shared bootstrap text (single source)
 skills/bridge/              the Bridge skill and its references
 skills/bridge-*/            the crew skills (Armorer, Recon, Strategist, Architect, Dispatcher,
                             Pilot, Copilot, Medic, Optimizer, Shield, Watcher)
+agents/bridge-*.md          native crew subagents (Claude Code; OpenCode registers them from here):
+                            load the matching crew skill under a per-role tool allowlist
 hooks/                      Claude Code SessionStart hook
 .claude-plugin/, .mcp.json  Claude Code plugin and marketplace manifests
 manifests/codex/AGENTS.md   Codex copy of the bootstrap (synced)
@@ -110,7 +112,7 @@ docs/                       per-harness install and update guides
 
 ```bash
 npm install
-npm test            # bootstrap, hook, installer and Pi extension tests (offline)
+npm test            # bootstrap, hook, crew agents, installer and Pi extension tests (offline)
 npm run typecheck   # Pi extension
 cd packages/allye-opencode && bun install && bun run typecheck && bun run build
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Allye extension for Pi and OMP: the Allye bootstrap, the Bridge skill and the team gate",
   "type": "module",
   "keywords": [
@@ -45,7 +45,9 @@
     "test:pi": "node --experimental-strip-types --test packages/allye-pi/src/index.test.ts",
     "test:installer": "bash install/test-validation.sh && bash install/test-installer.sh",
     "test:bootstrap": "bash test/test-bootstrap.sh && bash hooks/test-session-start.sh",
-    "test": "npm run test:bootstrap && npm run test:installer && npm run test:pi"
+    "test:agents": "node test/test-agents.mjs",
+    "test:skills": "node test/test-skills-text.mjs",
+    "test": "npm run test:bootstrap && npm run test:agents && npm run test:skills && npm run test:installer && npm run test:pi"
   },
   "repository": {
     "type": "git",

package/skills/bridge/SKILL.md

@@ -61,7 +61,7 @@ Composed routes never skip preflight or gates. Every code change runs on a track
 | Mode | References |
 |---|---|
 | `launch`, `mission` | `workflow.md`, `delegation.md`, `state-contract.md`, `publish.md` (§6–7 branch, push and PR) |
-| `blueprint`, `blueprint --auto`, `dispatch` | `discovery.md`, `publish.md`, `delegation.md`, `state-contract.md` (log after publish) |
+| `blueprint`, `blueprint --auto`, `dispatch` | `discovery.md`, `publish.md`, `spec-lint.md` (before any spec write), `delegation.md`, `state-contract.md` (log after publish) |
 | `repair`, `optimize`, `shield` | `workflow.md`, `delegation.md`, `state-contract.md`, `publish.md` |
 | `inspect`, `survey` | `delegation.md`, `workflow.md` (§11) |
 

package/skills/bridge/references/delegation.md

@@ -1,6 +1,6 @@
 # Delegation
 
-Agents are mandates, not persistent processes. The Mothership dispatches each one with a task packet through the harness's native subagent mechanism, or plays the role itself when the harness has none. Never create persistent custom agents, watchers or shell wrappers to emulate delegation.
+Agents are mandates, not persistent processes. The Mothership dispatches each one with a task packet through the harness's native subagent mechanism, or plays the role itself when the harness has none. Never create persistent custom agents, watchers or shell wrappers to emulate delegation; the native crew agents the plugin ships (below) are the only typed agents you use.
 
 ## Roles
 
@@ -18,9 +18,27 @@ Agents are mandates, not persistent processes. The Mothership dispatches each on
 | Shield | reviewer | read-only | Security veto by severity |
 | Watcher | reviewer | read-only | Full diff, never a sample |
 
-Use the role map from Armorer's preflight: native reviewer → Medic, Optimizer, Watcher; native security reviewer → Shield; read-only explorer → Recon; general worker → Pilot, Copilot, Strategist, Architect, Dispatcher. If a specialized type is missing, use a general worker with the same mandate and limits; read-only roles stay read-only by mandate.
+Use the role map from Armorer's preflight. A native crew agent for the role (see Native crew agents) always wins. Otherwise: native reviewer → Medic, Optimizer, Watcher; native security reviewer → Shield; read-only explorer → Recon; general worker → Pilot, Copilot, Strategist, Architect, Dispatcher. If a specialized type is missing, use a general worker with the same mandate and limits; read-only roles stay read-only by mandate.
 
-Tell each subagent to load skill `bridge-<agent>` by name, or — if the harness has no skill loader — to read `../bridge-<agent>/SKILL.md` relative to the `bridge` skill's directory (give the resolved absolute path in the packet), and include the full packet.
+Tell each subagent to load skill `bridge-<agent>` by name, or — if the harness has no skill loader — to read `../bridge-<agent>/SKILL.md` relative to the `bridge` skill's directory (give the resolved absolute path in the packet), and include the full packet. Native crew agents are already told to load their skill; the packet still carries `skill`.
+
+## Native crew agents
+
+Where the plugin can ship typed subagents, each crew role has one, named `bridge-<agent>`, that loads skill `bridge-<agent>` and enforces the role's mandate with a tool allowlist. The skill stays the single source of behavior; the agent file adds only the tool ceiling. Dispatch the native agent when Armorer lists it in `nativeCrewAgents` (for Armorer itself, which runs before any role map, when the type is visible in your own dispatch tool); otherwise use the generic worker and tell it to load the skill (above). Never mix: a role is dispatched either as its native agent or as a generic worker carrying the full mandate.
+
+| Harness | Native crew agents | Dispatch |
+|---|---|---|
+| Claude Code | `agents/bridge-<agent>.md` in the plugin (auto-discovered) | `Agent` with `subagent_type: allye:bridge-<agent>` |
+| OpenCode | registered by the `allye-opencode` plugin's `config` hook from the same `agents/*.md` (`mode: subagent`; permissions deny every tool, then allow the role's allowlist) | `task` with `subagent_type: bridge-<agent>` |
+| Codex | none: Codex reads custom agents only from `~/.codex/agents/` and `.codex/agents/`, and its plugins cannot ship them; its agent files have no tool allowlist | generic worker + skill |
+| Pi | none: core Pi has no subagents, and packages cannot ship agent definitions | generic worker + skill (or sequential fallback) |
+| OMP | none yet: OMP can discover a plugin's `agents/*.md`, but its frontmatter and tool names differ from this format, so `allye-pi` does not ship them | built-in agent types + skill |
+
+Tool ceilings, from `agents/*.md`:
+
+- Read-only roles (Armorer, Recon, Strategist, Architect, Copilot, Medic, Optimizer, Shield, Watcher) never get file-editing tools. Bash only where the role must run commands: Armorer (tool checks), Recon (reproduce, git history), Copilot (rerun verify, scope check), Medic (run covering tests), Optimizer, Shield and Watcher (read the diff at the reviewed point with git). Strategist, Architect and Dispatcher have no shell; Architect may read primary sources on the web.
+- Dispatcher may edit files only to write `docs/code-guide.md` in `guide` mode; Pilot edits its slice paths. Path limits come from the packet and the skill, not from the tool list.
+- Allye MCP tools are granted per tool, not per action: every role except Armorer gets `projects`, `epics`, `specs` and `tasks`, which also expose write actions. The Allye MCP access table below still decides which actions each role may call. Armorer gets only its probes (`initialize`, `allye_health_check`, `skills`). No crew agent gets `team` or any subagent-dispatch tool.
 
 ## Task packet
 
@@ -155,9 +173,9 @@ The contracts above are identical everywhere; only the dispatch mechanism change
 
 | Harness | Dispatch | Parallel batch | Asking the user |
 |---|---|---|---|
-| Claude Code | `Agent` tool: explorer type for Recon, general-purpose for the other roles (reviewers read-only by mandate); `run_in_background` for Recon/Architect during interviews; `SendMessage` to continue the same Pilot on corrections | several `Agent` calls in one message | `AskUserQuestion` |
+| Claude Code | `Agent` tool: `subagent_type: allye:bridge-<agent>` when Armorer lists the native crew agents; otherwise explorer type for Recon, general-purpose for the other roles (reviewers read-only by mandate); `run_in_background` for Recon/Architect during interviews; `SendMessage` to continue the same Pilot on corrections | several `Agent` calls in one message | `AskUserQuestion` |
 | Codex | native subagents when this session's tool list exposes a subagent/spawn tool; if none is listed, sequential fallback | as supported; otherwise sequential | numbered markdown |
-| OpenCode | `task` tool with a subagent (explore for read-only, general for writers) | several `task` calls in one turn | its question tool if available, else numbered markdown |
+| OpenCode | `task` tool: `bridge-<agent>` when Armorer lists the native crew agents; otherwise a subagent (explore for read-only, general for writers) | several `task` calls in one turn | its question tool if available, else numbered markdown |
 | Pi | subagent extension if installed; otherwise sequential fallback | extension-dependent | numbered markdown |
 | OMP | native `task` tool with its built-in agent types; its messaging tool for short handoffs | batch in one `task` call | numbered markdown |
 

package/skills/bridge/references/publish.md

@@ -36,6 +36,8 @@ Ask once. No yes → create nothing. A change to any item after the yes (title,
 
 Dispatch the author (Architect for blueprint, Dispatcher otherwise) with the confirmed list in `mcp.confirmed`; if subagents cannot see the Allye MCP tools, the Mothership makes the same calls itself.
 
+**Lint gate — no partial publish.** Before the first write, the anchor lint (`spec-lint.md`) must pass for **all** specs and tasks in the confirmed list — whoever makes the calls (author or Mothership) runs it. One failure anywhere → create nothing (no epic, no spec, no task), report the failures, fix the content and, if the fix changes a confirmed item, ask for a new confirmation (§3).
+
 1. `epics.epic_create` (project, title, description) when the confirmed list includes an epic.
 2. `specs.spec_create` per spec (project, title, `type`, `content` with anchors, `apps` = that single app, `epic`) — or `specs.spec_update` for a same-scope spec.
 3. `tasks.task_bulk_create` per spec (thin: `temp_id`, title, `refs`, `files`, `verify`, `notes` ≤2000, `depends_on_temp_ids`). Map temp ids to the returned keys; never map by position.
@@ -69,6 +71,14 @@ Never deploy. Merge into any branch only when the person commanding the chat exp
 
 Stop at the first failed write. Re-read what exists (`specs.spec_list` with `project`, `spec_context`, `epic_get`), report created vs. missing with real keys, and propose how to finish. No blind retry, no recreation, no destructive rollback (nothing can be deleted; `spec_cancel`/`epic_cancel` only if the user asks).
 
+Resuming after a partial failure (once the user confirms the plan to finish):
+
+1. Fix the cause (e.g. the content that failed the lint or the server's validation) and rerun the anchor lint over every spec still to be written.
+2. Never re-create an epic or spec that already exists: reuse its key (`epic` on the remaining `spec_create` calls); change an existing spec only with `spec_update`.
+3. Create only the missing specs, in the original order.
+4. `tasks.task_bulk_create` is idempotent by title within a spec, so rerunning it for a spec whose tasks were partly created adds only the missing ones; map temp ids to the returned keys as usual.
+5. Add only the missing `spec_dependency_add` links, then continue at the re-read and submit step of §4.
+
 ## Output
 
 ```markdown

package/skills/bridge/references/spec-lint.md

@@ -0,0 +1,22 @@
+# Spec anchor lint
+
+The single checklist every spec and its tasks must pass before they leave the author and again right before the first Allye write. The Architect (`author`, `auto` and `publish` modes) and the Dispatcher (`spec` and `publish` modes) run it in their self-check; `publish.md` §4 requires it to pass for **all** specs of the confirmed list before anything is created. It is offline: it reads only the drafted content, never the server.
+
+An **anchor definition** is a list item or heading whose text starts with `[KIND-NN]` (e.g. `- [D-01] …`, `### [AC-02] …`). Any other occurrence is an **inline reference** (e.g. "see [D-01]", "covers [AC-02]") and is always allowed. The server rejects a spec that defines the same id twice (`specs.spec_create` → `SPEC_DUPLICATE_ANCHOR`, "each anchor must appear once").
+
+## Checklist
+
+Run every item per spec; report each failure with the spec, the anchor or task and the line.
+
+1. **Unique definitions** — each anchor id is defined exactly once in the spec. A shared contract `[D-NN]` defined under Contracts is never defined again under Decisions; elsewhere it appears only inline ("see [D-01]"), never at the start of a list item or heading.
+2. **Well-formed ids** — every definition matches `[BR-NN]`, `[AC-NN]`, `[D-NN]`, `[NFR-NN]` or `[Q-NN]` with two or more digits (`[AC-01]`, not `[AC-1]`, `[ac-01]` or `[AC 01]`).
+3. **Open items listed** — list every open `[Q-NN]` (no `(resolved)` marker) and every `[NEEDS CLARIFICATION]` explicitly in the output; each one blocks `specs.spec_submit`, so the spec stays `draft`.
+4. **Task refs resolve** — every entry in a task's `refs` names an anchor defined in that task's own spec.
+5. **AC coverage** — every `[AC-NN]` is referenced by at least one task's `refs`.
+6. **Task notes size** — every task's `notes` is at most 2000 characters.
+7. **Shared contracts match** — a `[D-NN]` shared across specs (multi-app) has the same number and identical text in every spec that shares it.
+
+## Outcome
+
+- All items pass → the content may be returned (author/spec modes) or written (publish mode).
+- Any item fails → fix it before returning; in `publish` mode, write nothing and return `blocked` with the failures. Never publish a subset of the specs to work around a failing one.

package/skills/bridge-architect/SKILL.md

@@ -44,6 +44,7 @@ Follow `references/spec-template.md`: one Allye spec with **Functional** and **T
 
 **Functional self-check** — every rule has an observable acceptance criterion; error flows and non-goals are explicit; no invented decision; nothing contradicts the ledger. Fail → fix before the technical part.
 **Technical self-check** — every `[AC-NN]` has a mechanism and a validation; cross-app contracts have a compatible order; failure handling and rollback are executable; security and operations have signals. Uncertain facts carry a validation plan, never presented as fact.
+**Anchor lint** — after the tasks are drafted, and again after every challenge fix, run `../bridge/references/spec-lint.md` (relative to this skill's directory) over every spec and its tasks: unique anchor definitions, well-formed ids, open `[Q-NN]`/`[NEEDS CLARIFICATION]` listed, task refs resolve, every `[AC-NN]` covered, notes ≤2000 chars, shared `[D-NN]` identical across specs. Fail → fix before returning; never return content that fails it.
 
 ## Challenge round
 
@@ -55,7 +56,7 @@ Thin tasks per spec, each with a `tempId`, unique imperative title, `refs` to an
 
 ## Allye MCP
 
-Your rights are the Architect row of `../bridge/references/delegation.md` → Allye MCP access (the single source): the common reads; writes only the items in the packet's `mcp.confirmed` list (content they authored, confirmed by the user): `epics.epic_create`/`epic_update`, `specs.spec_create`/`spec_update`, `tasks.task_bulk_create`/`task_create`/`task_update`, `specs.spec_dependency_add`. The Dispatcher creates an epic only when the confirmed list includes one. You write only in `publish` mode, in order: `epics.epic_create` → `specs.spec_create` (or `spec_update`) → `tasks.task_bulk_create` per spec (map temp ids to returned keys, never by position) → `specs.spec_dependency_add`. Stop at the first failure and report what exists. Report every write in `mcpWrites`.
+Your rights are the Architect row of `../bridge/references/delegation.md` → Allye MCP access (the single source): the common reads; writes only the items in the packet's `mcp.confirmed` list (content they authored, confirmed by the user): `epics.epic_create`/`epic_update`, `specs.spec_create`/`spec_update`, `tasks.task_bulk_create`/`task_create`/`task_update`, `specs.spec_dependency_add`. The Dispatcher creates an epic only when the confirmed list includes one. You write only in `publish` mode. Before the first write, rerun the anchor lint (`../bridge/references/spec-lint.md`) over **all** confirmed specs and tasks; any failure → write nothing and return `blocked` with the failures. Then, in order: `epics.epic_create` → `specs.spec_create` (or `spec_update`) → `tasks.task_bulk_create` per spec (map temp ids to returned keys, never by position) → `specs.spec_dependency_add`. Stop at the first failure and report what exists. Report every write in `mcpWrites`.
 
 ## Structured output
 
@@ -89,7 +90,7 @@ filesRead: [<paths>]
 filesChanged: []
 ```
 
-`ready` means both self-checks passed and the challenge round ended with no open CRITICAL/HIGH outside an open `[Q-NN]`. Anything else is `needs-input` (questions, Recon or challenge pending) or `blocked` (with the smallest question that would unblock it).
+`ready` means both self-checks and the anchor lint passed and the challenge round ended with no open CRITICAL/HIGH outside an open `[Q-NN]`. Anything else is `needs-input` (questions, Recon or challenge pending) or `blocked` (with the smallest question that would unblock it).
 
 ## Limits
 

package/skills/bridge-architect/references/spec-template.md

@@ -1,6 +1,6 @@
 # Full spec template
 
-One Allye spec per app. The content below is the spec's markdown body (`specs.spec_create content`). Anchors start a list item or heading: `[BR-NN]` rule, `[AC-NN]` acceptance criterion, `[D-NN]` decision, `[NFR-NN]` non-functional, `[Q-NN]` question. Number from `01`, never renumber; drop an anchor by removing it. Omit a section that genuinely does not apply by writing `n/a — <why>`; never leave a heading empty. Compact Mermaid diagrams are welcome when they clarify a flow or state; avoid fragile file inventories.
+One Allye spec per app. The content below is the spec's markdown body (`specs.spec_create content`). Anchors start a list item or heading: `[BR-NN]` rule, `[AC-NN]` acceptance criterion, `[D-NN]` decision, `[NFR-NN]` non-functional, `[Q-NN]` question. Number from `01`, never renumber; drop an anchor by removing it. Every anchor id is **defined exactly once per spec** — one list item or heading starting with it; everywhere else it is referenced inline ("see [D-01]"), never at the start of a list item or heading. A shared cross-spec contract is defined once, under Contracts and compatibility, and is not repeated as an anchor under Decisions (the server rejects a repeated anchor with `SPEC_DUPLICATE_ANCHOR`). Before returning, run `../../bridge/references/spec-lint.md`. Omit a section that genuinely does not apply by writing `n/a — <why>`; never leave a heading empty. Compact Mermaid diagrams are welcome when they clarify a flow or state; avoid fragile file inventories.
 
 ```markdown
 # <Outcome-oriented title>
@@ -45,7 +45,7 @@ One Allye spec per app. The content below is the spec's markdown body (`specs.sp
 
 ### Contracts and compatibility
 <API, event or data contracts; versioning; backward compatibility; order relative to dependent specs.>
-- [D-01] (user) <cross-app contract> — <rationale>     ← same number and text in every spec that shares it
+- [D-01] (user) <cross-app contract> — <rationale>     ← defined here only; same number and text in every spec that shares it
 
 ### Data and migration
 <Schema/data changes, migration, backfill, consistency. n/a when none.>
@@ -69,6 +69,7 @@ One Allye spec per app. The content below is the spec's markdown body (`specs.sp
 <Options considered and why the chosen one wins.>
 
 ## Decisions
+Shared contracts are defined under Contracts and compatibility (see [D-01]); do not define them again here.
 - [D-02] (user) <decision> — <rationale>
 - [D-03] (source: <path or doc>) <decision confirmed by evidence> — <rationale>
 - [D-04] (proposed) <architect's recommendation, not yet contested> — <rationale>
@@ -85,6 +86,7 @@ One Allye spec per app. The content below is the spec's markdown body (`specs.sp
 
 - Decision origin: `(user)` — the user decided or accepted it; `(source: …)` — established by code, docs or a primary source; `(proposed)` — the Architect's recommendation (all choices in `blueprint --auto`).
 - Every `[BR-NN]` is covered by at least one `[AC-NN]`; every `[AC-NN]` is observable and testable as written.
+- One definition per anchor id per spec; every other mention is inline. The anchor lint (`../../bridge/references/spec-lint.md`) must pass before the spec is returned and again before it is published.
 - English throughout, even when the interview ran in another language.
 - No secrets, tokens, internal URLs with credentials, or unnecessary personal data.
 - The epic (multi-app only) is a short description: shared outcome, the specs and their order, compatibility notes, done condition.

package/skills/bridge-armorer/SKILL.md

@@ -34,6 +34,7 @@ You make sure the requested mode has every capability it needs before the Mother
 3. **MCP for subagents.** If you run as a subagent, check whether the `allye` MCP tools are in your own tool list — that is direct evidence of what other subagents get. Present → `subagentMcp: available` (crew members read and write Allye within their roles, see `../bridge/references/delegation.md`); absent → `unavailable` (satisfied by the fallback: the Mothership makes those calls on their behalf and embeds content in packets). In sequential fallback, `n/a`. When this check cannot be observed directly, report `unavailable` until a subagent shows otherwise — never assume access.
 4. **Question channel.** Native question tool present (e.g. Claude Code `AskUserQuestion`) → native; otherwise numbered markdown rounds (satisfied).
 5. **Agent types → crew roles.** Map what the harness offers before declaring anything missing:
+   - native crew agent `bridge-<agent>` (Claude Code: `allye:bridge-<agent>` in the `Agent` tool's agent types; OpenCode: `bridge-<agent>` among the `task` tool's subagents) → that role, always first. List each one you see in `nativeCrewAgents`; a role without one falls through to the types below (`../bridge/references/delegation.md` → Native crew agents);
    - native reviewer → Medic, Optimizer, Watcher;
    - native security reviewer → Shield (else a native reviewer with Shield's mandate);
    - read-only explorer → Recon;
@@ -71,6 +72,7 @@ harness:
   delegation: parallel|sequential
   subagentMcp: available|unavailable|n/a
   questions: native|markdown
+  nativeCrewAgents: [<observed type names, e.g. allye:bridge-pilot; [] when none>]
   roleMap: { recon: <type>, strategist: <type>, pilot: <type>, copilot: <type>, medic: <type>, optimizer: <type>, shield: <type>, watcher: <type>, architect: <type>, dispatcher: <type> }
 pluginVersion: <version>
 allye: { connected: true|false, activeTeam: <name|null> }

package/skills/bridge-dispatcher/SKILL.md

@@ -44,6 +44,7 @@ No target app or too little context → `blocked` with what is missing; never pr
    Rules and criteria become `[BR-NN]` and `[AC-NN]` (EARS or Given/When/Then).
 4. **Write** the spec with `references/spec-template-minimal.md`, in English.
 5. **Tasks.** Draft thin tasks: `tempId`, unique imperative title, `refs` to anchors, `files`, `verify` derived from the repo's scripts, `dependsOn` by temp id, short `notes` (≤2000 chars, never restating rules). Every `[AC-NN]` referenced by at least one task.
+6. **Anchor lint.** Run `../bridge/references/spec-lint.md` (relative to this skill's directory) over the spec and its tasks — unique anchor definitions, well-formed ids, open `[Q-NN]`/`[NEEDS CLARIFICATION]` listed, task refs resolve, every `[AC-NN]` covered, notes ≤2000 chars, shared `[D-NN]` identical. Fail → fix before returning; never return content that fails it.
 
 **Hand back to the Architect** (`status: escalate`) when the change spans several apps, needs a cross-app contract, is systemic (architecture, migrations across services, security model), or needs more than three questions to bound.
 
@@ -66,7 +67,7 @@ No target app or too little context → `blocked` with what is missing; never pr
 
 ## Allye MCP
 
-Your rights are the Dispatcher row of `../bridge/references/delegation.md` → Allye MCP access (the single source): the common reads; writes only the items in the packet's `mcp.confirmed` list (content they authored, confirmed by the user): `epics.epic_create`/`epic_update`, `specs.spec_create`/`spec_update`, `tasks.task_bulk_create`/`task_create`/`task_update`, `specs.spec_dependency_add`. The Dispatcher creates an epic only when the confirmed list includes one. You write only in `publish` mode, in order: `epics.epic_create` (only when confirmed) → `specs.spec_create` (or `spec_update` when revising) → `tasks.task_bulk_create` (map temp ids to returned keys, never by position) → `specs.spec_dependency_add` (only when confirmed). Stop at the first failure and report what exists. Report every write in `mcpWrites`.
+Your rights are the Dispatcher row of `../bridge/references/delegation.md` → Allye MCP access (the single source): the common reads; writes only the items in the packet's `mcp.confirmed` list (content they authored, confirmed by the user): `epics.epic_create`/`epic_update`, `specs.spec_create`/`spec_update`, `tasks.task_bulk_create`/`task_create`/`task_update`, `specs.spec_dependency_add`. The Dispatcher creates an epic only when the confirmed list includes one. You write only in `publish` mode. Before the first write, rerun the anchor lint (`../bridge/references/spec-lint.md`) over all confirmed specs and tasks; any failure → write nothing and return `blocked` with the failures. Then, in order: `epics.epic_create` (only when confirmed) → `specs.spec_create` (or `spec_update` when revising) → `tasks.task_bulk_create` (map temp ids to returned keys, never by position) → `specs.spec_dependency_add` (only when confirmed). Stop at the first failure and report what exists. Report every write in `mcpWrites`.
 
 ## Structured output
 

package/skills/bridge-dispatcher/references/spec-template-minimal.md

@@ -1,6 +1,6 @@
 # Minimal spec template
 
-For a known, bounded change in one app. It uses the same anchors as the full template (`[BR]`, `[AC]`, `[D]`, `[NFR]`, `[Q]`, numbered from `01`) so the server can track coverage and block submission on open questions. Drop an optional section only when it truly does not apply.
+For a known, bounded change in one app. It uses the same anchors as the full template (`[BR]`, `[AC]`, `[D]`, `[NFR]`, `[Q]`, numbered from `01`) so the server can track coverage and block submission on open questions. Every anchor id is **defined exactly once per spec** — one list item or heading starting with it; everywhere else it is referenced inline ("see [D-01]"), never at the start of a list item or heading (the server rejects a repeated anchor with `SPEC_DUPLICATE_ANCHOR`). A contract decision lives in Decisions only; the Contract section refers to it inline. Drop an optional section only when it truly does not apply.
 
 ```markdown
 # <Outcome-oriented title>
@@ -50,4 +50,4 @@ For a known, bounded change in one app. It uses the same anchors as the full tem
 - [Q-02] <open blocker — owner and impact>     ← blocks spec_submit
 ```
 
-Rules: English throughout; every `[BR-NN]` covered by an `[AC-NN]`; no secrets or unnecessary personal data. If filling this template needs a Technical section of its own (data migration, cross-app contract, security model), the change belongs to the Architect.
+Rules: one definition per anchor id, every other mention inline; the anchor lint (`../../bridge/references/spec-lint.md`) passes before the spec is returned and again before it is published; English throughout; every `[BR-NN]` covered by an `[AC-NN]`; no secrets or unnecessary personal data. If filling this template needs a Technical section of its own (data migration, cross-app contract, security model), the change belongs to the Architect.