@jaybeeuu/agent-cortex 1.41.1 → 1.42.0

package/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 12
           run_install: false
 
       - name: Cache pnpm store
@@ -103,7 +103,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 12
           run_install: false
 
       - name: Install dependencies
@@ -136,7 +136,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 12
           run_install: false
 
       - name: Install dependencies
@@ -169,7 +169,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 12
           run_install: false
 
       - name: Install dependencies
@@ -257,7 +257,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 12
           run_install: false
 
       - name: Install dependencies

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.42.0
+
+### Minor Changes
+
+- 3da7e6e: Bead quality gate: required sections now drive the planning interview, and every substantive
+  bead is validated at creation with `bd create --validate` and reviewed with `bd lint`.
+
+  - The type's required sections are documented once in `bd-tool` and referenced by the
+    interview-driving skills (`write-a-prd`, `request-refactor-plan`, `prd-to-tasks`, `plan`,
+    `ralph-plan`) and the grilling primitives (`grill-me`, `grill-with-docs`). Planning is complete
+    only when there is enough agreed detail to fill every required section, and agents must confirm
+    inferred answers with the human instead of inventing them.
+  - Substantive `bd create` calls carry `--validate`; each bead-creating flow runs a scoped
+    `bd lint` review and fixes flagged beads.
+  - Templates now satisfy the contract: PRD and `prd-to-tasks` epics carry `## Success Criteria`;
+    the refactor and architecture templates, the PR gate, and the ralph-plan planning gates carry
+    `## Acceptance Criteria`. Chore beads stay exempt and instead point at the parent requirements
+    bead.
+  - The stateful fake `bd` test helper models `--validate`, with tests covering rejection of a
+    section-less bead and the PR gate's validated status.
+
+- fdf8ead: Add `spec-to-tickets` for turning a PRD/RFC/spec into an agreed ticket map, then drafting each ticket body with the human in dependency order. Tighten `write-a-ticket` to a Context/Scope/Changes/Acceptance body with length budgets and a no-open-questions rule.
+
 ## 1.41.1
 
 ### Patch Changes

package/agents/ralph-plan/agent.md

@@ -39,7 +39,7 @@ Dispatch parallel **explore** sub-agents — one per independent research area.
 - If the task requires designing a new module API or interface, invoke **design-an-interface** to generate and compare options. Write the output to `.agent-cortex/working-docs/interface-design.md`.
 
 ### 4. Grill the user
-After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. Record answers in `.agent-cortex/working-docs/decisions.md`.
+After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. The grill is complete only when there is enough agreed detail to fill every required section of the target bead type (task/feature → `## Acceptance Criteria`; epic → `## Success Criteria`; see the beads skill). Never invent an answer — surface it as an assumption and confirm it. Record answers in `.agent-cortex/working-docs/decisions.md`.
 
 ### 5. Write the plan
 Update the top-level bead's `design` field with a high-level implementation plan. Invoke the **style-comms** skill first so the plan matches the project's communication style.
@@ -56,14 +56,18 @@ For each new feature bead and each new task bead, create a HITL planning gate be
 Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
 
 ```bash
-gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>")
+gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>
+
+## Acceptance Criteria
+
+- [ ] User confirms planning is sufficient for this feature/task." --validate)
 bd tag <planning-gate-id> implementation-type:hitl
 bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
 ```
 
 Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
 
-Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field.
+Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
 
 Tag every bead created in this step with `workflow:ralph`:
 

package/agents/ralph-plan.agent.md

@@ -47,7 +47,7 @@ Dispatch parallel **explore** sub-agents — one per independent research area.
 - If the task requires designing a new module API or interface, invoke **design-an-interface** to generate and compare options. Write the output to `.agent-cortex/working-docs/interface-design.md`.
 
 ### 4. Grill the user
-After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. Record answers in `.agent-cortex/working-docs/decisions.md`.
+After reviewing exploration findings, invoke the **grill-me** skill to surface and resolve outstanding design questions. Keep grilling until there are no open questions that would block implementation. The grill is complete only when there is enough agreed detail to fill every required section of the target bead type (task/feature → `## Acceptance Criteria`; epic → `## Success Criteria`; see the beads skill). Never invent an answer — surface it as an assumption and confirm it. Record answers in `.agent-cortex/working-docs/decisions.md`.
 
 ### 5. Write the plan
 Update the top-level bead's `design` field with a high-level implementation plan. Invoke the **style-comms** skill first so the plan matches the project's communication style.
