mandrel 2.9.0 → 2.11.0

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

@@ -1,99 +1,63 @@
 # Git & Version Control Conventions
 
-This rule applies globally to all repository changes to maintain a clean git
-history. It is the **always-on core**: branch shapes, the Conventional-Commit
-subject contract, issue references, and the non-negotiable push/hygiene MUSTs.
-
-Deeper mechanics — the hard-cutover contract policy, the push-hook
-false-negative signature, shared-checkout merge contention, the
-documentation-freshness gate, and the `meta::*` retrospective-routing labels —
-live in the on-demand
-[`git-conventions-reference.md`](git-conventions-reference.md). Read that file
-**before** doing the matching work; the core below is sufficient for every
-routine commit, branch, and PR.
+This rule applies globally to all repository changes. It is the **always-on
+core**: branch shapes, the Conventional-Commit subject contract, issue
+references, and the non-negotiable push/hygiene MUSTs. Deeper mechanics —
+the hard-cutover contract policy, the full push-validation procedure and
+the push-hook false-negative signature, checkout-hygiene scope rules,
+shared-checkout merge contention, the documentation-freshness gate, and
+the `meta::*` labels — live in the on-demand
+[`git-conventions-reference.md`](git-conventions-reference.md); read it
+**before** doing the matching work.
 
 ## Canonical Branching (v2)
 
-### Story branch → PR → main
-
-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`
-wave merge.
-
-> **Commit subjects.** Stories have no child tickets. Commits land on
-> `story-<storyId>` directly from the agent and the Conventional Commit
-> subject references the Story via `(refs #<storyId>)`. See
-> [`.agents/instructions.md` § 5.D](../instructions.md) for the hierarchy
-> contract.
+Every Story lands on a dedicated **Story branch** named
+`story-<storyId>`, 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). No `epic/<id>` integration branch, no `--no-ff` wave
+merge, no child tickets: commits land on `story-<storyId>` directly, the
+subject referencing the Story via `(refs #<storyId>)` — see
+[`.agents/instructions.md` § 5.D](../instructions.md).
 
 ## Conventional Commits
 
-- MUST adhere to Conventional Commits format:
-  `<type>(<optional scope>): <description>`
-- Types allowed: `feat:`, `fix:`, `perf:`, `refactor:`, `revert:`, `docs:`,
-  `style:`, `chore:`, `test:`, `build:`, `ci:`. This list mirrors the
-  `changelog-sections` in `release-please-config.json`; keep the two in
-  sync when adding a type.
-- Description must be in the imperative mood (e.g., "add feature", not
-  "adds" or "added").
-- **Local enforcement**: the `commit-msg` Husky hook runs `commitlint`
-  against every local commit (`.husky/commit-msg` →
-  `commitlint --edit "$1"`, config in `commitlint.config.js`). A
-  non-conventional subject fails the hook and no commit is created. Do not
-  bypass with `--no-verify`. The hook does **not** run on squash-merge
-  titles edited in the GitHub UI; author the PR title in conventional form
-  so the squash commit on `main` parses cleanly for release-please.
-
-## Push Validation & Reliability
-
-To prevent "silent" push failures (e.g., hidden by multi-command chains or
-rejected by `pre-push` hooks):
-
-1.  **Local Validation**: Run the project's configured validation commands
-    (`agentSettings.commands.validate` and `agentSettings.commands.test` in
-    `.agentrc.json`, or the equivalent format-check command) locally
-    _before_ attempting a `git push`.
-2.  **Verify Push Output**: Do NOT assume a push succeeded unless the output
-    explicitly confirms the remote ref was updated (`[new branch]`,
-    `[up to date]`, or `... -> ...`).
-3.  **Handle Rejections**: If a push is rejected by a `pre-push` hook, fix
-    the underlying issue (usually formatting or linting) and create a NEW
-    follow-up commit. Do **not** amend the rejected commit — amending makes
-    diffs harder to review and can lose work if the original commit
-    contained more than the linting fix.
-4.  **Never bypass hooks**: Do not use `--no-verify`, `--no-gpg-sign`, or
-    other hook-skipping flags unless the operator explicitly authorizes it.
-    If a hook fails, investigate the underlying cause. One recognized
-    exception — a Biome _zero-match_ failure under a harness-managed
-    worktree path the consumer's lint config ignores — is a consumer-tooling
-    gap, **not** authorization to skip the hook; its recognition signature
-    and sanctioned fix live in
-    [`git-conventions-reference.md` § Push Validation](git-conventions-reference.md).
+- MUST follow `<type>(<optional scope>): <description>`, imperative
+  mood.
+- Types: `feat:`, `fix:`, `perf:`, `refactor:`, `revert:`, `docs:`,
+  `style:`, `chore:`, `test:`, `build:`, `ci:` — mirrors
+  `changelog-sections` in `release-please-config.json`; keep in sync.
+- The `commit-msg` Husky hook runs `commitlint` on every local commit.
+  It does **not** run on squash-merge titles edited in the GitHub UI —
+  author the PR title in conventional form so the squash commit parses
+  for release-please.
+
+## Push Validation & Reliability (MUSTs)
+
+1. Run the configured validation commands locally **before** `git push`.
+2. Do NOT assume a push succeeded unless the output confirms the remote
+   ref was updated (`[new branch]`, `[up to date]`, `... -> ...`).
+3. If a `pre-push` hook rejects, fix the cause and create a NEW follow-up
+   commit — never amend the rejected commit.
+4. **Never bypass hooks** (`--no-verify`, `--no-gpg-sign`, …) without
+   explicit operator authorization. The one recognized exception — a
+   Biome zero-match failure under a harness-managed worktree path — is a
+   consumer-tooling gap, **not** authorization; see
+   [`git-conventions-reference.md` § Push Validation](git-conventions-reference.md).
 
 ## Local checkout hygiene
 
