mandrel 1.92.0 → 1.94.0

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -3,8 +3,8 @@ name: epic-plan-spec-author
 description: >-
   Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON
   for an Epic from the planner authoring context emitted by
-  `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when
-  the host LLM needs to write the three artifacts before `epic-plan-spec.js`
+  `plan-context.js --epic <Epic_ID>`. Use during Phase 7 of `/plan` when
+  the host LLM needs to write the three artifacts before `plan-persist.js`
   folds them into the Epic body's managed sections.
 allowed_tools:
   - Read
@@ -32,7 +32,7 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Run only during `/plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
+- Run only during `/plan` Phase 7, after `plan-context.js --epic <Epic_ID>` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
 - Write exactly three artifacts and only inside `temp/epic-<Epic_ID>/`: `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All three MUST exist on disk before returning.
 - **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the Phase 7 persist call rejecting an artifact (e.g. a missing `## Delivery Slicing` heading, a schema-invalid risk verdict) — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/` artifact that fix only what the rejection named; do NOT rewrite an artifact wholesale from a blank draft. `helpers/plan-epic.md` bounds this to **one refinement pass** per invocation (the same shape as the Epic Clarity Gate's own "one refinement pass per invocation" contract) — do not loop.
 - Start each markdown artifact at the correct `##` heading (Tech Spec → `## Delivery Slicing`, Acceptance Spec → `## Acceptance Table` — never the Epic's own `## Acceptance Criteria` heading, which stays the ideation bullets) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
@@ -57,7 +57,7 @@ the Tech Spec to produce the Acceptance Spec).
 
 ## When to use
 
-`/plan` Phase 7, immediately after `epic-plan-spec.js --emit-context`
+`/plan` Phase 7, immediately after `plan-context.js --epic <Epic_ID>`
 writes `temp/epic-<Epic_ID>/planner-context.json`. This Skill replaces the
 inline "Author the Tech Spec" step from the legacy workflow body — the calling
 workflow dispatches this Skill via the `Skill` tool, supplies the Epic ID, and
@@ -72,7 +72,7 @@ The dispatcher passes the Epic ID as the Skill argument. The Skill itself
 reads:
 
 - `temp/epic-<Epic_ID>/planner-context.json` — produced by
-  `node .agents/scripts/epic-plan-spec.js --epic <Epic_ID> --emit-context`.
+  `node .agents/scripts/plan-context.js --epic <Epic_ID>`.
   Fields:
   - `epic.id`, `epic.title`, `epic.body` (or `epic.bodySummary` when the
     planning-context budget downgrades the body to a summary)
@@ -113,10 +113,10 @@ reads:
         Treat each as a likely drift signal: confirm the path exists (it may
         have been dropped by truncation) or mark it net-new explicitly in
         the spec so the post-author freshness gate does not flag it.
-  - `systemPrompts.techSpec` and
-    `systemPrompts.acceptanceSpec` — left in the envelope as a backstop;
-    this Skill's own body below carries the authoritative versions and is
-    the source of truth going forward
+  - `systemPrompts.techSpec` and `systemPrompts.acceptanceSpec` — the
+    **authoritative** rendered system prompts (single-sourced in
+    `lib/templates/spec-author-prompts.js`). Apply them verbatim; the
+    procedure below describes how to use them, it does not restate them.
   - `bddRunner` — BDD runner pending-tag verification result. Shape:
     `{ runner, pendingTag, supported, fallback, reason? }`. When
     `supported: true`, render the verified `pendingTag` in the
@@ -151,7 +151,7 @@ reads:
 
 All three files MUST exist on disk before this Skill returns control. The
 caller will invoke
-`epic-plan-spec.js --epic <Epic_ID> --tech-spec ... --risk-verdict ... --acceptance-table ...`
+`plan-persist.js --epic <Epic_ID> --tech-spec ... --risk-verdict ... --acceptance-table ...`
 next, and the persist half will fail loudly if any file is missing, empty,
 or (for the verdict) schema-invalid.
 
@@ -217,27 +217,13 @@ consolidation and the section the model most often omits when it drafts it last.
 > "Independent?" means, why an unjustified `No` slice is a smell, and how the
 > consolidation pass degrades gracefully when the section is absent).
 
