mandrel 2.6.0 → 2.8.0

package/.agents/rules/changelog-style.md

@@ -5,8 +5,8 @@ This rule governs the shape of per-release entries in the project CHANGELOG
 release entry is authored or edited — most commonly inside Story #N's
 docs sweep before `/deliver` opens the release PR.
 
-The contract is **guidance-tier** in v1: no automated gate fails a close when
-an entry drifts off-template. It still binds every author.
+The contract is **guidance-tier**: no automated gate fails a close when an
+entry drifts off-template. It still binds every author.
 
 ## Goal
 
@@ -129,71 +129,13 @@ release into grouped sub-sections over padding the bullet list. Before
 accepting a long entry, ask: which bullets are user-visible, and which
 are internal detail that migrated in from the Epic body?
 
-## Worked Example — Before/After
+## Worked Example — On-Contract
 
-The "before" reflects the style that drove the Epic #553 retro action item:
-multi-section entries where each bullet leaked internal function names,
-file paths, and implementation mechanics. The "after" applies the contract
-above.
-
-### Before (off-contract, ~48 lines)
-
-```markdown
-## [5.8.7] - 2026-04-15
-
-### Robust story→epic merge at story close
-
-Parallel wave execution kept producing conflicts — Stories branched
-early in a wave landed after peers had merged. `finalizeMerge` now:
-
-1. **Pre-merge rebase in the story worktree** onto
-   `origin/<epicBranch>`, shrinking the conflict surface to the
-   Story's real delta. Failed rebase is aborted and merge still
-   proceeds.
-2. **Conflict triage via `mergeFeatureBranch`** — same threshold-based
-   triage used at integration time (major ≥3 files or ≥20 markers =
-   abort; minor = auto-resolve by accepting Story's version with audit
-   log).
-
-### Per-worktree node_modules collapsed into shared store
-
-Per-worktree `npm install` duplicated dependencies across every story
-tree and blew out disk on parallel waves. `ensure()` now links each
-worktree's `node_modules` to a primed donor tree (junction on Windows)
-and `reap()` removes the link before `git worktree remove`.
-Auto-detected: if the configured strategy is `symlink`, the link
-applies.
-
-### Deliver tail auto-invokes pre-merge gates
-
-`/deliver` auto-invokes the code-review module (Phase 4) and
-the retro runner (Phase 5) inline instead of halting to ask the
-operator to run them separately. `--skip-code-review` available as
-an override.
-
-### Epic Health ticket closed alongside PRD/Tech Spec
-
-Step 8's closure sweep now matches any ticket carrying `type::health`
-or a title starting with `📉 Epic Health:`, in addition to
-`context::prd` / `context::tech-spec`.
-
-### Stale-lock sweep for shared `.git/` dir
-
-`WorktreeManager.sweepStaleLocks({ maxAgeMs = 30_000 })` removes
-well-known lock files (`index.lock`, `HEAD.lock`, `packed-refs.lock`,
-`config.lock`, `shallow.lock`) whose mtime exceeds the threshold.
-Fresh locks belonging to in-flight ops are skipped. Runs at
-`/deliver` start, before worktree GC.
-```
-
-Contract violations: five separate `###` sub-sections where one theme
-would do; internal function names (`finalizeMerge`, `mergeFeatureBranch`,
-`ensure()`, `reap()`, `WorktreeManager.sweepStaleLocks`); implementation
-mechanics (`BFS walker` equivalent, exact argument shapes, internal step
-numbering like "Step 1.4", "Step 8"); lock-file name list leaks
-implementation detail that operators cannot act on.
-
-### After (on-contract, ~18 lines)
+Off-contract entries — the style that drove the Epic #553 retro action item —
+pack several `###` sub-sections into one release and leak internal function
+names (`finalizeMerge`, `mergeFeatureBranch`, `ensure()`, `reap()`),
+implementation mechanics, internal step numbering, and lock-file name lists
+operators cannot act on. The on-contract version collapses all of that:
 
 ```markdown
 ## [5.8.7] - 2026-04-15

package/.agents/rules/ci-remediation.md

@@ -1,127 +1,68 @@
 # CI Failure Triage & Remediation
 
 This rule applies when a delivery path is watching a pull request's CI checks
-and a required check is red (or repeatedly slow) — the `/deliver` router
-([`deliver.md`](../workflows/deliver.md)) runs each Story through the
-single-Story Step 4 CI watch + fix loop
-([`deliver-story.md`](../workflows/helpers/deliver-story.md)), which hands off
-to it. It is the single triage brain that mechanism defers to:
-the watcher (`pr-watch-with-update.js`) surfaces the failing check, the run
-link, and the failure signature; this rule decides what to do next.
-
-The animating principle: **a red check is a defect until proven otherwise, and
-the fix is always to remove the defect — never to hide it.** There is no
-rerun-the-failed-job path and no quarantine path in this rule, by design.
-Reruns and quarantines mask defects; a flaky test that passes on the second
-attempt is still a bug that will fail a future run for a real user or a future
-delivery. Root-cause it or file it — never re-roll the dice.
-
-## The triage decision tree
-
-When a required check goes red, walk this tree top to bottom. Do **not** skip
-to "fix" before you have classified the failure — an unclassified fix is a
-guess.
-
-### 1. Pull the evidence
-
-Fetch the failing job log and record the failure signature (the failing check
-name, the run id / run link, and the first distinctive error line). The
-watcher already writes this to `temp/story-<id>-ci-digest.{json,md}` — start
-from that digest.
-
-### 2. Classify the failure
-
-- **Deterministic (real) failure** — the check fails the same way every time,
-  and the failure is caused by the diff under review (a lint violation, a
-  broken test, a coverage regression, a baseline drift the diff genuinely
-  caused). → Go to [§ Real failures](#real-failures--route-to-the-per-check-fix-table).
-- **Infra / transient failure** — a runner died, a network fetch timed out, a
-  dependency registry 5xx'd, a step hit a platform-conditional path. → Go to
-  [§ Infra, transient, and flaky failures](#infra-transient-and-flaky-failures-are-root-cause-defects).
-- **Flaky failure** — the check fails intermittently: green on one run, red on
-  the next, with **no diff change** between them (order-dependent tests,
-  timing/race assertions, shared-state bleed, wall-clock or timezone
-  assumptions). → Go to
-  [§ Infra, transient, and flaky failures](#infra-transient-and-flaky-failures-are-root-cause-defects).
-
-## Real failures — route to the per-check fix table
-
-A deterministic failure caused by the diff is remediated at source. Use the
-existing per-check fix table — do **not** duplicate it here:
-
-- **Story Step 4**:
-  [`deliver-story-reference.md` § Step 4 — CI watch + fix recovery](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery).
-
-In short: lint/format → `npm run lint` + biome apply; maintainability/crap
-baseline drift → re-run the ratcheted script and fix at source (refresh a
-baseline only when the diff demonstrably can't be covered); test failure →
-reproduce with `npm test`, fix source or test; coverage threshold → add tests.
-Commit the fix on the delivery branch (`story-<storyId>`), push, and re-run the
-watcher. Auto-merge stays armed across retries.
-
-## Infra, transient, and flaky failures ARE root-cause defects
-
-Treat every infra/transient failure **and** every flaky failure as a
-root-cause defect. The remediation sequence is the same for both — you do not
-get to wave it off because "CI was flaky."
-
-1. **Reproduce.** Run the failing check locally (or in a clean environment as
-   close to CI as you can get). Re-run it enough times to observe the
-   intermittency for a flaky failure. If you cannot reproduce it at all after a
-   genuine attempt, that itself is a finding — record it in the issue you file
-   in step 4.
-2. **Check whether it also fails on `main`.** Run the same check against an
-   unmodified `main` checkout. If it fails on `main`
-   too, the defect is **pre-existing** — it is not caused by the diff under
-   review, and the fix belongs in a separate change, not silently folded into
-   this delivery.
-3. **Bisect environment vs. code.** Determine whether the failure is driven by
-   the environment (runner OS, Node version, concurrency, a platform-
-   conditional branch, an external service) or by the code (an
-   order-dependent test, a race, a shared-state assumption). This tells you
-   where the fix has to land.
-4. **Then either fix in-scope OR file the defect.**
-   - **Fix in-scope** when the root cause is within this delivery's footprint
-     and the fix is a cohesive part of the change under review (e.g. a race in
-     a test the diff touches, a timezone assumption in code the Story owns).
-     Commit it on the delivery branch, push, and re-run the watcher.
-   - **File a `meta::framework-gap` issue** when the root cause is outside this
-     delivery's scope — a pre-existing flaky test, a runner/infra weakness, a
-     framework-level environment gap. Open the issue with the
-     `meta::framework-gap` label (see
-     [`git-conventions.md` § `meta::framework-gap`](git-conventions.md)),
-     and include **the run link and the failure signature** (failing check,
-     run id, first distinctive error line) captured in step 1 so a later
-     `/plan` Phase 0 sweep can act on it. Then remediate this delivery only if
-     the pre-existing defect is genuinely blocking it; otherwise proceed once
-     the defect is filed and the check is not caused by your diff.
-
-**There is no shortcut.** You may **not** re-run the failed job to "see if it
-goes green," and you may **not** quarantine, skip, or `.only`/`.skip` a flaky
-test to get a green bar. Both mask the defect and are prohibited by this rule.
-
-## Escalation criteria
-
-Escalate — flip the ticket to `agent::blocked`, post a `friction` comment, and
-hand back to the operator — under **any** of the following. These extend the
-existing three-strikes halt rule; they do not replace it.
-
-- **Three strikes (existing).** Three consecutive remediation iterations on the
-  same failure class without convergence. Stop; the diagnosis is likely wrong
-  (see [`instructions.md` § 1.I Anti-Thrashing](../instructions.md)).
-- **Wall-clock timebox.** Regardless of iteration count, if you have spent more
-  than **30 minutes of active remediation** on a single CI failure without a
-  green bar in sight, stop and escalate. A long grind on one red check is
-  itself a signal that the failure exceeds a single delivery turn's judgment.
-- **Clearly-environmental → escalate immediately (fast path).** When the
-  failure is unambiguously environmental and outside your control — a runner
-  provisioning failure, a persistent registry/network outage, a
-  branch-protection or CI-configuration misconfiguration, an expired
-  credential — do **not** burn iterations trying to code around it. File the
-  `meta::framework-gap` issue (with run link + signature) and escalate on the
-  first encounter. This fast path exists so an operator-side or infra-side
-  problem reaches the operator immediately instead of consuming the turn.
-
-When you escalate, name the failing check, the run link, the failure
-signature, the classification you reached, and what you tried — never fall
-silent.
+and a required check is red (or repeatedly slow). The Story Step 4 CI watch +
+fix loop ([`deliver-story.md`](../workflows/helpers/deliver-story.md)) hands off
+to it: the watcher (`pr-watch-with-update.js`) surfaces the failing check, the
+run link, and the failure signature; this rule decides what to do next.
+
+## Goal
+
+**A red check is a defect until proven otherwise, and the fix is always to
+remove the defect — never to hide it.** A red required check is resolved in
+exactly one of two ways, and no others:
+
+1. **Remove the root cause on the branch.** Pull the failing job log and record
+   the failure signature (failing check, run id / run link, first distinctive
+   error line — the watcher writes this to
+   `temp/story-<id>-ci-digest.{json,md}`). Reproduce the failure, confirm it is
+   caused by the diff under review — **verify the same check against an
+   unmodified `main` checkout**; if it also fails on `main` the defect is
+   pre-existing and belongs in a separate change — then fix it at source,
+   commit on `story-<storyId>`, push, and re-run the watcher. Auto-merge stays
+   armed across retries. Route deterministic per-check failures (lint/format,
+   maintainability/CRAP baseline drift, test failure, coverage threshold)
+   through the fix table in
+   [`deliver-story-reference.md` § Step 4](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery);
+   refresh a baseline only when the diff demonstrably can't be covered.
+2. **File a `meta::framework-gap` issue** when the root cause is outside this
+   delivery's scope — a pre-existing flaky test, a runner/infra weakness, a
+   framework-level environment gap. Open the issue with the `meta::framework-gap`
+   label (see [`git-conventions.md`](git-conventions.md)) carrying **the run
+   link and the failure signature** so a later `/plan` Phase 0 sweep can act on
+   it. Remediate this delivery only if the pre-existing defect is genuinely
+   blocking it.
+
+Infra, transient, and flaky failures are root-cause defects too — a flaky test
+that passes on a rerun is still a bug that will fail a future run. They route
+through the same two options; bisect environment (runner OS, Node version,
+concurrency, a platform-conditional branch, an external service) vs. code (an
+order-dependent test, a race, a shared-state assumption) to decide which.
+
+## Verifier
+
+The check is resolved only when it is **green with zero reruns of the failed
+job**, and the diff carries **no `.skip` / `.only`, no quarantine, and no
+deleted or loosened assertion** introduced to reach green. You may **not**
+re-run a failed job to "see if it goes green," and you may **not** skip,
+`.only`, or quarantine a flaky test to get a green bar. Both mask the defect
+and are prohibited by this rule.
+
+## Escalation
+
+Flip the ticket to `agent::blocked`, post a `friction` comment (naming the
+failing check, the run link, the failure signature, the classification you
+reached, and what you tried — **never fall silent**), and hand back to the
+operator under **any** of:
+
+- **Three strikes.** Three consecutive remediation iterations on the same
+  failure class without convergence — the diagnosis is likely wrong (see
+  [`instructions.md` § 1.I Anti-Thrashing](../instructions.md)).
+- **Wall-clock timebox.** More than **30 minutes** of active remediation on a
+  single CI failure without a green bar in sight.
+- **Clearly-environmental → escalate immediately.** An unambiguously
+  environmental failure outside your control (runner provisioning, a persistent
+  registry/network outage, a branch-protection or CI misconfiguration, an
+  expired credential) — file the `meta::framework-gap` issue (with run link +
+  signature) and escalate on the first encounter rather than burning iterations
+  trying to code around it.

package/.agents/rules/gherkin-standards.md

@@ -29,10 +29,8 @@ scenarios. Use the canonical set below; do not invent ad-hoc tags.
   the tag (the "de-skip" edit). Unlike `@flaky`, `@skip` marks planned
   not-yet-implemented behavior, never a stability problem.
 
-Retired: the `@epic-<id>-ac-N` namespaced AC tag. Its consumer
-(`acceptance-spec-reconciler.js`) was deleted in the v2 Epic removal, so
-the tag is inert — do not apply it to new scenarios. The `mandrel update`
-migration strips surviving instances from consumer feature files.
+Retired: the `@epic-<id>-ac-N` AC tag is inert — do not apply it to new
+scenarios; `mandrel update` strips surviving instances from consumer files.
 
 Rules:
 
@@ -127,30 +125,11 @@ implementation detail.
 
 ## Step Reuse — Grep Before You Write
 
-Before authoring a new step, search the existing step-definition library for
-an equivalent phrase. New steps are a cost: they fragment the vocabulary and
-multiply step-definition maintenance.
-
-Workflow:
-
-1. Identify the verb phrase you want to write (e.g. "the user signs in as").
-2. Grep the step-definition directory for the verb stem:
-
-   ```bash
-   rg -n "signs? in" tests/steps
-   ```
-
-3. If a matching step exists, reuse it verbatim — adjust your scenario
-   phrasing to fit the existing step, not the reverse.
-4. If a near-match exists, extend the existing step (add a parameter, widen
-   the regex) rather than forking a new one. Update every call site in the
-   same PR.
-5. Only when no reasonable match exists, add a new step definition.
-   Co-locate it with related steps and follow the library's naming
-   convention.
-6. Never copy-paste a step implementation to support a paraphrased scenario.
-   Rephrase the scenario instead.
-
-Deprecations: when a step is superseded, mark the old definition deprecated
-in code and migrate all call sites in the same PR. Do not leave two
-near-identical steps live.
+Before authoring a new step, grep the step-definition library for the verb
+stem and **reuse an existing step verbatim** (adjust your scenario to fit it),
+or **extend a near-match** (add a parameter, widen the regex, updating every
+call site in the same PR) — new steps fragment the vocabulary and multiply
+maintenance. Add a new definition only when no reasonable match exists, and
+never copy-paste a step implementation to support a paraphrased scenario.
+When a step is superseded, mark it deprecated and migrate every call site in
+the same PR; do not leave two near-identical steps live.

package/.agents/rules/git-conventions-reference.md

@@ -31,17 +31,6 @@ therefore:
    by side for a release window. If a shape changes, the old shape is
    deleted in the same PR.
 
-The codifying decision is **Epic #2646** (the "Hard-Cutover Cleanup Epic"),
-which deleted the existing compatibility shim layer across
-`config-resolver.js`, `lib/config/*.js`, `lib/baselines/`,
-`wave-session.js`, `IExecutionAdapter` / `ManualDispatchAdapter`, lifecycle
-emit shims, and duplicate progress/comment writers in one pass. The
-per-finding closing references (audit Findings #10, #11, #13, #17) live in
-the merged PRs and the Epic #2646 history; the Part 1 — Model-Evolution
-Audit analysis this section grew out of is preserved at
-`docs/roadmap.md` @ tag `mandrel-v1.94.0` (see the Historical-anchors
-table in the live [`docs/roadmap.md`](../../docs/roadmap.md)).
-
 Practical guidance when authoring a contract change:
 
 - If you are tempted to add a "legacy shape" branch in a parser or
@@ -74,63 +63,41 @@ signature is worth naming:
   (`--no-errors-on-unmatched` or equivalent) before escalating via
   `agent::blocked`.
 
-## Local checkout hygiene — full mechanics
+## Local checkout hygiene — outcome contract
 
 **Invariant (stated in the core): the delivering flow owns tidying the local
 checkout — reaping its own merged refs and fast-forwarding the base branch.
-`/git-cleanup` is a recovery tool, not a routine chore.** The mechanics behind
-that invariant:
-
-Every flow that lands work — `/deliver` and `/git-deliver` — is responsible
-for leaving the local checkout tidy without
-operator intervention:
-
-- **Fast-forwarding the base branch is owned by the flow.** `/deliver`
-  fast-forwards `main` itself in its cleanup phase (via
-  `git-cleanup.js --fast-forward-main --execute --yes`). No workflow ends by
-  telling the operator to "run `/git-cleanup` afterwards to catch up".
-- **Reaping merged local refs is owned by the flow's next boot.** `/plan` and
-  `/git-deliver` open with a **protected boot sweep**
-  (`boot-sweep.js`) that fast-forwards `main`, prunes stale remote-tracking
-  refs, and reaps every local branch whose PR is already merged — skipping any
-  candidate with unpushed work, a dirty worktree, or a still-open parent
-  ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
-  whose PR merges out of band) is therefore reaped automatically at the next
-  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
-  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
-  Story branches; `/plan` and `/git-deliver` widen the scope to their own
-  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
-  `refactor/*`) by passing `--include` explicitly at their boot call site.
-  A branch the planner detects only via the weaker content-equivalence
-  signal (`detectedBy: 'content-merged'`, Story #4395's
-  `git merge-tree --write-tree` probe — content already landed in the base
-  branch by another route, such as a squash-merged Epic PR, with no merged
-  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
-  is report-only, surfaced under `contentMerged` in the result envelope and
-  a routing hint in the summary line (Story #4396), so the operator can
-  send it to `/git-cleanup` for a confirmed, eyeballed reap.
-- **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
-  an unusual state the automated hygiene does not cover — triaging stashes,
-  reaping across non-standard branch namespaces, or `--remote` pruning after a
-  force-push diverged a tip. It is **not** the expected way to keep `main`
-  current or to clear merged branches after a normal delivery; the delivering
-  flows already own that. If you find yourself reaching for `/git-cleanup`
-  after every routine `/deliver` or `/git-deliver` run, that is a signal the
-  owning flow's hygiene step regressed — fix the flow, do not codify the manual
-  sweep.
-
-### Shared-checkout contention (Stories #4460, #4424, #4545)
+`/git-cleanup` is a recovery tool, not a routine chore.** The outcome every
+delivering flow (`/deliver`, `/git-deliver`) guarantees, with the mechanics
+owned by `boot-sweep.js` / `git-cleanup.js`:
+
+- **`main` is fast-forwarded** by the flow itself in its cleanup phase, so the
+  next init seeds from a current base. No workflow ends by telling the operator
+  to run `/git-cleanup` to catch up.
+- **Merged local refs are reaped** at the next workflow boot's protected sweep
+  (`boot-sweep.js`) — every local branch whose PR is already merged, skipping
+  any candidate with unpushed work, a dirty worktree, or a still-open parent
+  ticket. `/plan` and `/git-deliver` widen the sweep's `--include` scope beyond
+  the default `story-*` to their own branch namespaces at their boot call site.
+- **Content-merged branches are report-only.** A branch detected only via the
+  weaker content-equivalence signal (`detectedBy: 'content-merged'` — content
+  already landed in the base by another route, with no merged PR or git
+  ancestry of its own) is **never** reaped by the boot sweep; it is surfaced
+  under `contentMerged` for the operator to send to `/git-cleanup` for a
+  confirmed, eyeballed reap.
+- **`/git-cleanup` is recovery, not routine.** Run it by hand only for a state
+  the automated hygiene does not cover — triaging stashes, reaping across
+  non-standard namespaces, or `--remote` pruning after a force-push. Reaching
+  for it after every routine delivery signals the owning flow's hygiene step
+  regressed — fix the flow, do not codify the manual sweep.
+
+### Shared-checkout contention
 
 **One delivery per checkout is the model.** v2 has no Epic integration branch
 and no merge phase that parks the shared checkout on someone else's branch:
 each Story works in its own worktree (`.worktrees/story-<id>/`) and lands by
-pushing `story-<id>` and opening a PR. The Epic-era collision this section used
-to describe — `story-close.js` running `git checkout <epic-branch>` in the
-shared main checkout under a per-Epic `epic-*.merge.lock` — is gone with the
-machinery that caused it (Story #4545 deleted the last of that prose; the six
-modules it named had already been removed in the v2.0.0 cutover).
-
-Two guards remain, and they cover different hazards:
+pushing `story-<id>` and opening a PR. Two guards remain, and they cover
+different hazards:
 
 - **Per-Story lease** (`lib/orchestration/single-story-lease-guard.js`). The
   standalone path has no Epic-scoped dispatch manifest to serialize two

package/.agents/rules/git-conventions.md

@@ -20,7 +20,7 @@ Every Story lands on a dedicated **Story branch** named `story-<storyId>`
 (e.g., `story-104`), seeded from `project.baseBranch` (`main` by default).
 The runtime owns branch creation via `single-story-init.js`; agents commit
 on that branch only. Close opens a PR against `main` (squash + required
-checks). There is **no** `epic/<id>` integration branch and no `--no-ff`
+checks). There is no `epic/<id>` integration branch and no `--no-ff`
 wave merge.
 
 > **Commit subjects.** Stories have no child tickets. Commits land on

package/.agents/rules/orchestration-error-handling.md

@@ -9,21 +9,11 @@ orchestrators themselves.
 ## Throw, Never Fatal
 
 Orchestration scripts MUST surface unrecoverable failures with
-`throw new Error(<message>)` rather than `Logger.fatal(<message>)`.
-
-### Why
-
-The `runAsCli` boundary catches the throw and maps it to `process.exit(1)`,
-preserving the operator-visible message verbatim while staying robust under
-a mocked `process.exit` (in tests or when the harness stubs it). By contrast,
-`Logger.fatal` falls through silently when `process.exit` is stubbed, which
-lets execution continue past the intended hard-stop and masks failures.
-
-### Precedent
-
-Story #959 converted every `Logger.fatal` call inside the story-close
-orchestrator surface to `throw` and established this rule for future
-orchestration work.
+`throw new Error(<message>)` rather than `Logger.fatal(<message>)`. The
+`runAsCli` boundary catches the throw and maps it to `process.exit(1)`,
+preserving the message verbatim and staying robust under a mocked
+`process.exit`; `Logger.fatal` falls through silently when `process.exit` is
+stubbed, letting execution continue past the intended hard-stop.
 
 ### Where it applies
 

package/.agents/rules/security-baseline.md

@@ -1,13 +1,10 @@
 # Application Security Baseline
 
-Non-negotiable security MUSTs that apply to every piece of code generated. This
-rule is the SSOT for security taxonomy and constraints; the companion skill
+Non-negotiable security MUSTs (the SSOT for security taxonomy and constraints)
+that apply to every piece of code generated; the companion skill
 [`core/security-and-hardening`](../skills/core/security-and-hardening/SKILL.md)
-shows **how** to apply these MUSTs with code patterns, examples, and process
-guidance. Conflicts resolve per the central ordering in
-[`.agents/instructions.md` § 1.K](../instructions.md) — this rule sits above
-the skill, and its security MUSTs are **inviolable**: no persona, skill, or
-local override may relax them. The skill is updated to match.
+shows **how** to apply them. These MUSTs are inviolable per
+[`.agents/instructions.md` § 1.K](../instructions.md).
 
 ## Input Validation
 
@@ -87,11 +84,8 @@ local override may relax them. The skill is updated to match.
 
 ## Forbidden Practices
 
+The MUSTs above are the contract; two rationalizations recur often enough to
+name explicitly (both violate a MUST above):
+
 - Committing secrets to version control.
-- Logging passwords, tokens, or full credit-card numbers.
-- Trusting client-side validation as a security boundary.
 - Disabling security headers for convenience.
-- Using `eval()` or `innerHTML` with user-provided data.
-- Storing auth tokens in client-accessible storage.
-- Exposing stack traces or internal error details to users.
-- Hardcoding fallback secrets ("default" API keys, debug bypasses) in source.

package/.agents/rules/shell-conventions.md

@@ -45,19 +45,10 @@ Other PowerShell-isms agents must respect:
 
 ## Searching the Workspace
 
-When searching for strings, patterns, or files, prioritize speed and avoid
-pipeline bottlenecks or full-file reads. Use this decision tree:
-
-1. **Host grep tool first.** If the harness exposes a dedicated grep tool
-   (e.g. Claude Code's `Grep` tool, ripgrep wrappers), use it. These
-   normalize quoting, respect `.gitignore`, and stream results.
-2. **`git grep`** when the workspace is a git repo and no host tool is
-   available. Pass `-l` to list only filenames when paths are sufficient.
-3. **`rg` (ripgrep)** when installed and outside a git repo, or when you
-   need features `git grep` lacks (multiline, type filters).
-4. **Avoid full-file reads** for searches. Reading whole files into memory
-   to scan for a pattern wastes context and is slower than a streaming
-   grep.
+Prefer, in order: the host's dedicated grep tool (ripgrep-backed — normalizes
+quoting, respects `.gitignore`, streams results), then `git grep` in a git
+repo (`-l` for filenames only), then `rg` outside a git repo or when you need
+multiline / type filters. Do not read whole files to scan for a pattern.
 
 ### PowerShell-specific anti-patterns
 

package/.agents/rules/test-seams.md

@@ -30,8 +30,8 @@ export function ensureSomething(ctx, { fsImpl = fs, spawnImpl = defaultSpawnSync
 
 ### Canonical In-Repo Reference
 
-`baseline-snapshot.js` (`forkMainToEpic` at line 135 / `commitSnapshotsToEpicBranch`
-at line 259) is the established baseline for this pattern in this codebase.
+`.agents/scripts/lib/bootstrap/project-bootstrap.js` (its exported step
+functions) is the established in-repo baseline for this pattern.
 
 ## Rules
 

package/.agents/rules/testing-standards.md

@@ -101,23 +101,13 @@ semantics, including:
 - Header values that carry protocol semantics (`Location`, `ETag`,
   `Retry-After`)
 
-When a reviewer finds one of the above in a `.feature` file, the required
-remediation is to delete it from the scenario and add (or extend) a
-contract test that covers the assertion. The scenario should assert the
-**user-visible outcome** only ("the invoice appears in the outbox"), not
-the wire shape that produced it.
-
-This rule is enforced bidirectionally: the companion prohibition on
-`.feature` authoring lives in
-[`gherkin-standards.md § Forbidden Patterns`](./gherkin-standards.md#forbidden-patterns),
-which forbids raw SQL, HTTP status codes, DOM selectors, URLs, and JSON
-payloads inside scenarios. That list and this section are two sides of the
-same constraint: shape and state belong in contract tests; business
-outcomes belong in acceptance scenarios.
-
-This is the pyramid's load-bearing constraint. It is why the contract
-tier exists as a distinct layer, and why acceptance scenarios stay
-readable, stable, and free of implementation churn.
+When one of the above appears in a `.feature` file, delete it from the
+scenario and add (or extend) a contract test that covers it; the scenario
+asserts the **user-visible outcome** only ("the invoice appears in the
+outbox"). The companion prohibition on `.feature` authoring lives in
+[`gherkin-standards.md § Forbidden Patterns`](./gherkin-standards.md#forbidden-patterns)
+— the two are the same constraint from both sides, and it is the pyramid's
+load-bearing one.
 
 ## Test Structure (Arrange, Act, Assert)
 

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -97,7 +97,9 @@ function metaSourceLabel(source) {
  * ({@link buildContentMarker}) at the Story #4415 cutover, but still
  * probed for so follow-ups filed before the cutover are recognized and
  * not re-filed. An HTML comment so it survives markdown rendering without
- * leaking into the visible body, but stays indexable via `gh search`.
+ * leaking into the visible body; the idempotency probe strips the comment
+ * delimiters before querying `gh search` (the raw `<!-- … -->` form never
+ * matches the index — Story #4657).
  *
  * @param {number} epicId
  * @param {number} index — zero-based finding ordinal within the Epic.
@@ -112,7 +114,10 @@ export function buildIdempotencyMarker(epicId, index) {
  * follow-up bodies. Derived from the finding's `lens|path|summary` triple
  * so the marker is stable across sibling insert/remove/reorder churn in
  * the source `audit-results` comment (Story #4415). An HTML comment so it
- * survives markdown rendering but stays indexable via `gh search`.
+ * survives markdown rendering without leaking into the visible body; the
+ * idempotency probe strips the comment delimiters before querying
+ * `gh search` (the raw `<!-- … -->` form never matches the index —
+ * Story #4657).
  *
  * @param {number} epicId
  * @param {{ lens?: string, path?: string, summary?: string }} finding