-**Invariant: 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.**
-
-Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
-`/git-deliver` — leaves the local checkout tidy without operator
-intervention: it fast-forwards the base branch itself, and reaps its own
-merged local refs on the next workflow boot (the `boot-sweep.js` protected
-sweep). Do **not** end a workflow by telling the operator to run
-`/git-cleanup` to catch up; `/git-cleanup` is for recovering an unusual state
-the automated hygiene does not cover. The boot-sweep scope rules, the
-content-merged report-only case, and the shared-checkout merge-contention
-guard are detailed in
+**The delivering flow owns tidying the local checkout** — it
+fast-forwards the base branch itself and reaps its own merged refs on
+the next workflow boot (the `boot-sweep.js` protected sweep).
+`/git-cleanup` is a recovery tool, not a routine chore — never end a
+workflow by telling the operator to run it. Scope rules and the
+shared-checkout contention guard:
 [`git-conventions-reference.md` § Local checkout hygiene](git-conventions-reference.md).
 
 ## Pull Requests
 
 - Never commit `.env` or hardcoded secrets.
-- Always include a short description of _why_ the change was made in the PR
-  body.
-- **Reference Issues**: Use "Resolves #109" or "Closes #114" to link
-  tickets.
+- Always include a short description of _why_ the change was made.
+- Reference issues: "Resolves #109" / "Closes #114".

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

@@ -23,3 +23,31 @@ stubbed, letting execution continue past the intended hard-stop.
 Non-orchestration scripts (one-shot utilities, audit reporters, doc
 generators) may continue to use `Logger.fatal` where the lifetime guarantees
 are simpler.