@@ -64,14 +64,18 @@ For each new feature bead and each new task bead, create a HITL planning gate be
 Every planning gate description must be cold-start-ready so another person can pick it up without prior chat context. Include all of: (1) what is being built and why, (2) decisions already made, (3) open questions/risks, and (4) references (bead IDs, files, or docs) used during planning.
 
 ```bash
-gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>")
+gate_id=$(bd create "Plan: <feature title>" --type task --description "<planning context, decisions, open questions, and references>
+
+## Acceptance Criteria
+
+- [ ] User confirms planning is sufficient for this feature/task." --validate)
 bd tag <planning-gate-id> implementation-type:hitl
 bd dep add <feature-or-task-id> <planning-gate-id>   # feature/task depends on planning gate (gate blocks implementation)
 ```
 
 Do not close planning gates in bulk. Only close a gate after the user explicitly confirms that exact feature/task is ready to implement; leave all unconfirmed gates open and blocking.
 
-Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field.
+Before handing off, ensure every bead created in this step carries an `implementation-type` label — check `bd label list <id>` yourself. Do not spawn `classify-bead` here: planning gates were tagged inline above and `create-task` classifies its beads internally. Only invoke it for a bead that genuinely lacks both the label and a `## Type` field. Then run `bd lint <id>` for every bead created in this step and fix any missing sections before handoff.
 
 Tag every bead created in this step with `workflow:ralph`:
 

package/docs/ideas/ban-content-assertion-tests.md

@@ -1,7 +1,9 @@
 # Idea: ban-content-assertion-tests
 
 ## Status
