hatch3r 1.9.0 → 2.0.0

package/dist/content/skills/hatch3r-adhoc-orchestrate/SKILL.md

@@ -0,0 +1,131 @@
+---
+id: hatch3r-adhoc-orchestrate
+name: hatch3r-adhoc-orchestrate
+type: skill
+description: Scaffolds the ad-hoc Tier >= 2 orchestration protocol -- Per-Turn Pipeline-State Header, implementer delegation plan, End-of-Turn Delegation Attestation. Use for a maintainer multi-phase task with no registered command to avoid bypass mode.
+tags: [orchestration]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+parallel_tool_default: true
+sub_agents_spawned:
+  count: 0
+  rationale: This is a scaffolding skill — it emits the orchestration-protocol blocks for the maintainer's own multi-phase task; the maintainer's task then spawns its own implementer/fixer sub-agents per the plan this skill produces. The skill itself delegates nothing.
+---
+
+# Ad-Hoc Orchestration Scaffold
+
+## Quick Start
+
+```
+Task Progress:
+- [ ] Step 0: Detect ambiguity (P8 B1)
+- [ ] Step 1: Score the task tier (Tier >= 2 gate)
+- [ ] Step 2: Emit the Per-Turn Pipeline-State Header
+- [ ] Step 3: Build the delegation plan (no inline implementation)
+- [ ] Step 4: Emit the End-of-Turn Delegation Attestation template
+- [ ] Step 5: Verify the bypass-protection checklist
+```
+
+A multi-phase task driven by hand — research + implement + review, no registered `/h4tcher-*` command — is still bound by the **Orchestrator Self-Discipline (Bypass Protection)** contract in `CLAUDE.md` and `rules/hatch3r-agent-orchestration.md`. The CHANGELOG #73 failure mode is exactly this: running research and review sub-agents while inlining the implementation, escaping the protocol because no command was invoked. This skill is the turnkey scaffold that closes that loophole — it does not perform the work; it emits the three required protocol blocks so the maintainer's ad-hoc flow stays attributable.
+
+Use this skill at the start of any maintainer-side multi-phase task at Tier >= 2 that is NOT already running under a registered command (which carries these blocks itself). When the work matches a registered intent, prefer the command: `/h4tcher-capability-add`, `/h4tcher-capability-refactor`, `/h4tcher-capability-remove` for lifecycle work; `commands/hatch3r-*.md` for end-user content workflows.
+
+## Step 0 — Detect Ambiguity (P8 B1)
+
+Before any work, scan the invocation for unresolved questions in scope, intent, acceptance criteria, target files, or irreversibility. If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md`. Do not proceed under silent assumption. Default path, not an exception. Triggers for THIS skill: the task tier is genuinely uncertain (Tier 1 vs Tier 2 changes whether the protocol even applies), the set of files to mutate is unbounded, or a registered command already covers the intent (route there instead of scaffolding).
+
+## Step 1: Score the Task Tier (Tier >= 2 Gate)
+
+The protocol binds at Tier 2 and Tier 3 only. Score the task per the `hatch3r-deep-context` rule (deep-context score >= 3 → Tier >= 2):
+
+- **Tier 1** — trivial single-file edit, no cross-module reasoning. The header and attestation are NOT required; a single targeted edit is acceptable. State "Tier 1 — protocol not required" and exit the scaffold.
+- **Tier 2** — multi-file or behavior-changing task with bounded scope. Full protocol applies.
+- **Tier 3** — multi-module / high-risk task. Full protocol applies; fan out one sub-agent per independent module per `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+Record the score and the one-line rationale. The tier is the load-bearing input to every block below.
+
+## Step 2: Emit the Per-Turn Pipeline-State Header
+
+At the START of every assistant turn that touches the task, emit the single-line header per `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header:
+
+```
+[hatch3r-pipeline: phase {1|2|3|4} | last: {agent} → {SUCCESS|PARTIAL|FAILED|BLOCKED|n/a} | next: {agent or "user-confirmation" or "complete"}]
+```
+
+Example first turn: `[hatch3r-pipeline: phase 1 | last: n/a | next: hatch3r-researcher]`
+
+Phase mapping for an ad-hoc task (mirror the four-phase pipeline):
+
+| Phase | Meaning | Driving agent |
+|-------|---------|---------------|
+| 1 | Research / context gathering | `hatch3r-researcher` |
+| 2 | Implementation | `hatch3r-implementer` |
+| 3 | Review loop | `hatch3r-reviewer` ↔ `hatch3r-fixer` |
+| 4 | Final quality + summary | parallel specialists, then iteration summary |
+
+A missing header on a Tier >= 2 turn is a self-detectable drift signal — halt and re-ground rather than continuing blind.
+
+## Step 3: Build the Delegation Plan (No Inline Implementation)
+
+The hard constraint: the orchestrator turn MUST NOT call any code-writing tool (`Edit`, `Write`, `MultiEdit`) directly. Code mutation flows ONLY through the Task tool spawning `hatch3r-implementer` (Phase 2) or `hatch3r-fixer` (Phase 3) per `rules/hatch3r-agent-orchestration.md` -> Mandatory Delegation Directive (No Inline Implementation). There is no Tier-1 carve-out here — Tier 1 exits at Step 1.
+
+Produce a delegation plan before touching any file:
+
+```
+Delegation Plan:
+  Phase 1 — research:   hatch3r-researcher, modes: {…}, depth: {quick|standard|deep}
+  Phase 2 — implement:  hatch3r-implementer × {N}  ({1 per independent module}; correlation_id: {uuid})
+  Phase 3 — review:     hatch3r-reviewer ↔ hatch3r-fixer (max 4 iterations)
+  Phase 4 — quality:    {applicable specialists per the Phase 4 Specialist Trigger Table}
+  sub_agents_spawned:   { count: {N}, rationale: {one-sentence task-decomposition justification} }
+```
+
+Fan-out scales with task decomposition, not token budget (P8 B2 dominates P7): N independent modules → N parallel Phase-2 implementers; serialize only on true dependency edges (shared files, ordered handoffs). Every delegation prompt carries the confidence expression requirement and the `correlation_id` per the orchestration rule.
+
+## Step 4: Emit the End-of-Turn Delegation Attestation Template
+
+Every turn that mutated files at Tier >= 2 emits the attestation block immediately BEFORE the Iteration Summary (beside it, not inside it — the iteration-summary contract stays verbatim), per `rules/hatch3r-agent-orchestration.md` -> End-of-Turn Delegation Attestation:
+
+```
+[hatch3r-delegation-attestation]
+files_mutated_this_turn:
+  - <relative path>: via <hatch3r-implementer | hatch3r-fixer> (proof: <delegation_proof_id>)
+mutating_subagent_invocations: <integer>
+inline_edits_by_orchestrator: none
+```
+
+Why it is forgery-resistant: the per-file `delegation_proof_id` is returned by `hatch3r-implementer` / `hatch3r-fixer` in their structured results (`agents/hatch3r-implementer.md` -> Return Structured Result; `agents/hatch3r-fixer.md` -> Return Structured Result). Quote it verbatim. A turn that skipped delegation has no `delegation_proof_id` to quote — its row is unattributable, which is a self-declared P8 B2 violation: halt and queue re-delegation next turn. `inline_edits_by_orchestrator: none` is the only accepted value in an ad-hoc flow (the `hatch3r-quick-change` Tier-1 carve-out does not apply outside that command).
+
+## Step 5: Bypass-Protection Checklist
+
+Before declaring the turn complete, verify every item — a failed item is the CHANGELOG #73 bypass mode:
+
+- [ ] Task tier scored; protocol applied iff Tier >= 2 (Step 1).
+- [ ] Per-Turn Pipeline-State Header emitted at the start of every task-touching turn (Step 2).
+- [ ] Zero inline `Edit` / `Write` / `MultiEdit` from the orchestrator turn; every code mutation went through `hatch3r-implementer` or `hatch3r-fixer` (Step 3).
+- [ ] End-of-Turn Delegation Attestation emitted before the Iteration Summary, every mutated file attributed to a sub-agent with its `delegation_proof_id` quoted verbatim (Step 4).
+- [ ] `sub_agents_spawned: { count, rationale }` emitted as a first-class field per `rules/hatch3r-fan-out-discipline.md`.
+- [ ] Iteration Summary follows per `rules/hatch3r-iteration-summary.md`.
+
+## Error Handling
+
+- **Unattributable mutation row:** a file was mutated but no `delegation_proof_id` exists for it → the orchestrator inlined the edit. This is a P8 B2 violation. Halt the turn, queue re-delegation of that file through `hatch3r-implementer`/`hatch3r-fixer` next turn, and note the bypass in the attestation block.
+- **Tier misclassification surfaces mid-task:** a Tier-1-scored task that grows to touch multiple modules → re-score to Tier >= 2 immediately, begin emitting the header and attestation from the current turn, and re-delegate any already-inlined edits.
+- **Registered command exists for the intent:** if mid-scaffold you recognize the task matches a registered `/h4tcher-*` command or `commands/hatch3r-*.md`, stop scaffolding and route to that command — it carries these blocks natively and avoids hand-maintained drift.
+
+## Definition of Done
+
+- [ ] Tier scored; protocol applied at Tier >= 2 or skipped at Tier 1.
+- [ ] Header emitted on every task-touching turn.
+- [ ] No inline orchestrator edits; all mutations attributed to a delegated sub-agent.
+- [ ] Attestation block emitted before the Iteration Summary with verbatim `delegation_proof_id`s.
+- [ ] `sub_agents_spawned` count + rationale present.
+
+## References
+
+- `CLAUDE.md` -> "Orchestrator Self-Discipline (Bypass Protection)" — the three-requirement contract this skill scaffolds; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `rules/hatch3r-agent-orchestration.md` -> Per-Turn Pipeline-State Header, End-of-Turn Delegation Attestation, Mandatory Delegation Directive (No Inline Implementation) — block formats and rules reproduced here; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `rules/hatch3r-fan-out-discipline.md` — P8 B2 fan-out scaling, `sub_agents_spawned` first-class field, attestation forgery-resistance rationale; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- `skills/hatch3r-incident-response/SKILL.md` — canonical skill structure (Quick Start + Step pattern + Fan-out Discipline section) modeled here; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).
+- hatch3r governance self-audit analysis — source rationale for the missing ad-hoc Tier >= 2 orchestrator scaffold; accessed 2026-05-31; trust tier: official-docs (in-repo canonical).

package/dist/content/skills/hatch3r-ai-feature/SKILL.md

@@ -1,5 +1,6 @@
 ---
 id: hatch3r-ai-feature
+name: hatch3r-ai-feature
 type: skill
 description: Eval-driven development workflow for shipping AI features — write eval before prompt, measure, iterate, ship with caching + cost telemetry + model fallback + hallucination SLI
 tags: [implementation, ai]
@@ -11,6 +12,8 @@ cache_friendly: true
 
 ## Quick Start
 
+**Applies when:** the project ships an LLM/AI feature. On a project with no AI feature, skip — do not scaffold AI machinery pre-emptively (per `rules/hatch3r-right-sizing.md`).
+
 Run this skill before shipping any LLM-driven feature. It defines the canonical eval-driven loop (write eval, write prompt, measure, iterate) and the production-readiness gates. Skipping any of the 9 steps = the feature is not done.
 
 This skill is the implementation counterpart to `rules/hatch3r-ai-evals.md` (backend governance) and `rules/hatch3r-ai-ux-patterns.md` (UI governance). The rules define the bar; this skill defines the route to clearing the bar.
@@ -21,12 +24,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Define the task and success criteria
 

package/dist/content/skills/hatch3r-api-spec/SKILL.md

@@ -1,7 +1,8 @@
 ---
 id: hatch3r-api-spec
+name: hatch3r-api-spec
 type: skill
-description: Generate and validate OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
+description: Generates and validates OpenAPI specifications from codebase. Covers endpoint design, schema validation, and documentation generation.
 tags: [planning]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -10,6 +11,16 @@ cache_friendly: true
 
 # API Specification Workflow
 
+## Relationship to `commands/hatch3r-api-spec.md` (Decision 13 handoff)
+
+This skill shares the `id: hatch3r-api-spec` with the orchestrator command `commands/hatch3r-api-spec.md`. The two are NOT duplicates — they split the OpenAPI workflow by execution model per CONSTITUTION §6 Decision 13:
+
+- **`commands/hatch3r-api-spec.md` (orchestrator entry):** the canonical multi-agent pipeline — researcher scans routes, docs-writer assembles the spec, reviewer validates (`agentPipeline: [hatch3r-researcher, hatch3r-docs-writer, hatch3r-reviewer]`). Use the command when the workflow warrants sub-agent fan-out (Tier 2/3 framework detection, drift detection, breaking-change review).
+- **This skill (inline procedure):** the single-pass reference body the command's docs-writer and reviewer stages follow when assembling and validating the spec. Use the skill directly for Tier 1 single-endpoint spec edits where no fan-out is needed, OR as the step-by-step procedure cited inside the command's Step 5 (OpenAPI Assembly) and Step 6 (Validation).
+- **Unique to this skill:** Step 6 (`oasdiff` breaking-change CI gate wiring) is the inline-procedure detail the command references rather than restates.
+
+The merge-candidate review (F16.3-H3) flagged the shared id; this handoff documentation is the explicit workflow-split declaration that disambiguates the pair. A future collapse into a single command appendix requires coordinated edits to the command body, the bundled content inventory (skills count), and the Decision-13 anti-duplicate-id gate in `src/cli/commands/validate.ts`.
+
 ## Quick Start
 
 ```