-#### Tech Spec system prompt (authoritative)
-
-```text
-You are an expert Engineering Architect.
-Your job is to convert an Epic into a Technical Specification for implementation.
-
-The Tech Spec should outline:
-1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
-2. Architecture & Design
-3. Data Models (if any)
-4. API Changes (if any)
-5. Core Components
-6. Security & Privacy Considerations
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Open the document with the `## Delivery Slicing` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
-- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional `## Technical Overview` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
-- Format architectural decisions clearly with bullet points.
-- Author the `## Delivery Slicing` section as a markdown table with columns `Slice | What ships | Independent?`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.
-```
+Apply the `systemPrompts.techSpec` string from the emitted envelope verbatim —
+it is the single source (rendered from `lib/templates/spec-author-prompts.js`).
+It fixes the section order (Delivery Slicing first as the Phase 8 ceiling, then
+Architecture, Data Models, API Changes, Core Components, Security), forbids
+`<h1>` and any restatement of Epic Context/Goal/Scope, and mandates the
+`Slice | What ships | Independent?` table with a justification on every
+`Independent? No` row. Do not re-transcribe it here.
 
 ### Step 3 — Author the risk verdict (Risk Assessor persona)
 
@@ -359,35 +345,19 @@ MUST:
     `Runner Verification: Fallback: dependencies-first ordering (reason: <reason>)`.
     Phase 8 still proceeds; AC reconciliation defers to dependency order.
 
-#### Acceptance Spec system prompt (authoritative)
-
-```text
-You are an expert Acceptance Engineer.
-Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
-
-The Acceptance Spec should outline:
-1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
-2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
-3. Disposition — tag each row with one of: new | updated | unchanged
-
-The Epic body's `## Acceptance Criteria` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
-- Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
-- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
-- Each Outcome MUST be a **terse restatement keyed to a specific Epic `## Acceptance Criteria` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
-- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
-- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
-- Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.
-- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy `baseline-refresh` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (`ticket-validator.js` → `validateAcceptanceSubjectPrefix`) will reject the decompose with `code: 'forbidden-subject-prefix'`. Use a Conventional-Commits subject (e.g. `chore(baselines): refresh ...`) and a body trailer (e.g. `baseline-refresh: true` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.
-```
+Apply the `systemPrompts.acceptanceSpec` string from the emitted envelope
+verbatim — it is the single source (rendered from
+`lib/templates/spec-author-prompts.js`). It mandates the
+`AC ID | Outcome | Feature File | Scenario | Disposition` table, stable
+`AC-<n>` IDs that survive re-plans, one Outcome per user-visible behaviour
+anchored to a specific Epic `## Acceptance Criteria` bullet, complete and
+auditable anchor coverage, and Conventional-Commits subjects (no
+`baseline-refresh` subject prefix). Do not re-transcribe it here.
 
 ### Step 5 — Hand back to `/plan`
 
 All three files exist; return. The caller will run
-`node .agents/scripts/epic-plan-spec.js --epic <Epic_ID>
+`node .agents/scripts/plan-persist.js --epic <Epic_ID>
 --tech-spec temp/epic-<Epic_ID>/techspec.md
 --risk-verdict temp/epic-<Epic_ID>/risk-verdict.json
 --acceptance-table temp/epic-<Epic_ID>/acceptance-spec.md`, which validates

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: gates-and-baselines
+description:
+  Governs quality gates and the unified-baseline snapshots. Use when authoring
+  a baseline refresh commit (CRAP, maintainability, dead-exports, lighthouse),
+  when setting up or modifying CI quality gates, or when introducing a new gate
+  that asserts on pre-existing state without turning the integration branch red.
+allowed_tools:
+  - Read
+  - Write
+  - Bash
+---
+
+# Gates and Baselines
+
+## Policy Capsule
+
+- **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
+- **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
+- **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
+- Run the kind-specific update command (`npm run crap:update` / `maintainability:update` / `dead-exports:update` / `lighthouse:update`) on the **Story branch**, not on `main`.
+- Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
+- Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story/Epic that triggered it.
+- Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Epic: #<epic-id>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
+- After the refresh lands, re-run `node .agents/scripts/check-baselines.js` to confirm the gate passes against the new snapshot; if it still fails, a sibling kind drifted — refresh that kind too.
+- Keep credentials in GitHub Secrets (or platform equivalent) even for CI-only test databases; treat the security audit (`npm audit` or equivalent) as gating for critical/high vulnerabilities reachable in production code.
+
+## The Quality Gate Pipeline
+
+Automate quality gates so no change reaches production without passing tests,
+lint, type checking, and build. **Shift left** — a bug caught in linting costs
+minutes; the same bug caught in production costs hours — and prefer many small,
+frequent releases over big-bang merges (a deploy of 3 changes is debuggable, one
+of 30 is not).
+
+```text
+lint → typecheck → unit tests → build → integration → E2E (optional)
+     → security audit → bundle-size
+```
+
+**No gate can be skipped.** If lint fails, fix lint. If a test fails, fix the
+code. When CI fails, feed the specific error back into the agent loop with the
+directive to verify locally before re-pushing.
+
+### Introducing a gate on pre-existing state
+
+A new gate that asserts on latent state (doc-drift, lint-vocabulary,
+dependency-cycle, missing-test-coverage) lands red because of findings nobody
+authored, and every downstream PR is blocked until someone hotfixes the
+integration branch. Before wiring such a gate into `requiredChecks`, land it in
+a shape that is green at merge — **advisory-first** (report-only until the
+backlog is burned down) or by **committing the populated baseline in the same
+change** that turns the gate on.
+
+## Baseline Refresh
+
+The close-validation chain enforces unified baseline snapshots
+(`baselines/crap.json`, `baselines/maintainability.json`,
+`baselines/dead-exports.json`, `baselines/lighthouse.json`). A refresh is **not**
+a regression entry — it tells the ratchet that the new baseline key is
+intentional, so the gate compares future runs against the refreshed snapshot
+rather than the prior one.
+
+**When to refresh:** a file rename/move detached an MI/CRAP key; a method rename
+inside a file produced a phantom new + phantom deleted key (escomplex keys CRAP
+rows on `<file>::<methodName>`); an operator-approved complexity bump or perf
+delta needs to be enshrined as the new floor; a dead-export gate flagged a
+signed-off API-surface change. If the underlying change is an **unintentional**
+regression, do not refresh — remediate first.
+
+### Commit-subject contract (authoritative)
+
+```text
+chore(baselines): refresh <kind> snapshot for <reason>
+
+<non-empty body explaining the refresh — what changed, why the new
+baseline is the correct floor, and any operator sign-off reference>
+
+baseline-refresh: true
+Epic: #<epic-id>
+```
+
+The `commit-msg` hook (`commitlint`) rejects any subject whose leading token is
+not one of `feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert`, and
+`--no-verify` is forbidden by
+[`.agents/rules/git-conventions.md`](../../../rules/git-conventions.md), so the
+subject MUST conform. `release-please` consumes the subject on `main`;
+`chore(baselines):` keeps the refresh out of the user-facing changelog (correct —
+it is internal hygiene) while staying machine-parseable. The
+`baseline-refresh: true` **body trailer** is the canonical machine-readable
+marker (what
+[`.agents/scripts/lib/observability/baseline-refresh-rate.js`](../../../scripts/lib/observability/baseline-refresh-rate.js)
+classifies against) — subject-level leading tokens are not, and must not be, used
+for this purpose.
+
+### Procedure
+
+| Kind            | Update command                   |
+| --------------- | -------------------------------- |
+| CRAP            | `npm run crap:update`            |
+| Maintainability | `npm run maintainability:update` |
+| Dead-exports    | `npm run dead-exports:update`    |
+| Lighthouse      | `npm run lighthouse:update`      |
+
+1. **Run the matching update command** on the Story branch (HEAD must already be
+   the Story branch, not `main`).
+2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
+   possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
+   refresh is contaminated.
+3. **Author the commit.** Stage the baseline file(s) explicitly, then commit with
+   the Conventional-Commits subject + body trailer above:
+
+   ```bash
+   git add baselines/<kind>.json
+   git commit -m "$(cat <<'EOF'
+   chore(baselines): refresh <kind> snapshot for <reason>
+
+   <body: what changed, why the new floor is correct, linking the Story/Epic.>
+
+   baseline-refresh: true
+   Epic: #<epic-id>
+   EOF
+   )"
+   ```
+
+   Do NOT pass `--no-verify`.
+4. **Re-run the gate** — `node .agents/scripts/check-baselines.js`. If it still
+   fails, a sibling kind drifted; repeat from step 1 for that kind.
+
+## Red Flags
+
+- CI failures ignored or silenced; tests disabled in CI to make the pipeline pass.
+- A new required gate merged red on pre-existing findings, blocking every
+  downstream PR.
+- A legacy ad-hoc leading token (`baseline-refresh:`) as the commit subject type.
+- An empty-body refresh — unreviewable, hides the operator decision.
+- A refresh commit whose diff touches unrelated files (contaminated refresh).
+- Refreshing to paper over an unintentional regression.
+- Secrets stored in code or CI config instead of a secrets manager.
+
+## Verification
+
+- [ ] Every quality gate is present (lint, types, tests, build, audit) and
+      failures block merge (branch protection configured).
+- [ ] Any newly introduced gate is green at merge (advisory-first or
+      baseline-in-same-change).
+- [ ] A baseline refresh uses the Conventional-Commits subject + non-empty body
+      + `baseline-refresh: true` trailer, staged explicitly, no `--no-verify`.
+- [ ] `check-baselines.js` passes against the refreshed snapshot.

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -124,17 +124,14 @@ conversation, not a template.
      wouldn't?"
 
    Push beyond what the user initially asked for. Create products people don't
-   know they need yet.
+   know they need yet. Pick the lens that fits the idea — don't run every one
+   mechanically.
 
 **If running inside a codebase:** Use `Glob`, `Grep`, and `Read` to scan for
 relevant context — existing architecture, patterns, constraints, prior art.
 Ground your variations in what actually exists. Reference specific files and
 patterns when relevant.
 
-Read `frameworks.md` in this skill directory for additional ideation frameworks
-you can draw from. Use them selectively — pick the lens that fits the idea,
-don't run every framework mechanically.
-
 #### Phase 2: Evaluate & Converge (Grill)
 
 After the user reacts to Phase 1 (indicates which ideas resonate, pushes back,
@@ -283,9 +280,6 @@ Direct, thoughtful, slightly provocative. You're a sharp thinking partner, not a
 facilitator reading from a script. Channel the energy of "that's interesting,
 but what if..." -- always pushing one step further without being exhausting.
 
-Read `examples.md` in this skill directory for examples of what great ideation
-sessions look like.
-
 ## Red Flags
 
 - Generating 20+ shallow variations instead of 5-8 considered ones

package/.agents/skills/core/qa-coverage-mapping/SKILL.md

@@ -22,7 +22,7 @@ allowed_tools:
 - Read the verdict as a `{unit, contract, acceptance}` object: each tier is `{status: 'present'|'absent', note}`. A surface with only a colocated unit test reports `unit: present` and `contract`/`acceptance`: `absent` with explanatory notes.
 - Route remediation by the absent tiers, honoring the assertion-placement rule: wire-shape and status-code gaps become **contract** tests, user-visible journey gaps become **acceptance** scenarios — never push those into unit tests or `.feature` files incorrectly.
 - Treat `absent` as a coverage gap to surface, not an automatic failure: some surfaces legitimately need only one tier (a pure formatter needs no acceptance scenario). Use the notes to justify, not to mandate, the missing tier.
-- This skill is read + classify only: it does not author tests, mutate tickets, or run the suite. Hand the verdict to `core/test-driven-development` to actually write the missing tier.
+- This skill is read + classify only: it does not author tests, mutate tickets, or run the suite. Hand the verdict to the TDD cycle in `.agents/rules/testing-standards.md` to actually write the missing tier.
 
 ## Role
 
@@ -45,9 +45,9 @@ missing so remediation is aimed correctly.
 - During a test-pyramid audit, to roll up many surfaces into a tier-by-tier
   gap report.
 
-**When NOT to use:** for authoring tests (use
-[`core/test-driven-development`](../test-driven-development/SKILL.md)), for
-measuring line/branch coverage percentages (that is the unit-tier coverage
+**When NOT to use:** for authoring tests (use the TDD cycle in
+[`.agents/rules/testing-standards.md`](../../../rules/testing-standards.md#applying-the-standards)),
+for measuring line/branch coverage percentages (that is the unit-tier coverage
 config, not this skill), or for anything that requires running the suite.
 
 ## The verdict shape
@@ -79,9 +79,9 @@ config, not this skill), or for anything that requires running the suite.
    explicit `tier` field when you already know it.
 3. **Read the gaps.** Every `absent` tier is a candidate gap. Apply judgment
    from the Policy Capsule: not every surface needs all three tiers.
-4. **Route remediation.** For real gaps, hand off to
-   `core/test-driven-development` with the missing tier named, honoring the
-   assertion-placement rule so each assertion lands in its correct tier.
+4. **Route remediation.** For real gaps, hand off to the TDD cycle in
+   `.agents/rules/testing-standards.md` with the missing tier named, honoring
+   the assertion-placement rule so each assertion lands in its correct tier.
 
 ## Example