-Backlog idea (not implementation-ready) — priority P1 (high)
+Filed as epic `agnt-ctx-h9gt` (2026-10-06) — awaiting `prd-to-tasks`. Slice 1 (the
+`style-tests` ban) shipped earlier in `daa77c8` (PR #143); this epic covers the review-gate
+enforcement and the skill sweep.
 
 ## Created
 2026-08-30

package/docs/ideas/dedicated-review-tests-skill.md

@@ -0,0 +1,71 @@
+# Idea: Dedicated review-tests skill
+
+## Status
+Backlog idea (not implementation-ready) — priority P2 (moderate), timing: follows `agnt-ctx-h9gt`
+
+## Created
+2026-10-06
+
+## Problem
+Test review has no home of its own in the ralph pipeline. The review stage invokes
+`review-security` for a dedicated security pass, then falls back to `style-code` and
+`style-tests` for everything else. `style-tests` is a *writing* skill — it states conventions
+before tests are authored — so a reviewer reading it has to invert authoring guidance into
+review findings. The result is that test defects are caught by whatever the reviewer happens to
+notice rather than by an explicit checklist, and each new class of defect (the content-assertion
+ban being the first) has to be bolted onto the review template individually.
+
+## Who benefits
+- **The author**, who stops triaging test defects that a structured review should have caught.
+- **Ralph stage runners**, who get an explicit finding checklist instead of inferring one from a
+  writing-conventions skill.
+- **Future skill authors**, who get one place to add a test-review rule rather than editing the
+  review template, the review playbook, and `style-tests` in lockstep.
+
+## Proposed outcome
+A `review-tests` skill — a peer to `review-security` — that specifies what a reviewer checks in
+a test suite: assertion quality (does each assertion prove the behaviour under test),
+mock discipline (boundaries only, never internals), test-data construction (vital data inline,
+fresh per test, no shared mutable fixtures), determinism (no sleeps, no real clocks, every async
+interaction awaited), and coverage gaps against the task's stated behaviours.
+
+Broad scope, narrow use: the skill is generic test-review guidance, invoked as a stage step by
+the ralph review playbook (and available to a human reviewer or a `git-workflow` PR review).
+Once it exists, the content-assertion check added by `agnt-ctx-h9gt` becomes one row inside it
+rather than a standing instruction in the review template.
+
+## Validity check
+- Evidence we already have: the review stage already delegates to skills for every other
+  concern (`review-security` for security, `style-code` for code shape, `style-documentation`
+  for docs) — test review is the gap in an otherwise uniform pattern. The content-assertion
+  ban was bolted onto the review template precisely because no skill owned test review.
+- Riskiest assumption: that a *review* checklist is meaningfully different from `style-tests`
+  read critically. If a reviewer can derive the findings from the existing authoring skill with
+  no loss, this becomes a second statement of the same rules — exactly the two-homes problem
+  `agnt-ctx-h9gt` avoids by keeping `style-tests` canonical.
+- What would invalidate this idea: if `agnt-ctx-h9gt`'s review-gate change turns out to be
+  sufficient — if the review stage, with the content-assertion check in hand, stops missing
+  test defects — then the dedicated skill earns nothing and should be dropped.
+
+## Constraints
+- `style-tests` stays the canonical statement of test conventions; `review-tests` must cite it
+  and add only the reviewer's framing, or the two will drift.
+- Must not duplicate `review-security`'s ground or re-run the test suite (that is the verify
+  stage's job).
+- Invoked from the review playbook, so it must be cheap to load — no expansion of the review
+  stage's token budget beyond one skill read.
+- Follows `agnt-ctx-h9gt`; the content-assertion rule must not be restated in a second place
+  until this skill exists to hold it.
+
+## Next validation step
+After `agnt-ctx-h9gt` has run through the pipeline at least once, collect the test-related
+findings its review stage actually produces across a few PRs. If reviewers keep requesting
+changes on test grounds that the template does not name, that list is the skill's first
+checklist and the idea is confirmed; if the template covers them, drop the idea.
+
+## Notes
+Floated by the author on 2026-10-06 while scoping `agnt-ctx-h9gt`. Stance locked in the
+interview: broad scope (generic test review, not a pipeline-specific gate), used in the ralph
+pipeline, priority P2 with the trigger being `agnt-ctx-h9gt`'s real-world review findings.
+Deliberately kept as an idea rather than folded into `agnt-ctx-h9gt` so it passes the same
+validity check as every other backlog entry.

package/docs/ideas/unify-the-ticket-and-task-decomposition-workflows.md

@@ -0,0 +1,71 @@
+# Idea: Unify the ticket and task decomposition workflows
+
+## Status
+Backlog idea (not implementation-ready)
+
+## Created
+2026-10-13
+
+## Problem
+The planning skills assume a fixed split between tickets and tasks, and implement
+decomposition in three places that do not agree:
+
+- `prd-to-tasks` slices a PRD into epics and task beads, then expands each task through
+  `create-task` into pipeline chore beads for ralph.
+- `spec-to-tickets` slices a spec into a ticket map, drafts bodies, and creates tickets in
+  a tracker (Jira, GitLab, GitHub, or beads).
+- `plan` Phase 2 re-implements the slicing logic inline rather than delegating.
+
+There is no model for a ticket that itself needs breaking into tasks, and no single place
+that owns decomposition. Which skill to use depends on the tracker rather than on the work.
+
+## Who benefits
+The author, and any agent running the planning skills. One decomposition path replaces
+three overlapping ones, and a ticket in any tracker can be created and then broken into
+tasks without switching skills.
+
+## Proposed outcome
+A single coherent model in which a ticket — in any tracker, including beads — can be
+created and then decomposed into tasks, with the tracker acting as an adapter rather than
+defining a separate skill. The exact shape is deliberately undecided; this record captures
+the problem, not a design.
+
+## Validity check
+- Evidence we already have: three implementations of spec-to-units slicing (`plan` Phase 2
+  inline, `prd-to-tasks`, `spec-to-tickets`); `prd-to-tasks` has eight dependents plus a
+  generated agent file; the only substantive difference between the two decomposition
+  skills is the creation contract — `create-task` expands AFK tasks into ralph's chore
+  tree, while `spec-to-tickets` uses a generic tracker adapter.
+- Riskiest assumption: not yet identified — this needs a thinking-through pass. Candidates
+  to test: (a) the ticket/task split can be unified without losing ralph's execution
+  contract; (b) the refactor is affordable given its blast radius; (c) the duplication is
+  causing enough harm to justify it at all.
+- What would invalidate this idea: if ralph's requirements — chore-tree expansion via
+  `create-chores.ts`/`pipeline.json`, epic branches, AFK/HITL classification — cannot be
+  expressed as a tracker adapter behind one slicing skill, then the split is load-bearing
+  and should stay. It would also be invalidated if the duplication never produces concrete
+  drift.
+
+## Constraints
+- Ralph's execution contract is fixed and must keep working: chore expansion, the epic PR
+  flow, and AFK/HITL classification.
+- Open beads `agnt-ctx-s5xd.4` and `agnt-ctx-s5xd.4.4` are already rewriting
+  `prd-to-tasks` and `plan`'s tagging for the `execution:` label model. Any refactor has to
+  land after that epic or it will collide.
+- Skills target ~150 lines, so a unified decomposition skill would need its tracker
+  adapters and formats split into support files.
+
+## Next validation step
+Once the s5xd two-axis epic lands, enumerate exactly what `create-task` and ralph require
+from a decomposition — classification, chore tree, epic hierarchy, labels — and test
+whether each can be expressed as a tracker adapter behind one slicing skill. That is the
+cheapest step that would firm up or kill the idea.
+
+## Notes
+- The open question at the heart of it: are "ticket" and "task" the same thing at different
+  granularities, or genuinely different things? Related: is a ticket a ralph task, or
+  something a ralph task is created from?
+- Priority P3 by the author's call — it blocks other planning work rather than being
+  polish.
+- Filed during the `write-a-ticket` / `spec-to-tickets` work (bead `agnt-ctx-vgzj`), where
+  the overlap first became concrete.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
   ],
   "license": "MIT",