@@ -69,7 +80,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Step 6: Wire `oasdiff` Breaking-Change CI Gate
 
-Breaking changes on stable endpoints must trip CI before merge. This step enforces the CONSTITUTION §2 P5 lean-thresholds row "API breaking-change events on stable endpoints = 0 per release" (governance/CONSTITUTION.md:80, verified by `oasdiff / buf breaking / graphql-inspector CI gate`).
+Breaking changes on stable endpoints must trip CI before merge. This step enforces the canonical lean-threshold floor "API breaking-change events on stable endpoints = 0 per release" (see `agents/shared/principles.md`, verified by `oasdiff / buf breaking / graphql-inspector CI gate`).
 
 ### 6.1 Install `oasdiff`
 
@@ -133,6 +144,15 @@ When a breaking change is deliberate (versioned endpoint cut, deprecated field r
 
 The gate stays green only because the change is recorded — not because the breaking signal was silenced.
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single service / one spec file): inline.
+- Tier 2 (multiple services or spec + client-codegen + CI-gate concerns): spawn parallel sub-agents per concern via the Task tool.
+- Tier 3 (cross-service contract suite): one fresh sub-agent per service spec; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Route definitions use dynamic or meta-programmed patterns**: If endpoints are generated at runtime or via decorators that resist static analysis, document the gap and manually enumerate the missing endpoints.
@@ -147,3 +167,8 @@ The gate stays green only because the change is recorded — not because the bre
 - [ ] Example requests/responses included
 - [ ] No breaking changes to existing API consumers
 - [ ] `oasdiff breaking` CI gate is wired and fails on any `ERR`-level breaking change on stable endpoints (CONSTITUTION §2 P5: 0 per release)
