mandrel 1.94.0 → 2.1.0

package/.agents/docs/execution-reference.md

@@ -19,12 +19,13 @@ validated.
 
 - **Canonical record + schema validation**: `diagnose-friction.js` appends one
   `kind: friction` record, validated write-time against
-  `signal-event.schema.json`, to the per-Epic/per-Story `signals.ndjson`
-  stream on local disk. The retro roll-up reads that stream back to aggregate
+  `signal-event.schema.json`, to the per-run/per-Story `signals.ndjson`
+  stream on local disk (under `temp/run-<id>/`). The retro roll-up reads that
+  stream back to aggregate
   friction into routed proposals; nothing is posted to the GitHub ticket at
   capture time.
-- **No-Epic context**: Outside an Epic/Story loop there is no per-Epic stream
-  to anchor to, so the record lands on the **standalone signal stream**
+- **Standalone context**: Outside a delivery run there is no `temp/run-<id>/`
+  stream to anchor to, so the record lands on the **standalone signal stream**
   (`temp/standalone/stories/story-<sid>/signals.ndjson`) under the same
   canonical schema.
 - **Never silently dropped**: The signal is never silently dropped — a
@@ -41,8 +42,11 @@ the `AGENT_LOG_LEVEL` environment variable:
 - `silent` — only `fatal` emits; useful for script embedding where the caller
   owns presentation.
 - `info` — default. Emits `info` / `warn` / `error` / `fatal`.
-- `verbose` — adds `debug` trace output on top of the `info` set. `debug` is
-  accepted as a backward-compatible alias.
+- `verbose` — adds `debug` trace output (`Logger.debug`) on top of the `info`
+  set.
+
+Unrecognized `AGENT_LOG_LEVEL` values fall back to `info`. There is no
+`debug` level alias.
 
 This is a diagnostic knob: set it when you need quieter script embedding
 (`silent`) or a deeper trace (`verbose`). The friction-telemetry MUST it sits