-  "repository": "https://github.com/jaybeeuu/agent-cortex",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jaybeeuu/agent-cortex"
+  },
   "bin": {
     "agent-cortex": "./bin/agent-cortex.mjs"
   },

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.41.1",
+  "version": "1.42.0",
   "author": {
     "name": "jaybeeuu"
   },

package/skills/engineering/grill-with-docs/SKILL.md

@@ -27,7 +27,7 @@ description: "Grilling session that challenges your plan against the existing do
 5. **Cross-reference with code.** When the user states how something works, check whether the code agrees. Surface contradictions the moment you find them.
 6. **Update `CONTEXT.md` inline.** When a term resolves, write the entry right there — do not batch. Keep it a pure glossary: no implementation details, no specs, no scratch notes. Entry format and file-discovery rules live in `REFERENCE.md`.
 7. **Offer ADRs sparingly.** Propose an ADR only when all three hold: hard to reverse, surprising without context, and the result of a real trade-off. If any is missing, skip it. ADR format lives in `REFERENCE.md`.
-8. **Close when shared understanding is reached.** Confirm every design-tree branch is resolved or explicitly deferred, and that the glossary diff captures the session's new language.
+8. **Close when shared understanding is reached.** Confirm every design-tree branch is resolved or explicitly deferred, that the glossary diff captures the session's new language, and — when the session feeds a bead — that there is enough agreed detail to fill every required section of the target bead type (see `bd-tool` → Required sections). Never invent section content; surface assumptions and confirm them.
 
 ## Red Flags
 
@@ -88,4 +88,5 @@ which voids an order before fulfilment. See cancellation.
 - [ ] Terminology conflicts and vague terms called out the moment they appeared
 - [ ] Claims cross-referenced against code; contradictions surfaced
 - [ ] ADRs offered only when all three criteria held (offering none is a valid outcome)
-- [ ] All design-tree branches resolved or explicitly deferred before closing
+- [ ] All design-tree branches resolved or explicitly deferred before closing
+- [ ] When feeding a bead, enough agreed detail to fill every required section; no fabricated answers

package/skills/engineering/improve-codebase-architecture/REFERENCE.md

@@ -43,6 +43,11 @@ Describe the architectural friction:
 - What integration risk exists in the seams between them
 - Why this makes the codebase harder to navigate and maintain
 
+## Acceptance Criteria
+
+- [ ] <verifiable outcome 1>
+- [ ] <verifiable outcome 2>
+
 ## Proposed Interface
 
 The chosen interface design:

package/skills/engineering/improve-codebase-architecture/SKILL.md

@@ -43,7 +43,7 @@ A **deep module** (John Ousterhout, "A Philosophy of Software Design") has a sma
 
 6. **User picks an interface** (or accepts the recommendation).
 
-7. **Create the refactor bead.** Run the `create-task` skill with a concise title, the description from the template in [REFERENCE.md](REFERENCE.md), and priority P2. Always use `create-task` — never `bd create` directly — because it classifies the bead and expands AFK work into pipeline stages ralph can execute. Do not ask the user to review before creating; share the bead ID.
+7. **Create the refactor bead.** Run the `create-task` skill with a concise title, the description from the template in [REFERENCE.md](REFERENCE.md), and priority P2. The template's `## Acceptance Criteria` is required (enforced by `create-task`'s `--validate`) and must reflect outcomes the user agreed, not assumptions. Always use `create-task` — never `bd create` directly — because it classifies the bead and expands AFK work into pipeline stages ralph can execute. Do not ask the user to review before creating; share the bead ID.
 
 ## Red Flags
 
