mandrel 2.8.0 → 2.10.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

@@ -327,6 +327,27 @@
         "codebaseSnapshot": {
           "$ref": "#/$defs/codebaseSnapshot"
         },
+        "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.",
+          "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 150."
+            },
+            "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."
+            }
+          },
+          "additionalProperties": false
+        },
         "failOnSharedEditors": {
           "type": "boolean",
           "description": "When true, upgrade shared-editor conflict findings to hard errors (default false — advisory soft findings only)."
@@ -1150,8 +1171,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,
@@ -1179,6 +1206,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": {
@@ -1291,6 +1331,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

@@ -283,7 +283,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;
 }
 

package/.agents/scripts/audit-to-stories.js

@@ -31,6 +31,7 @@ import fs from 'node:fs';
 import { glob } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
+import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import { buildStoryBody } from './lib/audit-to-stories/build-story-body.js';
 import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-against-github.js';
@@ -85,12 +86,30 @@ function tallyBySeverity(findings) {
   return t;
 }
 
+/**
+ * Test-only seam: when `AUDIT_TO_STORIES_PROVIDER_FIXTURE` names a module, load
+ * its default export as the dedup provider (ports) instead of the live GitHub
+ * provider. This lets the soft-fail contract be exercised end-to-end through
+ * the real `--scan` CLI with a search port that fails for a subset of groups
+ * (Story #4678, AC-8), with no network. Returns null when the env var is unset.
+ *
+ * @returns {Promise<object|null>}
+ */
+async function loadFixtureProvider() {
+  const fixturePath = process.env.AUDIT_TO_STORIES_PROVIDER_FIXTURE;
+  if (!fixturePath) return null;
+  const mod = await import(pathToFileURL(fixturePath).href);
+  return mod.default ?? null;
+}
+
 async function loadProvider({ createProviderImpl, resolveConfigImpl } = {}) {
   // The provider is optional — when missing, the dedupe step emits a
   // create-only classification and the workflow operator is informed. The
   // `createProviderImpl` / `resolveConfigImpl` seams let a contract test drive
   // this exact adapter (fingerprint + semantic-candidate ports) with an
   // in-memory issue store instead of the live GitHub provider.
+  const fixture = await loadFixtureProvider();
+  if (fixture) return fixture;
   try {
     const resolveConfig =
       resolveConfigImpl ??
@@ -180,6 +199,31 @@ function dedupSkippedWarning(reason) {
   );
 }
 
+/**
+ * Render the loud, operator-visible warning emitted when Phase 6 dedup ran but
+ * one or more groups' lookups could not complete (an HTTP 422, or a rate limit
+ * still exhausted after the endpoint budget's cooldown). Those groups degrade
+ * to `create` rather than aborting the whole scan (Story #4678); this warning
+ * names each affected group so the operator knows exactly which to check by
+ * hand. Mirrors the `dedupSkippedWarning` shape so a partially-checked plan
+ * reads as clearly as a wholly-unchecked one.
+ *
+ * Pure: returns the message string so `buildPlan` owns the single `Logger.warn`
+ * write site (stderr) and the text stays unit-testable.
+ *
+ * @param {Array<{ group: string, reason: string }>} entries
+ * @returns {string}
+ */
+function dedupDegradedWarning(entries) {
+  const lines = (entries ?? []).map((e) => `  - ${e.group}: ${e.reason}`);
+  return (
+    `dedup degraded for ${lines.length} group(s): their GitHub lookup could ` +
+    'not complete, so they are classified "create" WITHOUT a dedup check. A ' +
+    'run that creates Stories from this plan may open duplicates of these ' +
+    `groups — verify each by hand before opening:\n${lines.join('\n')}`
+  );
+}
+
 async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
   const reportPaths = await collectReportPaths(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
@@ -227,6 +271,12 @@ async function buildPlan({ glob: pattern, severity, useProvider, ledger }) {
       classifications = result.classifications;
       summary = result.summary;
       dedupApplied = true;
+      // A partially-checked plan is a useful result — warn loudly (stderr, so
+      // the --scan JSON on stdout stays clean) naming the groups that degraded
+      // to create because their lookup could not complete (Story #4678).
+      if (summary.dedupDegraded?.count > 0) {
+        Logger.warn(dedupDegradedWarning(summary.dedupDegraded.groups));
+      }
     } else {
       // The provider could not resolve a searchIssues port — the dedup gate
       // is silently a no-op without this. Surface it loudly (stderr, so the
@@ -488,6 +538,7 @@ export const __testing = {
   buildPlan,
   loadProvider,
   dedupSkippedWarning,
+  dedupDegradedWarning,
   buildAndGateStories,
   runAuto,
   resolveSeverityFloor,