@@ -54,24 +58,46 @@ schema mechanics are in [§ Friction telemetry](#friction-telemetry) above.
 
 ## FinOps & token budgeting (economic guardrails)
 
-Mandrel does **not** enforce live LLM spend from response metadata. The
-framework limits **hydrated prompt size** and optional **pre-dispatch
-estimates**; your host runtime (editor / CLI) owns session quota and hard
-stops. Consult this section when reasoning about why a task prompt was elided
-or why `/deliver` refused a fan-out on budget grounds.
-
-### Token budget (hydration + pre-dispatch estimates)
-
-- **`delivery.maxTokenBudget`** (`.agentrc.json`, resolved via
-  `lib/config/limits.js`): caps the task prompt built by
-  `hydrate-context` / `hydrateContext`. The pipeline uses a rough token
-  estimate (≈4 characters per token) and applies section-aware elision
-  (`elideEnvelope`) so oversized envelopes drop or summarize lower-priority
-  sections before you receive the prompt.
-- **`delivery.preflight.*`** (optional): before `/deliver` fan-out,
-  `epic-deliver-preflight.js` compares **estimated** story count, waves,
-  install time, GitHub API volume, and Claude quota tokens against configured
-  ceilings (`maxClaudeQuotaTokens`, etc.). A breach surfaces via
-  `agent::blocked`; there is no per-tool-call metering.
+Mandrel does **not** enforce live LLM spend from response metadata. It bounds
+two things, both **fixed framework constants** rather than operator knobs, and
+both **fail closed**: the assembled `/plan` context envelope, and plan-time
+Story sizing. Your host runtime (editor / CLI) owns session quota and hard
+stops. Consult this section when reasoning about why `/plan` refused an
+over-ceiling envelope or an over-budget Story count.
+
+> **There is no configurable context budget.** `planning.context.maxBytes` /
+> `summaryMode` were removed outright in Story #4541, along with the
+> `applyBudget` pass they fed: that pass lost its last caller in the v2
+> cutover, and it was already bounding a field the envelope builders discarded
+> before shipping the raw seed anyway. The schema now **rejects**
+> `planning.context`, so a config carrying it fails loudly rather than silently
+> capping nothing. The ceiling below is the replacement and the only live bound
+> on planner-context size. Separately, `elideEnvelope` in
+> `lib/orchestration/context-envelope.js` — which this section used to credit
+> with limiting hydrated prompt size — has no production caller either (it is
+> carried in `baselines/dead-exports-production.json`). Only `estimateTokens`
+> from that module is live.
+
+### Planner-context envelope (`/plan`)
+
+- **`PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`** (`lib/orchestration/plan-context.js`):
+  256 KB (≈64K tokens at the ≈4-chars/token estimate) on the serialized
+  envelope `buildPlanContext` assembles, checked at the single choke point
+  every mode returns through. Measured envelopes on this repo land at ~42 KB,
+  so the ceiling is >2× headroom over a worst-case seed plus a medium-tier
+  codebase snapshot.
+- **On refusal**, the error names the envelope's largest fields. Trim the seed,
+  plan fewer `--tickets` source issues in one run, or narrow
+  `planning.codebaseSnapshot`. The seed is carried **verbatim** by design — it
+  is the operator's request, and summarizing it silently would degrade planning
+  quality precisely when the input is richest — so there is no elision path to
+  fall back on. Raising the ceiling needs a measured justification.
+
+### Session-mass capacity (plan-time sizing)
+
+- **`DEFAULT_MODEL_CAPACITY`** (`lib/orchestration/ticket-validator-sizing.js`):
+  absolute authored-token ceilings for plan-time Story sizing (soft 30k /
+  hard 75k). Not operator-configurable via `.agentrc.json`; programmatic
+  override via `opts.modelCapacity` on validateTickets / runPlanPersist only.
 - **Host runtime**: session billing, quota exhaustion, and operator overrides
   are enforced by your provider (e.g. Claude Code), not by Mandrel scripts.

package/.agents/docs/quality-gates.md

@@ -4,8 +4,8 @@ This is the consumer-facing reference for the quality gates the framework
 runs against your repo: the lint baseline ratchet, the maintainability
 ratchet, the CRAP per-method gate, the **absolute quality floors**
 (90/85/90 coverage, MI ≥ 70, CRAP ≤ 20), the anti-thrashing protocol,
-and the concurrent close-safety retry that protects the Epic branch when
-multiple Stories close in quick succession.
+and the concurrent close-safety retry that protects Story-branch pushes
+when multiple Stories close in quick succession.
 
 The floor + ratchet duo is intentional: the ratchet protects against
 regressions on touched files; the floor enforces an absolute threshold
@@ -17,9 +17,8 @@ the lift the floor gate represents.
 
 The configuration knobs that drive these gates live in
 [`.agents/docs/configuration.md`](../docs/configuration.md) under
-`delivery.quality.*` and the framework-internal `DEFAULT_STORY_MERGE_RETRY` constant. This
-file is the runbook side — what the gate does, when it fires, and how to
-bootstrap or refresh it.
+`delivery.quality.*`. This file is the runbook side — what the gate does,
+when it fires, and how to bootstrap or refresh it.
 
 The **baseline envelope, per-kind shapes, component model, writer/reader
 contract, and floor-override path** are documented in the
@@ -36,16 +35,14 @@ it once and reuse the context as you read through any individual gate.
 
 ## Concurrent close safety
 
-`/deliver`'s wave loop may close multiple Stories into the same
-`epic/<epicId>` branch in quick succession. The push step inside `story-close.js` retries
-on a non-fast-forward rejection — fetch, replay the story merge on top of
-the new remote tip, push again — bounded by
-`DEFAULT_STORY_MERGE_RETRY.maxAttempts` (3) and
-`DEFAULT_STORY_MERGE_RETRY.backoffMs` (`[250, 500, 1000]`) from
-`.agents/scripts/lib/config/runners.js`.
-A real
-content conflict (both stories touched the same lines) aborts the loop
-with a clear error and leaves the local tree clean for manual resolution.
+`/deliver` may close multiple Stories from separate Story branches in quick
+succession. Each Story rebases onto the latest `main` in its own base-sync
+phase (`phases/base-sync.js`) before the push, so concurrent closes serialize
+through their own worktrees rather than racing one shared branch. The push
+step itself does not retry: a rejected push fails the close non-zero and the
+operator resolves it, and a real content conflict (both Stories touched the
+same lines) surfaces at base-sync with a clear error, leaving the local tree
+clean for manual resolution.
 
 ---
 
@@ -117,18 +114,14 @@ The same files-out-of-scope list as before, declared in `.c8rc.cjs`:
   whose meaningful logic (label taxonomy + project field defs) lives
   in `lib/label-taxonomy.js` and is unit-tested there. The CLI shell
   itself is integration-only against a live GitHub repo.
-- `.agents/scripts/hydrate-context.js` — thin wrapper around the
-  unit-tested hydration engine; end-to-end coverage requires a real
-  provider tree and Story prompt context, which lives in integration
-  tests.
-- `plan-context.js`, `plan-persist.js`, `epic-plan-healthcheck.js` —
+- `plan-context.js`, `plan-persist.js` —
   `/plan` CLI shells with no unit-test seam; the meaningful
   orchestration logic lives in `lib/orchestration/plan-context.js`,
   `lib/orchestration/plan-persist/*`, and the plan phase modules, and is
   unit-tested there.
 - A larger Story #1702 carve-out of top-level CLI gates, orchestration
   CLIs, git-manipulation CLIs, and `lib/*` glue (e.g. `lint-baseline.js`,
-  `story-close.js`, `dispatcher.js`, `run-tests.js`,
+  `single-story-init.js`, `run-tests.js`,
   `lib/config-schema.js`) — see the `.c8rc.cjs` header comment for the
   per-category rationale and the authoritative entry list.
 
@@ -251,7 +244,7 @@ file. When any threshold under
 the qualitative anti-thrashing cues in
 [`.agents/instructions.md`](../instructions.md) are tripped, the
 friction logger flips the Story to `agent::blocked` and
-posts a structured `friction` comment on the Task so the operator has
+posts a structured `friction` comment on the Story so the operator has
 the trace.
 
 ---
@@ -261,9 +254,8 @@ the trace.
 After a Story's implementation commits land and **before** the Story
 proceeds to close, delivery runs a bounded acceptance self-eval loop
 (Step 1a of
-[`helpers/epic-deliver-story`](../workflows/helpers/epic-deliver-story.md)
-and `helpers/single-story-deliver`; the shared per-round mechanic lives
-in
+[`helpers/deliver-story`](../workflows/helpers/deliver-story.md); the shared
+per-round mechanic lives in
 [`helpers/acceptance-self-eval`](../workflows/helpers/acceptance-self-eval.md),
 with the gate CLI at
 [`.agents/scripts/acceptance-eval.js`](../scripts/acceptance-eval.js)).
@@ -293,8 +285,8 @@ the `delivery.acceptanceEval` field reference.
 > Baseline envelope, axes, and component model: see the
 > [Baseline reference](#baseline-reference) section below.
 
-The lint baseline engine enforces zero-deterioration during Epic
-workflows. Integrations fail if new lint warnings are introduced, and the
+The lint baseline engine enforces zero-deterioration during Story
+delivery. Integrations fail if new lint warnings are introduced, and the
 baseline automatically tightens when the codebase improves.
 
 The canonical baseline file lives at `baselines/lint.json` (override via
@@ -319,7 +311,7 @@ this was removed in a pre-npm-era release; the operator is now the gate.
 A per-file maintainability scoring engine computes composite scores based
 on cyclomatic complexity, file length, and dependency counts. The
 `baselines/maintainability.json` baseline prevents score degradation
-between Epics.
+between Stories.
 
 Refresh with `npm run maintainability:update`.
 
@@ -521,7 +513,7 @@ does not pause automatically on `risk::high`.
 
 The sole runtime HITL pause point is `agent::blocked`: when an agent
 encounters an unresolvable blocker (including unsafe destructive actions
-lacking explicit authorization), it flips the ticket/Epic to
+lacking explicit authorization), it flips the ticket to
 `agent::blocked`, posts friction context, and waits for operator resume
 (`agent::executing`).
 
@@ -759,10 +751,10 @@ Behaviour:
 - The `components` map is optional. When omitted, the default
   `{ "*": ["**"] }` applies and only `*` rows are ever evaluated.
 - The unified `check-baselines.js` reports breaches per component, with
-  `*` always present in the output. The per-component progress signals
-  (`crap-drift.js#detectComponentRegressions`,
-  `maintainability-drift.js#detectComponentRegressions`) name the
-  breached component in their bullet so a `*` rollup is not falsely
+  `*` always present in the output. The shared baselines kernel
+  (`lib/baselines/kernel.js`, via the per-kind rollups in
+  `lib/baselines/kinds/`) groups rows by component and names the
+  breached component in its output so a `*` rollup is not falsely
   implicated when only a component-scoped floor was crossed.
 
 #### Floor axes must match rollup axes

package/.agents/docs/workflows.md

@@ -14,10 +14,10 @@ modules, not runnable commands). The canonical workflow narrative lives in
 compose. This file is only for "which command does X?" lookups.
 
 Every command file lives at `.agents/workflows/<name>.md` and is projected
-into a flat `.claude/commands/` tree by `npm run sync:commands` (the
-UserPromptSubmit hook keeps it current) so it shows up as a bare `/<name>`
-slash command (e.g. `/deliver`). The projection writes only
-`.claude/commands/<name>.md` — there is no plugin manifest and no
+into a flat `.claude/commands/` tree by `npm run sync:commands` (kept
+current at install time and on every `mandrel sync`/`update`) so it shows
+up as a bare `/<name>` slash command (e.g. `/deliver`). The projection
+writes only `.claude/commands/<name>.md` — there is no plugin manifest and no
 marketplace listing. The commands load in every Claude Code environment.
 
 Loop units are the one namespaced exception: files under
@@ -43,19 +43,19 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
 | `/audit-lighthouse` | Run a Lighthouse audit (Performance / Accessibility / Best Practices / SEO) and produce a structured findings report |
 | `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
-| `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`epic-close`, dispatcher, gates); propose remediations. |
+| `/audit-performance` | Audit hot paths, algorithmic complexity, and I/O bottlenecks in the tooling surface (`single-story-close`, dispatcher, gates); propose remediations. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
 | `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
 | `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report. |
 | `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
-| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --idea or opens standalone Stories. |
+| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, composes a sequential segment plan over any mix of Epics and standalone Stories, then delegates each segment to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
+| `/deliver` | Unified delivery entry point. Takes a list of Story ids, resolves their dependency graph from live state, and delivers each via the single deliver-story engine — story-<id> → PR → main. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
 | `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
-| `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the 3-step Epic path (interrogate → author → persist) or the standalone-Story authoring path — and absorbs every planning flag. |
+| `/plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default (folded Tech Spec in the Story body); splits into N>1 only under the default-single split policy. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |