mandrel 1.57.0

package/.agents/workflows/git-push.md

@@ -0,0 +1,60 @@
+---
+description: Commit all outstanding changes then push to the remote repository.
+---
+
+# /git-push [Message] [--no-push]
+
+This workflow is the single source of truth for "stage + commit [+ push]"
+ergonomics. It accepts an optional `[Message]` and an optional `--no-push` flag.
+
+- **Default mode** — stage all outstanding changes, commit, then push the
+  current branch to its upstream remote.
+- **`--no-push` mode** — stage and commit only. Useful when you want to chain
+  several commits or defer the push. `/git-commit-all` is a compatibility alias
+  that maps to this mode.
+
+## Steps
+
+1. **Stage Changes**: Stage all new, modified, and deleted files.
+
+   ```powershell
+   git add .
+   ```
+
+2. **Commit Changes**: Commit the staged changes. If no message is provided, a
+   generic timestamped message will be used.
+
+   ```powershell
+   git commit -m "[Message]"
+   ```
+
+3. **Push to Remote** _(skip when `--no-push` is set)_: Push the current branch
+   to the upstream repository.
+
+   ```powershell
+   git push
+   ```
+
+## Troubleshooting
+
+- **Hook Failures**: If `git commit` or `git push` fails due to Husky/pre-commit
+  hooks (e.g., linting, formatting, or test failures), you MUST analyze the
+  error output, fix the issues in the codebase, and then re-run the failed
+  command.
+- **Upstream Conflicts**: If the push is rejected because the remote contains
+  work that you do not have locally, pull the latest changes first
+  (`git pull --rebase`) and resolve any conflicts before pushing again.
+
+## Constraint
+
+Never use `--no-verify` to bypass quality gates. If a hook fails, identify and
+fix the root cause (e.g., run `npm run format` or fix lint errors) before
+attempting to commit or push again.
+
+## ⚠️ Parallel Story Execution
+
+Do **not** use this workflow from inside a parallel story-execution context
+(`/story-deliver #<storyId>`). `git add .` sweeps any untracked files in the
+working tree, which in a shared working directory may belong to another agent.
+In that context, follow the explicit-staging + branch-guard pattern documented
+in `story-deliver.md` Step 1.

package/.agents/workflows/helpers/_merge-conflict-template.md

@@ -0,0 +1,54 @@
+# Merge Conflict Resolution — Shared Procedure
+
+Canonical, workflow-agnostic procedure for resolving merge / rebase conflicts.
+Referenced by `git-merge-pr.md`, `story-deliver.md`, and `epic-deliver.md`.
+
+## Procedure
+
+1. **Identify conflicting files.**
+
+   ```powershell
+   git diff --name-only --diff-filter=U
+   ```
+
+2. **For each conflicting file**, open it and read both conflict sides in full:
+   - The `<<<<<<< HEAD` block — content from the branch you are merging _into_
+     (or the rebase target).
+   - The `>>>>>>> <incoming>` block — content from the branch you are merging
+     _in_ (or the commit being replayed).
+
+3. **Resolve**, in order of preference:
+   - **Apply both changes** when they are logically compatible (e.g. two
+     additions to the same list, two new helpers in the same module). This is
+     the default when the two sides touch disjoint responsibilities.
+   - **Choose a single side** only when the two sides are genuinely mutually
+     exclusive. Document the rationale in your commit message or in an inline
+     comment — "chose incoming because it updates the API signature both sides
+     assume" is enough; silent choices are not.
+   - **Never silently drop code.** If neither side can be preserved, raise the
+     conflict to the operator with both sides quoted before making a destructive
+     choice.
+
+4. **Stage the resolved files** and continue the operation:
+
+   ```powershell
+   git add <resolved/path/one> <resolved/path/two>
+   # Rebase path:
+   git rebase --continue
+   # Merge path:
+   git commit    # if the merge was paused for manual resolution
+   ```
+
+5. **Repeat** until the rebase / merge completes cleanly.
+
+## Constraint
+
+- Do not bulk-accept one side (`git checkout --ours` / `--theirs`) without
+  reading the deltas first. These shortcuts are the easiest way to lose
+  legitimate work.
+- Do not use `--no-verify` to bypass commit hooks around a conflict resolution —
+  the hooks are there to catch resolutions that reintroduce syntax errors or
+  broken formatting.
+- If the same file conflicts repeatedly across successive rebase steps, stop and
+  re-evaluate — you may be resolving the same hunk inconsistently across
+  rewrites. `git rebase --abort` is a valid escape hatch.

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -0,0 +1,74 @@
+---
+description: >-
+  Shared include for the bounded acceptance self-eval loop run during Story
+  delivery (both Epic-attached `epic-deliver-story` and standalone
+  `single-story-deliver`). Defines the per-round critic mechanic; each caller
+  supplies its own gate-decision wrapper (snapshot vs. label transitions).
+---
+
+# Bounded acceptance self-eval loop (shared include)
+
+> **Include module.** Not a slash command. Referenced from
+> [`epic-deliver-story.md`](epic-deliver-story.md) and
+> [`single-story-deliver.md`](single-story-deliver.md) at their respective
+> Step 1a. This file is the **single prose home** for the per-round critic
+> mechanic; each caller layers only its own wrapper (snapshot transitions vs.
+> standalone label transitions, and whether to pass `--epic`).
+
+After the implementation commits land and **before** the Story proceeds to
+close, run an explicit, **independent** eval pass that scores the working diff
+against **each** `acceptance[]` item individually. This is the acceptance gate
+the close-validation chain does not provide: that chain (lint / test / format /
+maintainability / coverage / crap) proves the code is *healthy*, not that it
+satisfies *this Story's* acceptance criteria.
+
+The loop is **always on** (a hard cutover — there is no flag to disable it) and
+**bounded** by `delivery.acceptanceEval.maxRounds` (default 2), which the
+resolver clamps into `[1, hard ceiling]` so the cap can never be switched off or
+run unbounded. It is **distinct from** the Epic-level acceptance-spec
+reconciliation in `/epic-deliver` Phase 7.1 (which fires once at finalize and
+only checks `@ac-*` Gherkin tag presence): this loop is per-Story,
+per-criterion, mid-delivery, and evaluates the actual work product.
+
+## Per round
+
+1. **Eval pass (fresh context, independent of the author).** Run a **separate
+   critic pass** — a fresh-context sub-agent (`Agent` tool,
+   `subagent_type: general-purpose`), *not* a continuation of your implementing
+   turn — so the evaluator does not grade its own homework. The critic:
+   - Inspects the working diff (`git diff origin/<baseBranch>...HEAD`) and the
+     Story's inline `acceptance[]` / `verify[]` arrays.
+   - **Runs the `verify[]` commands** and consumes their output as **required
+     evidence** when scoring the relevant acceptance items. `verify[]` is not
+     optional advisory pre-flight — a criterion cannot be scored `met` without
+     the supporting `verify[]` evidence where a `verify[]` command is relevant
+     to it.
+   - Emits a verdict file under `temp/` conforming to
+     [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
+     one `{ index, criterion, verdict: met|partial|unmet, evidence,
+     verifyEvidence[] }` record per acceptance item.
+2. **Decide.** Run the gate against the verdict (the caller's Step 1a names the
+   exact invocation — standalone omits `--epic`; the Epic-attached path passes
+   `--epic <epicId>` so the per-criterion signal lands on the Epic-scoped
+   stream):
+
+   ```bash
+   node <main-repo>/.agents/scripts/acceptance-eval.js \
+     --story <storyId> [--epic <epicId>] --verdict <verdict-path>
+   ```
+
+   The gate validates the verdict against the schema, applies the round cap,
+   emits the per-criterion `acceptance-eval` signal into the retro / feedback
+   substrate, prints a JSON envelope, and exits with one of three decisions:
+   - **`decision: "proceed"`** (every criterion `met`) → exit 0. Proceed to
+     close.
+   - **`decision: "redraft"`** (some `partial`/`unmet`, rounds remaining) →
+     exit 0. Redraft the flagged criteria (named in `unmetCriteria[]`), commit
+     the fix, and re-run the eval pass for the next round.
+   - **`decision: "block"`** (round cap reached, criteria still unmet) → exit
+     non-zero. **Do not proceed to close.** Take the caller's blocked path
+     (transition to `agent::blocked` / flip the snapshot to `blocked`) and post
+     a `friction` comment naming the unmet criteria and their evidence. Never
+     silently proceed to close.
+
+Write the verdict files under `temp/` only — they are scratch artifacts.

package/.agents/workflows/helpers/agents-sync-config.md

@@ -0,0 +1,129 @@
+---
+description: >-
+  Helper procedure — reconcile the project's .agentrc.json against the
+  framework schema (.agents/schemas/agentrc.schema.json) by validating it and
+  surfacing redundant keys (project values that already match framework
+  defaults). The runtime layers defaults at read time, so the helper never
+  auto-fills optional keys from the template. Invoked by reference from
+  /agents-update.
+---
+
+# agents-sync-config (helper)
+
+> **Not a slash command.** Lives under `.agents/workflows/helpers/` so it is
+> not projected into the mandrel plugin command tree. Invoked by reference from
+> [`/agents-update`](../agents-update.md) after a framework update; previously
+> shipped as `/agents-sync-config`. The reconciliation runs as part of the
+> `mandrel update` upgrade path (bump → sync → migrate → doctor).
+>
+> **Configuration reference.** The full set of configurable keys, defaults,
+> and required-vs-optional flags lives in
+> [`docs/configuration.md`](../../docs/configuration.md). This helper only
+> documents the reconciliation procedure.
+
+## Overview
+
+Story #1995 replaced the previous template-merge behaviour with a
+**default-aware** reconciliation: the helper never adds optional keys to the
+project config, because the runtime already layers framework defaults
+underneath the project's values at read time. The only thing the helper
+writes today is a structured report. The mechanical work is delegated to
+[`.agents/scripts/sync-agentrc.js`](../../scripts/sync-agentrc.js).
+
+The reconciliation rules:
+
+| Scenario                                                  | Behavior                                                                                |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| Project value validates against schema                    | **Preserve** unconditionally                                                            |
+| Project value fails validation                            | **Abort** with a list of validation errors                                              |
+| Required key missing in project                           | **Abort via validator** — the schema catches it; the helper does not auto-fill         |
+| Optional key missing in project                           | **Leave absent** — the runtime resolves the framework default at read time              |
+| Project value deep-equals framework default               | **Emit `[REDUNDANT]` advisory** (informational only — the file is never modified)       |
+| Identity placeholder paths (`github.owner` / `repo` / …)  | **Never flagged** — they carry no usable framework default                              |
+
+The defaults source of truth is
+[`.agents/docs/agentrc-reference.json`](../../docs/agentrc-reference.json), consulted via
+[`getAgentrcDefaults()`](../../scripts/lib/config/defaults.js). A parity test
+keeps that file aligned with the schema and the runtime accessors so the
+"what counts as default" question has exactly one answer.
+
+> **Why no auto-fill?** The runtime's `*_DEFAULTS` constants under
+> `.agents/scripts/lib/config/*.js` already layer framework defaults
+> underneath an absent project key — see
+> [`config-resolver.js`](../../scripts/lib/config-resolver.js)'s
+> `applyDefaults`. Writing those defaults into `.agentrc.json` only bloats
+> the consumer repo's config diff without changing runtime behaviour.
+>
+> **Persona**: `devops-engineer` · **Skills**: `core/ci-cd-and-automation`,
+> `core/documentation-and-adrs`
+
+## Procedure
+
+Run from the consumer repo root:
+
+```bash
+node .agents/scripts/sync-agentrc.js
+```
+
+The script:
+
+1. Reads `.agentrc.json` from the working directory (`--cwd <path>` to
+   override). When the file is missing, prints a pointer to
+   `/agents-bootstrap-project` and exits 1.
+2. Validates the parsed config against the framework AJV schema
+   (`getAgentrcValidator()`). On any failure, prints a single-line error
+   list and exits 1 — the operator must fix the typo / missing required
+   key before re-running.
+3. Walks every default leaf path. For each path where the project
+   carries a value deep-equal to the framework default, prints a
+   `[REDUNDANT]` advisory row. Advisories are informational — the
+   project file is never modified.
+4. Prints the summary line and exits 0.
+
+### Exit codes
+
+| Code | Meaning                                                                       |
+| ---- | ----------------------------------------------------------------------------- |
+| 0    | Config is valid (advisories may still appear)                                 |
+| 1    | Config is missing, malformed JSON, or fails schema validation                 |
+
+### Flags
+
+| Flag           | Description                                                        |
+| -------------- | ------------------------------------------------------------------ |
+| `--cwd <path>` | Project root (defaults to `process.cwd()`)                         |
+| `--quiet`      | Suppress the per-key advisory rows (keep only the summary line)    |
+
+## Sample output
+
+```text
+[sync-agentrc] ✅ No changes required.
+[sync-agentrc] Advisories: 4 project key(s) match framework defaults — informational only.
+  [REDUNDANT] project.paths.agentRoot = ".agents"
+  [REDUNDANT] project.paths.docsRoot = "docs"
+  [REDUNDANT] project.paths.tempRoot = "temp"
+  [REDUNDANT] project.baseBranch = "main"
+[sync-agentrc] Redundant keys are safe to delete — the runtime layers framework defaults at read time.
+```
+
+A clean config (or one whose every diverging value is intentional) prints
+only the first line.
+
+## Pruning redundant keys
+
+The helper deliberately does **not** auto-strip redundant keys. Operators
+who want a leaner `.agentrc.json` can delete the flagged paths by hand and
+commit the diff alongside the framework bump. Runtime behaviour is
+unchanged either way — the default layering happens in
+[`config-resolver.js`](../../scripts/lib/config-resolver.js) at read time.
+
+## Constraints
+
+- **Never modifies `.agentrc.json`.** The helper is read-only today.
+- **Never invents values.** When validation fails, the operator fixes the
+  config; the helper does not auto-patch.
+- **Never silently strips.** A project key that fails validation aborts the
+  run with a diagnostic; a project key that validates is preserved
+  unconditionally.
+- **Idempotent.** Running the helper twice produces identical output.
+- **Do not auto-commit.** Operator owns the review/commit decision.

package/.agents/workflows/helpers/code-quality-guardrails.md

@@ -0,0 +1,101 @@
+# Code Quality Guardrails — Helper
+
+Single source of truth for the **numeric coding-time rules** every workflow in
+this framework cites. Reviewers, prescriptive auditors, and writing agents all
+read the same numbers from here so a "high cyclomatic complexity" finding in
+`/audit-clean-code` and a pre-commit refusal cite the same threshold.
+
+> Tunable via `delivery.quality.codingGuardrails` in `.agentrc.json` —
+> see [`agentrc-reference.json`](../../docs/agentrc-reference.json) for the framework
+> defaults and [`schemas/agentrc.schema.json`](../../schemas/agentrc.schema.json)
+> for the validated shape. Override per-project; never fork this helper to
+> change a number.
+
+## At-keyboard verification
+
+Run [`npm run quality:preview`](../../../package.json) before committing
+on any Story that touches production source. The preview runs
+`quality-preview.js` with `--changed-since HEAD`, which exercises the
+same maintainability and CRAP engines (`escomplex` + `c8` coverage) that
+`check-baselines.js` enforces at merge time, then merges the results
+into a single per-file delta table. A clean preview means the commit
+will not bounce off the unified baselines gate. The `.husky/pre-commit`
+hook calls the same script.
+
+## Cyclomatic ceilings
+
+Cyclomatic complexity (CC) is measured per function by `escomplex` (the same
+engine the maintainability axis of `check-baselines.js` runs). Two
+thresholds, sourced from
+`delivery.quality.codingGuardrails.cyclomaticFlag` /
+`cyclomaticMustFix`:
+
+| CC range | Action |
+| --- | --- |
+| ≤ 8 | Pass — no annotation required. |
+| > 8 (default `cyclomaticFlag`) | **Flag** in review: explain why, or split. The function is allowed to land but the audit report names it. |
+| > 12 (default `cyclomaticMustFix`) | **Must-fix**: refactor before the Story commits. `quality:preview` reports it as a violation; the close-validation chain refuses the merge. |
+
+A common refactor that pulls a 13-CC function under 8 is extracting the early-
+return guard chain into a named predicate, then collapsing the remaining
+switch into a lookup table.
+
+## Sibling-test convention
+
+Every commit that adds a new public method or exported function in `src/`
+must add a sibling test in the **same commit**. The test lives next to the
+source under `tests/<mirrored-path>/<basename>.test.js`. Same-commit pairing
+keeps the bisect honest — a regression and the test that would have caught
+it land or revert together.
+
+When `delivery.quality.codingGuardrails.requireSiblingTest` is `true`,
+the pre-commit hook refuses to commit a staged new source file that
+lacks a sibling test. Default is `false` so legacy repos opt in
+deliberately; once enabled, the structural check replaces the
+review-time prose rule.
+
+## Maintainability-Index drop refactor rule
+
+Per-file Maintainability Index (MI) is tracked in
+[`baselines/maintainability.json`](../../../baselines/maintainability.json).
+A commit that drops a file's MI by more than
+`delivery.quality.codingGuardrails.miDropMustRefactor` points (default
+`1.5`) requires a refactor in the same Story — not a baseline bump. The MI
+ratchet's per-file `tolerance` (default `0.5`) is a noise filter, **not**
+permission to spend the budget; the 1.5-point ceiling is the upper bound
+above which the change is treated as a regression that must be undone or
+offset, not absorbed.
+
+`quality:preview --changed-since HEAD` shows the per-file MI delta in the
+working tree before the commit lands.
+
+## Rename = baseline-refresh
+
+Renaming a file (or moving it across `src/` directories) detaches its MI and
+CRAP history from the baseline keys. The correct response is a **baseline
+refresh**, not a regression entry: include `baseline-refresh:` (the
+`delivery.quality.crap.refreshTag` default) in the commit subject so the
+ratchet treats the new key as a clean entry instead of comparing it to
+nothing.
+
+The same convention applies when a method's name changes within a file —
+escomplex keys CRAP rows on `<file>::<methodName>`, so a rename produces a
+phantom new method + a phantom deleted method. Use the refresh tag to
+suppress the noise.
+
+## When a number changes
+
+Update three places **in the same commit**:
+
+1. `delivery.quality.codingGuardrails.<key>` in
+   [`agentrc-reference.json`](../../docs/agentrc-reference.json).
+2. The matching schema bound in
+   [`schemas/agentrc.schema.json`](../../schemas/agentrc.schema.json) and the
+   AJV mirror in
+   [`scripts/lib/config-settings-schema.js`](../../scripts/lib/config-settings-schema.js).
+3. The threshold cell or sentence in this helper.
+
+The drift test (`tests/config-schema-mirror-drift.test.js`) catches schema
+divergence between the JSON mirror and the AJV runtime; the helper-prose
+drift is caught by `audit-clean-code` and `agent-protocol` linking back here
+rather than restating the numbers.