mandrel 1.91.0 → 1.92.0

package/.agents/workflows/helpers/epic-plan-decompose.md

@@ -1,22 +0,0 @@
----
-description: >-
-  Thin pointer — Phase 8 (decompose) of sprint planning now lives entirely in
-  `helpers/plan-epic.md`. This file is kept only so pre-existing links to
-  `helpers/epic-plan-decompose.md` still resolve.
----
-
-# Sprint Plan — Decompose Phase (thin pointer)
-
-> **Superseded.** This file used to carry its own Phase 8 step-by-step
-> procedure — a drifted duplicate of the authoritative one, and a pre-skill
-> pattern. Story #4403 collapsed it: the full, current Phase 8 procedure
-> (context gathering, the
-> [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-> skill activation, the Phase 8.3 consolidation / Phase 8.4 reachability /
-> Phase 8.5 pre-mortem critic passes, the persist call, cross-validation, and
-> cleanup) lives in
-> [`helpers/plan-epic.md` § Phase 8](plan-epic.md#phase-8-work-breakdown-decomposition).
-> Read that section — do not resurrect an inline copy here.
-
-The complementary Phase 7 pointer is
-[`helpers/epic-plan-spec.md`](epic-plan-spec.md).

package/.agents/workflows/helpers/epic-plan-spec.md

@@ -1,22 +0,0 @@
----
-description: >-
-  Thin pointer — Phase 7 (spec) of sprint planning now lives entirely in
-  `helpers/plan-epic.md`. This file is kept only so pre-existing links to
-  `helpers/epic-plan-spec.md` still resolve.
----
-
-# Sprint Plan — Spec Phase (thin pointer)
-
-> **Superseded.** This file used to carry its own Phase 7 step-by-step
-> procedure — a drifted duplicate of the authoritative one, and a pre-skill
-> pattern that instructed inline authoring from the envelope's
-> (now-retired) `systemPrompts` field. Story #4403 collapsed it: the full,
-> current Phase 7 procedure (context gathering, the
-> [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
-> skill activation, the persist call and its folded Tech Spec section gate,
-> review routing, freshness/BDD advisories, and cleanup) lives in
-> [`helpers/plan-epic.md` § Phase 7](plan-epic.md#phase-7-epic-planning-tech-spec--acceptance-spec).
-> Read that section — do not resurrect an inline copy here.
-
-The complementary Phase 8 pointer is
-[`helpers/epic-plan-decompose.md`](epic-plan-decompose.md).

package/.agents/workflows/loops/README.md

@@ -1,65 +0,0 @@
-# Loop units (`.agents/workflows/loops/`)
-
-A **loop unit** is a markdown file that defines one unit of *recurring* work
-with a checkable definition of done. Each file's leading YAML frontmatter
-carries a `loop:` block — a cadence, a goal, an optional `verify` oracle, a
-round cap, and an exhaustion policy — validated against
-[`.agents/schemas/loop-unit.schema.json`](../../schemas/loop-unit.schema.json)
-by `node .agents/scripts/check-loop-units.js` (wired into `npm run lint`).
-
-This directory is the **one** namespaced exception to the flat slash-command
-projection. Files here project to `.claude/commands/loops/<name>.md` and are
-invoked as the namespaced `/loops:<name>` command (flat fallback
-`/loops-<name>` on hosts that flatten subdirectory commands). Every other
-top-level workflow projects flat as `/<name>`; `helpers/` is not projected at
-all.
-
-## What a loop unit is — and is not
-
-A loop unit ships **content and contract**, not a runner. It declares:
-
-- **the action** — what one round does;
-- **the goal** — the standing objective each round works toward;
-- **the `verify` oracle** — the runnable check that proves a round is complete
-  (required for `self-paced` cadence, optional for `interval` / `cron`); and
-- **the observability / escalation contract** — the `maxRounds` backstop, the
-  `onExhaust` policy, and the explicit "stop & escalate" conditions in the body.
-
-It does **not** ship the loop driver. **Cadence and iteration are owned by the
-host** — Claude Code's built-in `/loop` (self-paced or interval) and
-`/schedule` (cron). Mandrel deliberately ships **no** `/goal` or `/loop`
-runner of its own. The full rationale, and why this division exists, is fixed
-in the ADR:
-
-> [`docs/decisions/loop-units-division-of-labor.md`](../../../docs/decisions/loop-units-division-of-labor.md)
-> — *Loop units: mandrel owns content + oracle + contract; the host owns
-> cadence + iteration; no runner shipped.*
-
-Read that ADR before adding a runner, a scheduler, or a `/goal` command to the
-framework — the decision to **not** build one is deliberate.
-
-## Cadence → host mapping
-
-| Cadence       | `verify` | Driven by                         | Starter unit                                                   |
-| ------------- | -------- | --------------------------------- | -------------------------------------------------------------- |
-| `self-paced`  | required | `/loop` (no interval)             | [`fix-failing-tests.md`](fix-failing-tests.md) — red → green   |
-| `interval`    | optional | `/loop <interval>` (e.g. `/loop 5m`) | [`watch-ci.md`](watch-ci.md) — poll a PR's checks          |
-| `cron`        | optional | `/schedule` (cron-driven)         | [`nightly-audit.md`](nightly-audit.md) — nightly audit sweep   |
-
-A `self-paced` unit **must** carry a `verify` oracle because nothing external
-paces it — the oracle is the only signal that tells the host when to stop.
-`interval` and `cron` units are paced by an external scheduler, so a
-terminating oracle is optional; they observe, report, and yield each tick.
-
-## Authoring a new loop unit
-
-1. Create `.agents/workflows/loops/<name>.md` with a `loop:` frontmatter block
-   (`cadence` + `goal` required; add `verify` for `self-paced`).
-2. Give it a `description:` so it shows up in the generated catalog
-   ([`.agents/docs/workflows.md`](../../docs/workflows.md), **Loops namespace**).
-3. Body sections: **Action** (what one round does), **Goal & done-signal** (the
-   objective and the oracle/stop check), **Stop & escalate** (when to hand back
-   rather than loop).
-4. Run `node .agents/scripts/check-loop-units.js` (or `npm run lint`) to
-   validate the frontmatter, then `npm run sync:commands` to project it to
-   `/loops:<name>` and `npm run docs:gen` to refresh the catalog.

package/.agents/workflows/loops/fix-failing-tests.md

@@ -1,74 +0,0 @@
----
-description: >-
-  Self-paced convergence loop that drives a red test suite to green. Each round
-  reads the latest failure, applies the smallest fix, and re-runs the verify
-  oracle (`npm test`); the loop terminates when the oracle exits 0. The host
-  (`/loop`) owns iteration and pacing — mandrel supplies the action, the goal,
-  and the terminating oracle.
-loop:
-  cadence: self-paced
-  goal: >-
-    Drive the project's test suite from red to green by fixing the root cause of
-    each failure, one round at a time, until the verify oracle passes.
-  verify: npm test
-  maxRounds: 10
-  onExhaust: hand-back
----
-
-# /loops:fix-failing-tests — drive a red suite to green
-
-A **self-paced convergence loop**. The host (`/loop` with no interval) decides
-when to run the next round; this unit supplies the action each round performs,
-the standing goal, and the runnable `verify` oracle that tells the host when to
-stop. When `npm test` exits 0, the goal is met and the loop terminates.
-
-> **Scope.** This loop fixes the **root cause** of failing tests. It does not
-> delete, skip, `.only`, or weaken assertions to force a green bar — that is an
-> escalation condition, not a round (see **Stop & escalate** below).
-
-## Action
-
-Each round:
-
-1. **Read the latest failure.** Run the verify oracle (`npm test`) and read the
-   first failing assertion — name, file, and the expected-vs-actual diff. Fix
-   one failure cluster per round; do not fan out across unrelated failures in a
-   single round.
-2. **Diagnose the root cause.** Decide whether the failure is in the production
-   code under test or in the test's own setup/expectation. Prefer the
-   smallest change that makes the assertion honest — fix the code when the test
-   encodes the intended contract; fix the test only when it asserts the wrong
-   thing and you can state why in one sentence.
-3. **Apply the smallest fix.** Make the minimal edit that addresses the
-   diagnosed cause. Avoid speculative refactors — convergence depends on each
-   round changing exactly one thing.
-4. **Re-run the oracle.** Run `npm test` again. A reduced failure count is
-   progress; a new failure introduced by the fix means the diagnosis was wrong
-   — revert and re-diagnose rather than stacking another fix on top.
-
-## Goal & done-signal
-
-- **Goal:** the test suite passes — every test green, no skipped-to-hide
-  failures.
-- **Done-signal (the oracle):** `npm test` exits 0. This is the single
-  terminating check the host `/loop` evaluates after each round. When it
-  passes, stop — the loop is complete.
-- **Backstop:** `maxRounds: 10`. If the oracle is still red after ten rounds,
-  the `onExhaust: hand-back` policy returns control to the caller with a
-  summary rather than looping indefinitely.
-
-## Stop & escalate
-
-Stop the loop and hand back (do **not** keep iterating) when:
-
-- **The same failure survives the same class of fix twice.** Per the
-  anti-thrashing protocol, a repeated fix against an unchanged failure means
-  the diagnosis is wrong — stop and report what you tried.
-- **A fix would weaken the contract.** If the only way to make the bar green is
-  to delete a test, add `.skip` / `.only`, or relax an assertion to match buggy
-  behaviour, that is a product decision, not a loop round. Stop and surface it.
-- **The failure is environmental, not a code defect** (missing service, absent
-  credential, a flaky timing-dependent test). The loop cannot converge on an
-  external cause — report the blocker so the operator can resolve it.
-- **`maxRounds` is reached with the oracle still red.** Hand back a summary of
-  the remaining failures and the rounds spent.

package/.agents/workflows/loops/nightly-audit.md

@@ -1,81 +0,0 @@
----
-description: >-
-  Cron maintenance loop that runs a nightly audit sweep over the repository and
-  files actionable findings. Each run executes the audit workflows and routes
-  the results; the host (`/schedule` or a cron-driven `/loop`) owns the cadence.
-  verify is optional for a cron loop — the scheduler owns iteration, so this
-  unit ships the action and goal, not a terminating oracle.
-loop:
-  cadence: cron
-  goal: >-
-    Keep the repository's standing health surfaced by running the audit sweep on
-    a nightly schedule and turning each fresh finding into an actionable, deduped
-    record so regressions are caught within a day rather than at release time.
-  maxRounds: 30
-  onExhaust: report
----
-
-# /loops:nightly-audit — scheduled maintenance audit sweep
-
-A **cron maintenance loop**. The host (`/schedule`, or a cron-driven `/loop`)
-owns the cadence and fires this unit once per scheduled window — typically
-overnight. Because the scheduler owns iteration, this unit carries **no
-`verify` oracle**: per the loop-unit schema, `verify` is required only for
-`self-paced` cadence and optional for `interval` / `cron`. Each run is a single
-sweep that observes, records, and yields until the next scheduled tick.
-
-## Action
-
-Each scheduled run:
-
-1. **Run the audit sweep.** Execute the relevant audit workflows for the repo
-   (`/audit-security`, `/audit-clean-code`, `/audit-dependencies`,
-   `/audit-quality`, and any others the project relies on). Each audit writes a
-   structured `temp/audits/audit-*-results.md` report — that is the canonical
-   artifact this loop consumes, not free-form prose. Because these audits are
-   **independent** of one another, a scheduled run **may fan them out to
-   parallel sub-agents** (one per audit) rather than walking them serially:
-   dispatch one general-purpose sub-agent per lens, each instructed to read
-   its `/audit-<lens>` workflow and write the structured report. Each
-   sub-agent returns only its structured report; the scheduler/host owns the
-   fan-out just as it owns the cadence, and each per-audit strategy
-   (sequential or orchestrated) is unchanged by running under its own
-   sub-agent. (The former `/deliver` Phase 4 audit-orchestrator pattern this
-   note used to cite was retired by Story #4412, which folded the Epic-close
-   lens walk into the Phase 5 code-review pass.)
-2. **Diff against the prior night.** Compare the fresh findings against the last
-   sweep's reports and against already-open Issues. A finding seen before is
-   not new signal; only genuinely fresh or regressed findings warrant a record.
-3. **Route fresh findings.** Hand the new findings to `/audit-to-stories`, which
-   deduplicates against existing Issues by fingerprint and either chains into
-   `/plan` or opens standalone Stories. Do not open raw duplicate Issues —
-   dedup is the loop's job, not the operator's.
-4. **Report and yield.** Emit a short digest (sweeps run, new findings, Issues
-   opened or updated) and return control to the scheduler, which sleeps until
-   the next cron window.
-
-## Goal & done-signal
-
-- **Goal:** the repository's health regressions are caught and turned into
-  actionable, deduplicated records within a day, without a human remembering to
-  run the audits by hand.
-- **Done-signal:** the nightly sweep completed and every fresh finding has been
-  routed to a record (or explicitly judged a non-finding). A cron loop has no
-  self-evaluated oracle — the scheduler owns whether the loop runs again; this
-  unit simply finishes the night's sweep and yields.
-- **Backstop:** `maxRounds: 30`. Roughly a month of nightly runs;
-  `onExhaust: report` emits a final digest and stops so a long-lived schedule
-  is renewed deliberately rather than running unbounded.
-
-## Stop & escalate
-
-- **An audit cannot run** (a required tool is missing, the audit harness errors,
-  the working tree is dirty in a way that invalidates the sweep). Report the
-  failure for that audit and continue with the others — do not abort the whole
-  night because one audit broke.
-- **A finding is high-severity and time-sensitive** (an exposed secret, a
-  critical CVE reachable in production). Surface it loudly in the digest rather
-  than letting it sit as one row among many — a nightly cadence is too slow for
-  an actively-exploitable finding.
-- **`maxRounds` is reached.** Emit a final digest (`onExhaust: report`) so the
-  operator can renew or retire the schedule deliberately.

package/.agents/workflows/loops/watch-ci.md

@@ -1,68 +0,0 @@
----
-description: >-
-  Interval watch loop that polls a pull request's CI checks until they settle.
-  Each round runs `gh pr checks` and reports the delta; the host (`/loop 5m`)
-  owns the cadence and re-invokes the unit on its schedule. verify is optional
-  for an interval loop — the externally-scheduled host owns iteration, so this
-  unit ships the action and goal, not a terminating oracle.
-loop:
-  cadence: interval
-  goal: >-
-    Keep an eye on the current pull request's required CI checks each interval,
-    surfacing the first failed or stuck check the moment it appears so a human
-    can act before the checks finish.
-  maxRounds: 60
-  onExhaust: report
----
-
-# /loops:watch-ci — poll a PR's checks until they settle
-
-An **interval watch loop**. The host (`/loop <interval> /loops:watch-ci`, e.g.
-`/loop 5m …`) owns the cadence and re-runs this unit on each tick. Because the
-host schedules iteration externally, this unit carries **no `verify` oracle** —
-per the loop-unit schema, `verify` is required only for `self-paced` cadence and
-optional for `interval` / `cron`. The unit's job each round is to observe and
-report, not to converge.
-
-## Action
-
-Each interval:
-
-1. **Read the current check state.** Run `gh pr checks` for the PR under watch
-   (the host supplies the PR number, or it is inferred from the current
-   branch's open PR). Capture the per-check status: pending, passed, or failed.
-2. **Compute the delta since last round.** Compare against the prior round's
-   snapshot. A check that flipped `pending → failed` is the headline; a check
-   that flipped `pending → passed` is progress.
-3. **Surface failures immediately.** On the first failed or cancelled required
-   check, report it — name the check, link the run, and quote the first error
-   line if cheaply available — so a human can act before the rest of the matrix
-   finishes. Do not wait for the whole suite to settle to raise a red check.
-4. **Report and yield.** Emit a one-line status summary
-   (`N passed, M pending, K failed`) and return control to the host, which
-   sleeps until the next interval.
-
-## Goal & done-signal
-
-- **Goal:** the operator learns about a CI failure on the watched PR as early as
-  the polling interval allows, and knows when all required checks have gone
-  green.
-- **Done-signal:** all required checks have a terminal status (every check
-  passed, or at least one has failed). An interval loop has no self-evaluated
-  oracle — the host stops the loop when the operator cancels it, when a failure
-  is surfaced and acted on, or when `maxRounds` is reached.
-- **Backstop:** `maxRounds: 60`. At a 5-minute interval that is ~5 hours of
-  watching; `onExhaust: report` emits a final status and stops rather than
-  polling forever on a wedged check.
-
-## Stop & escalate
-
-- **A required check failed.** Surface it and let the operator decide whether to
-  keep watching the remaining checks or stop. A failed required check is the
-  signal the watch existed to catch.
-- **The PR cannot be resolved** (no open PR for the branch, `gh` not
-  authenticated, the PR was merged or closed out from under the watch). Report
-  the condition and stop — there is nothing left to watch.
-- **`maxRounds` is reached with checks still pending.** Emit a final summary of
-  the stuck checks (`onExhaust: report`) so the operator can investigate the
-  wedged run.