+
+## References
+
+- [OpenAPI Specification 3.1.0](https://spec.openapis.org/oas/v3.1.0) — accessed 2026-05-31, official-docs (OpenAPI Initiative). Source for the 3.1 `info`/`components/schemas`/`$ref`/`security` structures and the JSON-Schema-aligned validation keywords used in Steps 2–3.
+- [oasdiff breaking-change detection](https://github.com/Tufin/oasdiff) — accessed 2026-05-31, independent-analysis (Tufin). Source for the `oasdiff breaking --fail-on ERR` CI-gate behavior, `--format githubactions` annotations, and ignore-rules file in Step 6.

package/dist/content/skills/hatch3r-architecture-review/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-architecture-review
-description: Evaluate architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
+name: hatch3r-architecture-review
+type: skill
+description: Evaluates architectural decisions and produce ADRs following the project template. Use when making architectural decisions, evaluating trade-offs, or creating ADRs.
 tags: [review]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -27,12 +29,7 @@ Before any work, scan the invocation for unresolved questions in scope, intent,
 
 ## Fan-out Discipline (P8 B2)
 
-This skill delegates per task size:
-- Tier 1 (trivial single-file): inline execution acceptable.
-- Tier 2 (multi-file or multi-concern): spawn parallel sub-agents per concern via the Task tool.
-- Tier 3 (multi-module / high-risk): one fresh sub-agent per independent module or gate; orchestrator integrates only.
-
-Never under-fan-out to save tokens. Token cost is dominated by quality and completeness gains. Emit `sub_agents_spawned: { count, rationale }` in your output.
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Emit `sub_agents_spawned: { count, rationale }` in your output.
 
 ## Step 1: Read Existing ADRs and Template
 

package/dist/content/skills/hatch3r-board-groom/SKILL.md

@@ -1,5 +1,7 @@
 ---
 id: hatch3r-board-groom
+name: hatch3r-board-groom
+type: skill
 description: Ongoing backlog refinement for existing board items. Re-prioritize, reclassify, re-scope, archive stale items, decompose oversized issues, merge duplicates, refresh dependencies, and remediate board health findings.
 tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
@@ -683,6 +685,15 @@ Board Groom Complete:
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-issue re-scope): inline.
+- Tier 2 (multi-issue grooming with reclassification across lanes): spawn parallel sub-agents per lane via the Task tool.
+- Tier 3 (full-board re-grooming): one fresh sub-agent per lane or epic; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Issue listing failure:** Retry once, then fall back to MCP. If both fail, abort with platform-specific auth guidance:

package/dist/content/skills/hatch3r-board-init/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-board-init
-description: Initialize a project board (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r's label taxonomy, status fields, and board structure. Platform detected from hatch.json.
+name: hatch3r-board-init
+type: skill
+description: Initializes a project board (GitHub Projects V2, Azure Boards, or GitLab Issue Boards) with hatch3r's label taxonomy, status fields, and board structure. Platform detected from hatch.json.
 tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -527,6 +529,15 @@ Board Init Complete:
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-board scaffold with defaults): inline.
+- Tier 2 (board + multiple lanes + seed issues): spawn parallel sub-agents per concern via the Task tool.
+- Tier 3 (multi-board or migration-from-existing init): one fresh sub-agent per board or lane; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **API/CLI failure:** Report the error and suggest checking authentication:
@@ -545,3 +556,8 @@ Board Init Complete:
 - **Never skip Planning questions or the plan confirmation step.**
 - **Require proper authentication** for the configured platform. If mutations fail with permission errors, surface platform-specific auth requirements.
 - **Preserve existing `.hatch3r/hatch.json` content** outside the `board` key when writing config back.
+
+## References
+
+- [Using the API to manage Projects (GraphQL) — GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects) — accessed 2026-05-31, official-docs (GitHub). Source for the `createProjectV2` / `addProjectV2ItemById` / `updateProjectV2ItemFieldValue` mutations and the owner-node-ID requirement in Phase 2.
+- [gh auth refresh — GitHub CLI manual](https://cli.github.com/manual/gh_auth_refresh) — accessed 2026-05-31, official-docs (GitHub). Source for the `project` scope requirement (`gh auth refresh -s project`) and the `GITHUB_TOKEN`/`GH_TOKEN` PAT fallback in the authentication and error-handling steps.

package/dist/content/skills/hatch3r-board-refresh/SKILL.md

@@ -1,6 +1,8 @@
 ---
 id: hatch3r-board-refresh
-description: Regenerate the living board overview dashboard from current board state. Scans all open issues, computes health metrics, and updates the meta:board-overview issue.
+name: hatch3r-board-refresh
+type: skill
+description: Regenerates the living board overview dashboard from current board state. Scans all open issues, computes health metrics, and updates the meta:board-overview issue.
 tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
@@ -245,6 +247,15 @@ Board Refresh Complete:
 
 ---
 
+## Fan-out Discipline (P8 B2)
+
+Fan-out scales with task size; token cost never justifies serializing independent work (`rules/hatch3r-fan-out-discipline.md` P8 B2; `agents/shared/efficiency-patterns.md`). Tier boundaries for THIS skill:
+- Tier 1 (single-board refresh, no re-scoping): inline.
+- Tier 2 (multi-lane refresh with re-scoping or reclassification): spawn parallel sub-agents per lane via the Task tool.
+- Tier 3 (cross-board reconciliation): one fresh sub-agent per board or lane; orchestrator integrates only.
+
+Emit `sub_agents_spawned: { count, rationale }` in your output.
+
 ## Error Handling
 
 - **Issue listing failure:** Retry once, then fall back to MCP. If both fail, abort with platform-specific auth guidance:

package/dist/content/skills/hatch3r-board-shared/SKILL.md

@@ -1,5 +1,7 @@
 ---
 id: hatch3r-board-shared
+name: hatch3r-board-shared
+type: skill
 description: Shared context and procedures for all board commands. Provides platform-agnostic board config, label taxonomy, branch conventions, sync enforcement, and tooling directives. Platform-specific details are in commands/board/shared-{platform}.md.
 tags: [board, ctx:team-only]
 quality_charter: agents/shared/quality-charter.md
@@ -12,7 +14,7 @@ parallel_tool_default: true
 Shared context for `hatch3r-board-fill`, `hatch3r-board-groom`, `hatch3r-board-pickup`, `hatch3r-board-refresh`, and related board commands. Read once per run and cache.
 
 
-## Prerequisite Check (run at the start of every board command)
+## §0 Detect Ambiguity + Prerequisite Check (P8 B1) — run at the start of every board command
 
 Before reading configuration, validate that prerequisites are met. If any check fails, stop immediately with an actionable error message. For interactive sessions where credentials are missing, use the `agents/shared/user-question-protocol.md` plain-text fallback shape to offer the user a numbered choice (interactive login / paste-token / abort) instead of a bare stop message.
 
@@ -299,6 +301,36 @@ The export is idempotent and safe to re-set. `GH_PAGER` is scoped to `gh`; `PAGE
 
 ---
 
+## Todo Grammar
+
+Single source of truth for the `todo.md` line format shared by the producers (`hatch3r-roadmap` Step 5, `hatch3r-project-spec` Step 6) and the consumer (`hatch3r-board-fill` Step 1). Producers MUST emit this grammar; board-fill MUST parse it with the rules below so checkbox glyphs and scope tags never leak into issue titles and priority headers never parse as items.
+
+**Line forms:**
+
+| Form | Pattern | Parse as |
+|------|---------|----------|
+| Priority header | `## P{N} — {Label}` (N = 0–3) | Section header — sets the `priority:p{N}` default for items beneath it. NOT a todo item. |
+| Future-ideas header | `## Future Ideas` | Section header — items beneath it default to `priority:p3`. NOT a todo item. |
+| Todo item | `- [ ] **[{TAG}] {Title}**: {Description}[ Ref: {path}.]` | One todo item. `{TAG}` ∈ `{BIZ, TECH, BOTH}`. |
+
+**Parse rules (board-fill Step 1 applies in order):**
+
+1. **Skip headers.** A line matching `^## ` (priority header or `## Future Ideas`) is a section marker, not an item. Record its `P{N}` value (or `p3` for `## Future Ideas`) as the priority default for items until the next header.
+2. **Strip the list/checkbox token.** Strip a leading list marker (`- ` or `* `) and, if present, a checkbox token (`[ ]` or `[x]`, case-insensitive) that immediately follows it. Lines without `- `/`* ` are not items.
+3. **Extract the scope tag.** Parse the leading `**[{TAG}]` token; capture `{TAG}` ∈ `{BIZ, TECH, BOTH}` and remove it from the title. `BIZ` → business-driven, `TECH` → technically-driven, `BOTH` → cross-cutting. Feed the tag into Step 3 classification (area/executor lean), not the title.
+4. **Split title and description.** The bold span `**…**` is the item title (strip the surrounding `**`); the text after the first `:` is the description. A trailing `Ref: {path}.` carries the source spec/ADR path — surface it as a documentation reference, not part of the title.
+5. **Carry the priority default.** Apply the enclosing header's `P{N}` as the item's default `priority:*` (overridable by Step 3 triage). Items above the first header default to `p2`.
+
+Items not matching the todo-item form (blank lines, prose, stray bullets without a `**[{TAG}]…**` span) are skipped with a one-line note in the parsed-list output so the user can correct malformed entries.
+
+---
+
+## Fan-out Discipline (P8 B2)
+
+Reference library — no fan-out. This skill ships shared board context (configuration, sync procedures, tooling directives) consumed by the delegating board commands (`board-fill`, `board-pickup`, `board-init`, `board-refresh`, `board-groom`). It spawns no sub-agents itself; fan-out is owned by the consuming command per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+---
+
 ## Token-Saving Directives
 
 These apply to all board commands. Follow them to minimize token consumption.
@@ -328,3 +360,8 @@ All mutating board commands MUST maintain a run cache with the following entries
 | `errors` | `{step, issue?, message, recoverable}[]` | All errors encountered during the run |
 
 Initialize all entries at the start of the run. Populate incrementally as operations execute. The reconciliation procedure reads these entries to detect and fix drift.
+
+## References
+
+- [gh auth refresh — GitHub CLI manual](https://cli.github.com/manual/gh_auth_refresh) — accessed 2026-05-31, official-docs (GitHub). Source for the `project` scope requirement (`gh auth refresh -s project`), the classic-PAT `admin:org` note, and the `GITHUB_TOKEN`/`GH_TOKEN` fallback in the prerequisites/authentication section.
+- [Using the API to manage Projects (GraphQL) — GitHub docs](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-api-to-manage-projects) — accessed 2026-05-31, official-docs (GitHub). Source for the Projects V2 IDs, status-field sync, and built-in "Item closed" / "Pull request merged" workflow behavior the shared board config and sync procedures depend on.