+
+## Output Contract — compact digest + artifact path (Story #4708)
+
+An orchestration script's stdout rides resident in the invoking agent's
+transcript and is re-read as prompt-cache input on every later turn, so fat
+success output is a per-turn tax on the whole session — not a one-time cost.
+
+- **Budget.** A script's **default success-path stdout MUST stay under
+  ~2KB**. Error paths and opt-in verbose modes are exempt; the budget is
+  about what every routine invocation pays.
+- **Digest + artifact path.** When a script produces a large result (a full
+  envelope, a per-phase result object, a report), it MUST write the full
+  payload to an on-disk artifact (under `temp/`, or an operator-named
+  `--out` path) and emit a **compact machine-parseable digest** on stdout
+  that names the artifact path plus the handful of fields the caller acts
+  on. The shared helper
+  [`lib/observability/terse-result.js`](../scripts/lib/observability/terse-result.js)
+  (`emitTerseResult`, Story #4685) implements this for hot-path result
+  dumps; `plan-context.js --out` shows the envelope-capture variant.
+- **Compact JSON.** Machine-parsed stdout envelopes are `JSON.parse`d by
+  their drivers — emit them single-line (`JSON.stringify(x)`), never
+  pretty-printed (`null, 2` only adds resident bytes). Pretty output is
+  reserved for explicit opt-in flags (`--pretty`).
+- **Escape hatch.** `MANDREL_RESULT_DETAIL=inline` restores inline full
+  detail for interactive debugging; scripts using `emitTerseResult` honor it
+  automatically.
+- **stdout purity is unchanged.** Scripts whose stdout is a machine contract
+  (Story #2278) keep logs on stderr; the digest is the *only* stdout line.

package/.agents/schemas/agentrc.schema.json

@@ -329,21 +329,16 @@
         },
         "complexityGate": {
           "type": "object",
-          "description": "Plan-time ceremony-lite complexity gate. Routes trivial single-artifact seeds onto a collapsed plan/deliver path; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
+          "description": "Shape-derived ceremony-lite complexity routing. A lite claim is validated against the authored Story shape at persist and re-derived from the Story body at dispatch; conservative (full on any doubt). Never relaxes the Story-ticket / PR-to-main / repo-gates / security-baseline non-negotiables.",
           "properties": {
             "enabled": {
               "type": "boolean",
-              "description": "Master switch. When false, every seed takes the full plan/deliver ceremony. Default true."
-            },
-            "maxSeedWords": {
-              "type": "integer",
-              "minimum": 0,
-              "description": "Seed prose word ceiling for the lite path. A seed above this many words is not trivial and takes the full path. Default 60."
+              "description": "Master switch. When false, lite routing is disabled everywhere: persist refuses lite claims and dispatch always takes the sub-agent path. Default true."
             },
             "maxArtifacts": {
               "type": "integer",
               "minimum": 0,
-              "description": "Enumerated-artifact ceiling for the lite path. A seed enumerating more than this many candidate artifacts is multi-capability and takes the full path. Default 1."
+              "description": "Enumerated-artifact threshold reported by the plan-context complexity signals. An input signal for the planner verdict — carries no routing authority. Default 1."
             }
           },
           "additionalProperties": false
@@ -844,6 +839,16 @@
           "$ref": "#/$defs/listOrExtenderOfStrings",
           "description": "Directories whose JS sources the maintainability gate scores. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/` plus `tests/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal."
         },
+        "refreshTag": {
+          "allOf": [
+            {
+              "$ref": "#/$defs/safeString"
+            },
+            {
+              "minLength": 1
+            }
+          ]
+        },
         "refreshTimeoutMs": {
           "type": "integer",
           "minimum": 1,
@@ -1171,8 +1176,14 @@
     },
     "mergeWatch": {
       "type": "object",
-      "description": "Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR.",
+      "description": "Knobs consumed by the close-and-land merge wait (Story #4543; defaults in `lib/orchestration/merge-poll.js`). `mode` (Story #4698) selects the close-time merge posture. `intervalSeconds` is the poll cadence between `gh pr view` probes after the arm. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. `updateAttempts` caps the bounded update of a behind-the-base PR.",
       "properties": {
+        "mode": {
+          "type": "string",
+          "enum": ["sync", "async"],
+          "default": "sync",
+          "description": "Close-time merge-wait posture (Story #4698). `sync` (default) keeps the in-close foreground merge wait unchanged. `async` caps the per-invocation wait to a short ~60s probe window — long enough to catch an instant merge and, via the head-anchored required-check predicate, an instantly-red required check — then returns the resumable `pending` terminal (exit 3) with a `nextCommand`. Opt in when slow CI makes the foreground wait routinely expire: the worker launches `nextCommand` in the background instead of burning the host tool slot polling. `maxBudgetSeconds` (the cumulative give-up) is unchanged."
+        },
         "intervalSeconds": {
           "type": "integer",
           "minimum": 1,
@@ -1200,6 +1211,19 @@
       },
       "additionalProperties": false
     },
+    "review": {
+      "type": "object",
+      "description": "Close-scope review tuning (Story #4699). Governs the Story-scope local-lens pass that runs inside the close subprocess; the maker-blind code-review pass and all hard gates are unaffected.",
+      "properties": {
+        "lensDiffFloor": {
+          "type": "integer",
+          "minimum": 0,
+          "default": 40,
+          "description": "Changed-line floor for the close-scope lens walk (Story #4699). A diff strictly below this many changed lines (additions + deletions) with zero sensitive-path hits skips lens materialization and records the skip in the findings-yield ledger. Default 40; 0 disables the skip."
+        }
+      },
+      "additionalProperties": false
+    },
     "quality": {
       "type": "object",
       "properties": {
@@ -1312,6 +1336,9 @@
         "codeReview": {
           "$ref": "#/$defs/codeReview"
         },
+        "review": {
+          "$ref": "#/$defs/review"
+        },
         "refactorStage": {
           "$ref": "#/$defs/refactorStage"
         },

package/.agents/schemas/validation-evidence.schema.json

@@ -36,10 +36,12 @@
               "lint",
               "test",
               "format",
+              "coverage-capture",
+              "check-baselines",
               "check-maintainability",
               "check-crap"
             ],
-            "description": "Stable gate identifier. Closed enum — additions require a schema bump."
+            "description": "Stable gate identifier. Closed enum — additions require a schema bump. Must be a superset of every gate name buildDefaultGates() can emit (lib/close-validation/gates.js); tests/close-validation-gates-enum.test.js pins that gate-list ⊆ enum invariant. `coverage-capture` and `check-baselines` are the real close-validation gates (Story #4697); `check-maintainability` / `check-crap` are the retired per-kind gates (Story #2210) kept so historical evidence records still validate."
           },
           "commitSha": {
             "type": "string",

package/.agents/scripts/acceptance-eval.js

@@ -3,12 +3,16 @@
 /**
  * acceptance-eval.js — bounded per-Story acceptance self-eval gate (Story #3819).
  *
- * The Story-implementation phase runs an independent (fresh-context)
- * critic pass that scores the caller-injected change set against each
- * inline `acceptance[]` item, emitting one verdict file per round
+ * The Story-implementation phase runs ONE verdict-owner per acceptance
+ * cluster (Story #4723) — the fresh-context critic when
+ * `ceremony-routing.js` sensitivity-routes the cluster fresh, the
+ * contract-identical inline self-eval otherwise — which scores the
+ * caller-injected change set against each inline `acceptance[]` item and
+ * emits one verdict file per round
  * (`.agents/schemas/acceptance-eval-verdict.schema.json`). This CLI is the
- * deterministic substrate that turns that verdict into the loop's next
- * action:
+ * deterministic SCORER of that single authored verdict — it validates and
+ * decides, it never re-scores the criteria as an independent additional
+ * pass — turning the verdict into the loop's next action:
  *
  *   1. Validate the verdict file against the verdict JSON Schema (a
  *      malformed verdict is a hard error — the loop refuses to guess).
@@ -283,7 +287,7 @@ export async function main(argv = process.argv.slice(2)) {
     emitSignal,
   });
 
-  Logger.info(JSON.stringify(envelope, null, 2));
+  Logger.info(JSON.stringify(envelope));
 
   if (exitCode !== 0) {
     const names = envelope.unmetCriteria

package/.agents/scripts/apply-quality-bootstrap.js

@@ -69,7 +69,7 @@ async function main() {
   // Mirror the retired heredoc's output: pretty-printed `{ quality, baselines }`
   // to stdout. Use process.stdout.write (not console.log) per the no-console
   // enforcement boundary.
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.stdout.write(`${JSON.stringify(result)}\n`);
   return 0;
 }