@@ -95,5 +95,6 @@ Output: numbered deepening candidates (cluster, coupling, dependency category, t
 - [ ] At least two radically different designs, each with signature, usage example, hidden complexity, dependency strategy, and trade-offs
 - [ ] Recommendation given in prose, with a hybrid proposed where elements combine well
 - [ ] Refactor bead created via `create-task` at P2 using the REFERENCE.md description template
+- [ ] Description carries agreed `## Acceptance Criteria`; the bead lints clean
 - [ ] Bead ID reported and no review gate imposed before creation
 - [ ] No unrelated areas explored or refactors proposed outside the chosen candidate

package/skills/planning/create-task/SKILL.md

@@ -5,7 +5,7 @@ description: Create a task bead, classify it as AFK or HITL, and if AFK expand i
 
 # Create Task
 
-Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency).
+Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or human-in-the-loop (HITL) execution, and — when AFK — expand it into the standard pipeline: one chore bead per stage plus a HITL PR gate task so a human always reviews the finished branch. Parameters: `title` (required), `description` (required), `priority` (0–3, default 2), `parent` (epic bead ID, optional — sets a `parent-child` dependency). The description must carry the task's required section — `## Acceptance Criteria` — which `--validate` enforces; fill it from agreed answers, not assumptions (see `bd-tool` → Required sections).
 
 ## When to use
 
@@ -21,10 +21,13 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Workflow
 
-1. **Create the parent bead.**
+1. **Create the parent bead.** The description must contain the task's required section —
+   `## Acceptance Criteria` — or `--validate` rejects creation. Fill it from agreed answers, not
+   assumptions (see `bd-tool` → Required sections).
 
    ```bash
-   bd create "<title>" --description "<description>" --priority <priority>
+   bd create "<title>" --description "<description>" --priority <priority> --validate
+   bd lint <new-id>
    ```
 
    If a `parent` epic was provided, record the dependency:
@@ -65,6 +68,7 @@ Turn a piece of work into a tracked bead, classify it for autonomous (AFK) or hu
 
 ## Red Flags
 
+- **Filling acceptance criteria with assumptions.** Fabricated criteria pass `--validate` but mislead the pipeline. The description is the interview's output — confirm it with the human instead.
 - **Running the script from the wrong directory.** Chores land in whatever `.beads` tree `bd` resolves from cwd — the target project's root is the only safe cwd.
 - **Spawning the `classify-bead` subagent when the classifier already resolved the bead.** The deterministic script is the short-circuit; a subagent is only for `escalate: true`.
 - **Skipping the classifier and classifying by hand.** The rubric is a subagent's job; a hand-rolled guess drifts from it.
@@ -101,6 +105,7 @@ The full bead-property contract (titles, labels, dependencies per chore and for
 ## Verification checklist
 
 - [ ] Parent bead exists with the correct title, description, and priority.
+- [ ] Parent bead created with `--validate`, and `bd lint <id>` reports no missing sections.
 - [ ] `parent-child` dependency added when a parent epic was supplied.
 - [ ] `implementation-type` label present on the parent bead (`bd label list <id>`) — resolved by the classifier or, on escalation, the rubric subagent.
 - [ ] HITL path: no pipeline chores created, caller told the classification. AFK path: script ran from the target project's cwd and its JSON contains every stage ID plus `featurePrReview`.

package/skills/planning/create-task/scripts/create-chores.ts

@@ -101,8 +101,11 @@ const prGateBeadId = run([
   'bd', 'create', JSON.stringify(`[${parentId}] PR Review and Merge`),
   '--type', 'task',
   '--description', JSON.stringify(
-    'Human review gate: review and merge the agent PR into the feature branch before closing this feature.',
+    'Human review gate: review and merge the agent PR into the feature branch before closing this feature.\n\n## Acceptance Criteria\n\n- [ ] Agent PR reviewed and merged into the feature branch.',
   ),
+  // The gate is type `task`, so `--validate` enforces its `## Acceptance Criteria`
+  // section. Stage chores require no sections and deliberately omit the flag.
+  '--validate',
   '--priority', priority,
   '--labels', 'implementation-type:hitl,lifecycle:feature-pr',
   '--parent', parentId,

package/skills/planning/prd-to-tasks/REFERENCE.md

@@ -7,7 +7,7 @@ Body templates used in the Phase 3 and Phase 4 workflow steps of `SKILL.md`.
 Passed as the `--description` when creating an epic bead:
 
 ```bash
-bd create "<Phase Title>" --type epic --description "<epic body below>"
+bd create "<Phase Title>" --type epic --description "<epic body below>" --validate
 ```
 
 ```markdown
@@ -23,7 +23,7 @@ A concise description of this phase. Scope and goal, not implementation details.
 
 End-to-end behaviour for this phase. What a demo would show.
 
-## Acceptance criteria
+## Success Criteria
 
 - [ ] Criterion 1
 - [ ] Criterion 2

package/skills/planning/prd-to-tasks/SKILL.md

@@ -50,17 +50,21 @@ execute. The epic bead is the source of truth — no intermediate plan file.
    complete through all integration layers, demoable or verifiable on its own, and
    covering a specific set of user stories.
 5. For each phase define its **title**, **user stories covered**, **what to build**
-   (end-to-end behaviour, not layer-by-layer), and **acceptance criteria**.
+   (end-to-end behaviour, not layer-by-layer), and **success criteria** — the epic's required
+   `## Success Criteria`. The interview is complete only when every phase has agreed criteria;
+   never invent them.
 6. Present the proposed phases and ask about granularity, merges or splits, and which
    phases can run in parallel. Iterate until the user approves.
 
 ### Phase 3 — Create epics (one per phase)
 
 7. Create epics in dependency order (blockers first) so you can reference real bead IDs,
-   using the epic body template in [REFERENCE.md](./REFERENCE.md):
+   using the epic body template in [REFERENCE.md](./REFERENCE.md). The body must carry
+   `## Success Criteria`; `--validate` rejects it otherwise:
 
    ```bash
-   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>"
+   bd create "<Phase Title>" --type epic --description "<epic body from REFERENCE.md>" --validate
+   bd lint <epic-id>
    ```
 
 8. Tag each epic with a priority (`p3` default; adjust for p4/p5), and `workflow:ralph`
@@ -127,7 +131,7 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] Phase 1 complete: PRD confirmed, codebase explored, architectural decisions captured.
 - [ ] Phase 2 complete: phases drafted and approved by the user.
 - [ ] Phase 3 complete: epics created in dependency order and tagged (priority, plus
-      `workflow:ralph` under ralph-plan/ralph).
+      `workflow:ralph` under ralph-plan/ralph), and `bd lint` clean.
 - [ ] Phase 4 complete: tasks created via `create-task`; epics carry the aggregate
       `implementation-type` tag.
 - [ ] Phase 5 complete: full bead tree presented and confirmed.
@@ -137,6 +141,7 @@ Epic: "Phase 2 — Dashboard" (#127) — AFK (blocked by #123)
 - [ ] Every phase is a vertical slice covering all layers, not a horizontal layer.
 - [ ] Every task is independently grabbable by a single agent.
 - [ ] All epics are tagged with a priority (and `workflow:ralph` when under ralph).
+- [ ] Epics created with `--validate`; `bd lint` reports no missing sections for the created tree.
 - [ ] All tasks are classified AFK/HITL via `create-task`.
 - [ ] Parent epics carry the aggregate `implementation-type` tag.
 - [ ] No intermediate plan file was created — epics are the source of truth.

package/skills/planning/request-refactor-plan/FORMAT.md

@@ -10,6 +10,11 @@ The problem that the developer is facing, from the developer's perspective.
 
 The solution to the problem, from the developer's perspective.
 
+## Acceptance Criteria
+
+- [ ] <criterion 1>
+- [ ] <criterion 2>
+
 ## Commits
 
 A long, detailed implementation plan in plain English, broken into the tiniest commits possible. Each commit should leave the codebase in a working state.

package/skills/planning/request-refactor-plan/SKILL.md

@@ -32,7 +32,7 @@ description: Create a detailed refactor plan via user interview, split into tiny
    - **description**: the refactor plan formatted with the template in `FORMAT.md`
    - **priority**: P2
 
-   Always invoke `create-task` — never `bd create` directly. `create-task` classifies the bead and expands AFK tasks into pipeline stage beads for ralph.
+   Always invoke `create-task` — never `bd create` directly. `create-task` classifies the bead and expands AFK tasks into pipeline stage beads for ralph. The description must include the template's `## Acceptance Criteria` — the plan's definition of done, agreed in the interview rather than invented — or `create-task`'s `--validate` gate rejects it.
 
 ## Red Flags
 
@@ -81,4 +81,5 @@ Output: a P2 bead filed via `create-task` whose description follows the `FORMAT.
 - [ ] Test coverage assessed; testing plan recorded when coverage is insufficient.
 - [ ] Commit plan written with every commit leaving the codebase working.
 - [ ] Decision Document contains decisions only — no file paths or code snippets.
-- [ ] Bead filed via `create-task` with concise title, `FORMAT.md`-formatted description, priority P2.
+- [ ] Bead filed via `create-task` with concise title, `FORMAT.md`-formatted description, priority P2.
+- [ ] Description carries agreed `## Acceptance Criteria`; the bead was created with `--validate` and lints clean.

package/skills/planning/spec-to-tickets/REFERENCE.md

@@ -0,0 +1,82 @@
+# Spec to Tickets — Reference
+
+Supporting formats for `spec-to-tickets`. Load this when writing the map, drafting tickets,
+or creating them.
+
+## Ticket map format
+
+Written to `.agent-cortex/tickets/<spec-slug>-map.md` at Phase 3 step 8. `.agent-cortex/*`
+is gitignored, so the map is a local review artefact — not a committed plan file.
+
+```markdown
+# <Spec title> — ticket map
+
+- **Source:** <link or path to the PRD/RFC/spec>
+- **Tracker:** <Jira | GitLab | GitHub | beads>
+- **Status:** draft | agreed | created
+
+## Shared decisions
+
+- <schema/API/auth decision every ticket relies on, with a link>
+
+## Tickets
+
+| # | Title | Intent | Touches | Depends on | Ticket ID |
+|---|---|---|---|---|---|
+| T1 | Add grease sampling to the monitor | Read grease levels alongside oil on each poll | `src/monitor/` | — | — |
+| T2 | Surface grease readings in the dashboard | Show grease next to oil on the status panel | `src/web/` | T1 | — |
+
+## Ordering
+
+T1 -> T2, T3    (T2 and T3 can run in parallel)
+
+## Out of scope
+
+- <work the spec mentions that these tickets deliberately exclude>
+```
+
+Set `Status` to `agreed` at Phase 3, and fill `Ticket ID` as each ticket is created in Phase 6.
+
+## Ticket draft format
+
+Written to `.agent-cortex/tickets/<spec-slug>/<NN>-<ticket-slug>.md` at Phase 4 step 10 —
+one file per ticket, numbered in dependency order. Drafts are the review artefact for
+Phase 5 and the source of the created ticket body.
+
+```markdown
+# <Ticket title>
+
+- **Map ref:** T1
+- **Depends on:** T2, T3
+- **Ticket ID:** — (filled at creation)
+
+---
+
+<body from write-a-ticket>
+```
+
+Fill `Ticket ID` at Phase 6. Upload the body verbatim; record `Depends on` in the tracker's
+own link or dependency field when it has one.
+
+## Tracker adapters
+
+The tracker and mechanism are chosen in Phase 1 step 2. These are illustrative examples,
+not a fixed contract — confirm the real command or tool with the human before creating.
+
+| Tracker | Example creation mechanism |
+|---|---|
+| GitHub | `gh issue create --title "<title>" --body-file <draft-body.md> --label <label>` |
+| GitLab | `glab issue create --title "<title>" --description "<body>"` |
+| Jira | the configured Jira CLI or MCP tool for issue creation |
+| beads | `bd create "<title>" --description "<body>" --validate` |
+
+Keep the approved draft verbatim — do not reformat it for the tracker. After creation,
+copy the returned ID into the map's `Ticket ID` column, the draft's `Ticket ID` field, and
+downstream `Depends on` cells.
+
+## Worked run
+
+Input: an approved RFC with eight numbered requirements and a target GitLab project.
+Output: `.agent-cortex/tickets/checkout-v2-map.md` agreed in chat, eight drafts under
+`.agent-cortex/tickets/checkout-v2/` reviewed as a set, then eight GitLab issues created in
+dependency order with real IDs backfilled into the map and the drafts.