mandrel 1.57.0

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

@@ -0,0 +1,70 @@
+# Shell & Terminal Conventions
+
+This rule applies when running shell commands during agent execution. The host
+shell varies — agents must adapt to the environment.
+
+## Detecting the Shell
+
+Before chaining commands, check the host shell. Common signals:
+
+- `$env:COMSPEC` set / `pwsh.exe` or `powershell.exe` → PowerShell
+- `$SHELL` set to `/bin/bash`, `/bin/zsh`, etc. → POSIX shell
+- Claude Code system prompt or harness directive announces the shell
+
+## PowerShell (Windows)
+
+PowerShell 5.1 (default on Windows) does **not** support `&&` as a statement
+separator and will throw a parser error. PowerShell 7+ does, but agents
+running on Windows should not assume version 7+.
+
+- **Standard separator**: `;` runs the next command regardless of the first's
+  exit status.
+- **Success chaining (logical AND)**: `; if ($?) { ... }` runs the second
+  command only when the first succeeded.
+- **Example**: `git add . ; if ($?) { git commit -m "..." }`
+
+Other PowerShell-isms agents must respect:
+
+- Use `$null` (not `/dev/null`).
+- Use `$env:VAR` (not `$VAR`).
+- Use backtick (`` ` ``) for line continuation, not backslash.
+
+## POSIX Shells (bash / zsh)
+
+`&&` and `||` work natively. No translation needed.
+
+- **Success chaining**: `cmd1 && cmd2`
+- **Fallback**: `cmd1 || cmd2`
+
+## Cross-Platform Tips
+
+- Prefer the host's tool wrappers (Bash tool, etc.) over raw shell strings
+  when the harness exposes them — they normalize quoting and escaping.
+- For multi-step pipelines that must run identically across platforms, write
+  a Node/Python script and invoke that, rather than chaining shell builtins.
+
+## Searching the Workspace
+
+When searching for strings, patterns, or files, prioritize speed and avoid
+pipeline bottlenecks or full-file reads. Use this decision tree:
+
+1. **Host grep tool first.** If the harness exposes a dedicated grep tool
+   (e.g. Claude Code's `Grep` tool, ripgrep wrappers), use it. These
+   normalize quoting, respect `.gitignore`, and stream results.
+2. **`git grep`** when the workspace is a git repo and no host tool is
+   available. Pass `-l` to list only filenames when paths are sufficient.
+3. **`rg` (ripgrep)** when installed and outside a git repo, or when you
+   need features `git grep` lacks (multiline, type filters).
+4. **Avoid full-file reads** for searches. Reading whole files into memory
+   to scan for a pattern wastes context and is slower than a streaming
+   grep.
+
+### PowerShell-specific anti-patterns
+
+- If you must use `Select-String`, pass `-List` when you only need to
+  detect existence or collect file paths — without it, every match streams
+  through the pipeline.
+- NEVER chain `Select-Object -Unique` or `Sort-Object` directly after a
+  highly recursive `Get-ChildItem` on large trees. Both block the pipeline,
+  hold every result in memory, and frequently hang the terminal. Stream
+  through `Where-Object` filters first, or pre-narrow with a glob.

package/.agents/rules/test-seams.md

@@ -0,0 +1,59 @@
+# Injectable Test Seams
+
+This rule applies when writing or modifying scripts under
+`.agents/scripts/lib/` that perform filesystem I/O or spawn child processes.
+
+## Motivation
+
+Functions that hard-bind `fs` or `spawnSync` at module scope cannot be unit-
+tested without side-effecting the real filesystem or spawning real processes.
+The injectable-seam pattern threads replaceable implementations through a
+default-param `deps` object so tests substitute stubs while production code
+continues to call the real Node built-ins with zero configuration change.
+
+## The Pattern
+
+Each function that performs I/O accepts an optional final parameter named
+`deps` (or named individual dep params such as `fsImpl`, `spawnImpl`) that
+defaults to the real implementation:
+
+```js
+import fs from 'node:fs';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+
+export function ensureSomething(ctx, { fsImpl = fs, spawnImpl = defaultSpawnSync } = {}) {
+  if (fsImpl.existsSync(ctx.target)) return { action: 'already-present' };
+  fsImpl.writeFileSync(ctx.target, ctx.body, 'utf8');
+  return { action: 'created' };
+}
+```
+
+### Canonical In-Repo Reference
+
+`baseline-snapshot.js` (`forkMainToEpic` at line 135 / `commitSnapshotsToEpicBranch`
+at line 259) is the established baseline for this pattern in this codebase.
+
+## Rules
+
+1. **Default to the real impl.** The default value MUST be the real built-in so
+   callers (bootstrap CLI, integration tests) require no change.
+2. **One seam per I/O surface.** Filesystem access uses `fsImpl`; child-process
+   spawning uses `spawnImpl`. Do not bundle them into a single opaque deps
+   object unless the function is exclusively internal (not exported).
+3. **No module-level seam state.** Seam parameters live on individual functions,
+   not on a shared module-level variable. Module-level variables are reset only
+   on re-import, which makes parallel test isolation impossible.
+4. **Re-export the real impl when a helper wraps it.** If a private helper
+   (`readJsonIfExists`, `writeJson`) receives `fsImpl`, it must accept and
+   forward the seam — not re-acquire `fs` at call time.
+5. **Tests inject stubs via the parameter, never via module mocking.** Prefer
+   passing a plain object `{ existsSync: () => false, readFileSync: () => '' }`
+   over `mock.module()` / `jest.mock()` so tests remain isolated and
+   parallelizable.
+
+## Where It Applies
+
+- `.agents/scripts/lib/bootstrap/project-bootstrap.js` (primary consumer of
+  this rule — every exported step function).
+- Any new helper in `.agents/scripts/lib/` that touches the filesystem or
+  spawns a process.

package/.agents/rules/testing-standards.md

@@ -0,0 +1,177 @@
+# Testing Standards
+
+Rules to enforce robust, reliable, and consistent testing methodologies. These
+standards are pyramid-aware: every test belongs to exactly one of three
+tiers — **unit**, **contract**, or **e2e / acceptance** — and each tier has
+distinct responsibilities, scope, and assertion style. Choosing the correct
+tier is the first decision when adding a test; the companion rule
+[`gherkin-standards.md`](./gherkin-standards.md) governs how acceptance-tier
+scenarios are authored. The companion skill
+[`core/test-driven-development`](../skills/core/test-driven-development/SKILL.md)
+shows **how** to apply these standards (TDD cycle, Prove-It Pattern, naming,
+anti-patterns) — read this rule for the **what**. When the skill and this
+rule diverge, this rule wins, per the central ordering in
+[`.agents/instructions.md` § 1.K](../instructions.md) (rules sit above
+skills).
+
+## The Three Tiers
+
+### Unit
+
+Pure logic, no I/O. Unit tests exercise a single function, component, or
+module in isolation and make up the broad base of the pyramid.
+
+- **Scope.** Pure functions, reducers, formatters, parsers, validators,
+  component rendering with mocked props, hook logic with mocked context.
+- **Dependencies.** All external network, database, filesystem, and time
+  sources MUST be mocked. Never let a unit test make a real call.
+- **Assertions.** Return values, thrown errors, rendered output, emitted
+  events. Do not assert on HTTP status codes, SQL, or wire formats — those
+  are contract-tier concerns.
+- **Location.** Colocate `*.test.ts` / `*.test.tsx` alongside the file under
+  test, or in a `__tests__/` directory inside the same module. Never use the
+  `.spec.` suffix.
+- **Coverage.** Unit tests are where line and branch coverage targets are
+  met. Mutation testing (e.g. Stryker), when configured, runs at this tier.
+
+### Contract
+
+API ↔ DB invariants, schema conformance, adapter and boundary contracts.
+Contract tests exercise the shape of data crossing a process or service
+boundary and are where shape, status, and error-body assertions live.
+
+- **Scope.** REST/GraphQL handler ↔ persistence round-trips, Zod/JSON-schema
+  validation, adapter contract tests against a real (or high-fidelity
+  in-memory) database, event-payload conformance, backwards-compatibility
+  tests for published API surfaces.
+- **Dependencies.** Use a real database (Testcontainers, SQLite file, or
+  project equivalent) or a contract-grade fake. Do not mock the boundary
+  that is under test. External third-party services MAY be mocked; the
+  system-under-test's own persistence layer MUST NOT be.
+- **Assertions.** HTTP status codes, response bodies, error shapes, DB row
+  state after a write, schema conformance, pagination envelopes, idempotency
+  keys. This is the correct home for *all* status-code and wire-shape
+  assertions.
+- **Location.** `tests/contract/**/*.test.ts` or the project's equivalent
+  contract directory. Keep contract tests separate from unit tests so they
+  can be executed (and timed) independently.
+- **Coverage.** Measured by contract surface covered (endpoints, events,
+  schemas), not line coverage. Every public API surface MUST have at least
+  one contract test exercising the happy path and at least one negative
+  case.
+
+### E2E / Acceptance
+
+User-visible journeys, authored in Gherkin (`.feature` files) and executed
+through a browser or mobile automation runner. These sit at the narrow top
+of the pyramid.
+
+- **Scope.** Multi-step user journeys that cross UI, API, and persistence —
+  e.g. "sign in, create an invoice, send it, see it in the outbox". One
+  scenario per user-visible outcome.
+- **Authoring.** Scenarios MUST follow
+  [`gherkin-standards.md`](./gherkin-standards.md) — business intent only,
+  canonical tag taxonomy, step reuse, no implementation leakage.
+- **Dependencies.** Run against a real application stack (local, ephemeral,
+  or preview environment) with seeded test data. Do not mock the UI, API,
+  or DB at this tier.
+- **Assertions.** User-visible outcomes only: a banner appears, a row shows
+  up in a list, a PDF downloads. Never assert on DB rows, HTTP status
+  codes, or JSON shapes here — push those down to the contract tier.
+- **Location.** `tests/features/**/*.feature` with step definitions in
+  `tests/steps/**` (or the project's equivalent). The companion skill is
+  [`stack/qa/playwright-bdd`](../skills/stack/qa/playwright-bdd/SKILL.md).
+
+## Assertion Placement Rule {#assertion-placement}
+
+**DB assertions and API-shape assertions MUST live at the contract tier.**
+They MUST NOT appear in `.feature` files, and SHOULD NOT appear in unit
+tests.
+
+"DB assertions" means any check against persisted state — a row count, a
+column value, the presence or absence of a record after a write.
+
+"API-shape assertions" means any check against wire format or transport
+semantics, including:
+
+- HTTP status codes (`200`, `401`, `404`, etc.)
+- Response body shape, field names, field types
+- Error envelope structure (error codes, error messages, problem+json
+  fields)
+- Pagination metadata (cursors, page counts, `total` fields)
+- JSON/OpenAPI/Zod schema conformance
+- Header values that carry protocol semantics (`Location`, `ETag`,
+  `Retry-After`)
+
+When a reviewer finds one of the above in a `.feature` file, the required
+remediation is to delete it from the scenario and add (or extend) a
+contract test that covers the assertion. The scenario should assert the
+**user-visible outcome** only ("the invoice appears in the outbox"), not
+the wire shape that produced it.
+
+This rule is enforced bidirectionally: the companion prohibition on
+`.feature` authoring lives in
+[`gherkin-standards.md § Forbidden Patterns`](./gherkin-standards.md#forbidden-patterns),
+which forbids raw SQL, HTTP status codes, DOM selectors, URLs, and JSON
+payloads inside scenarios. That list and this section are two sides of the
+same constraint: shape and state belong in contract tests; business
+outcomes belong in acceptance scenarios.
+
+This is the pyramid's load-bearing constraint. It is why the contract
+tier exists as a distinct layer, and why acceptance scenarios stay
+readable, stable, and free of implementation churn.
+
+## Test Structure (Arrange, Act, Assert)
+
+Every test at every tier follows the same three-block structure:
+
+1. **Arrange.** Set up state, fixtures, mocks, seeded data, or page
+   navigation.
+2. **Act.** Call the function, hit the endpoint, or drive the user
+   interaction.
+3. **Assert.** Validate the outputs or side effects appropriate to the tier.
+
+Do not interleave arrange/act/assert. Do not chain multiple unrelated
+assertions into a single "kitchen sink" test — split them.
+
+## Mocking & Isolation
+
+- Unit tests MUST mock all external network calls, database access, and
+  filesystem I/O. Contract tests MUST NOT mock the boundary under test
+  (the DB or the API). E2E tests mock nothing within the system under test.
+- Never write tests that depend on real-world timing unless explicitly
+  testing a timeout — use fake timers instead.
+- Reset mocks in `afterEach` (unit) or tear down seeded data in `afterEach`
+  / `afterAll` (contract). Do not let state leak between tests.
+- Parallelization: unit and contract suites MUST be safe to run in
+  parallel. If a contract test requires exclusive DB access, gate it behind
+  a named serial worker — do not reorder the whole suite.
+
+## Coverage & Mutation Thresholds
+
+- **Line / branch coverage** is measured at the unit tier only. Project
+  defaults live in the consuming repo's coverage config; do not target
+  coverage percentages on contract or e2e suites.
+- **Contract coverage** is measured by API surfaces exercised, not lines.
+  Every endpoint, event, and published schema SHOULD have at least one
+  happy-path and one negative-path contract test.
+- **Mutation testing** (when configured) runs on the unit tier. It is not
+  meaningful at the contract or e2e tiers because those tiers exercise
+  integration paths rather than isolated logic.
+- Coverage targets apply to production code. Test helpers, fixtures, and
+  generated code are excluded per the project's coverage config.
+
+## Property-Based Testing (a technique, not a tier)
+
+Property-based testing is a **technique** — generating a domain of inputs and
+asserting invariants that must hold across all of them — not a fourth tier. It
+layers onto the **unit** tier (and occasionally the **contract** tier) without
+changing where a test lives or how it is mocked: the tier-placement, mocking,
+and coverage MUSTs above remain the SSOT and continue to govern any
+property-based test. Reach for it when a unit's correctness is better expressed
+as an invariant over many inputs than as a handful of hand-picked examples
+(parsers, encoders/decoders, serializers, sorting, idempotency).
+
+For the how — choosing properties, shrinking, generators, and worked
+examples — see the companion skill
+[`core/property-based-testing`](../skills/core/property-based-testing/SKILL.md).

package/.agents/runtime-deps.json

@@ -0,0 +1,18 @@
+{
+  "description": "Single source of truth for the third-party npm packages the .agents/ framework scripts import at runtime. This manifest ships *inside* .agents/ so it travels with the mandrel package into consumer projects. Consumers must provide these packages in the node_modules resolvable from their repository root (the framework scripts free-ride on the consumer's install). The `dependencies` block is fail-fast enforced by the preflight guard (.agents/scripts/lib/runtime-deps/ensure-installed.js); the `optionalDependencies` block lists packages that are imported behind graceful-degradation paths (try/catch or dev-only watch tooling) and are therefore declared but never preflight-blocked. A drift test (tests/scripts/runtime-deps-drift.test.js) asserts every third-party import under .agents/scripts/** is declared here. Version ranges mirror the framework's own root package.json.",
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.1",
+    "minimatch": "^10.0.0",
+    "picomatch": "^4.0.4",
+    "string-argv": "^0.3.2",
+    "typescript": ">=5.0.0",
+    "typhonjs-escomplex": "^0.1.0"
+  },
+  "optionalDependencies": {
+    "@commitlint/load": "^21.0.0",
+    "chokidar": "^5.0.0",
+    "jscpd": "^4.0.0"
+  }
+}

package/.agents/schemas/acceptance-eval-verdict.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "acceptance-eval-verdict",
+  "title": "Acceptance Self-Eval Verdict",
+  "description": "Structured output of one independent (fresh-context) acceptance self-eval round (Story #3819). Produced by the critic pass in the Story-implementation phase (helpers/epic-deliver-story.md Step 1 / helpers/single-story-deliver.md Step 1), written under the gitignored temp tree, and consumed by acceptance-eval.js to enforce the bounded round cap and decide whether the Story proceeds to `closing`, redrafts, or escalates to `agent::blocked`. The author MUST NOT be the evaluator — the verdict is an independent judgment of the working diff against each inline acceptance[] item.",
+  "type": "object",
+  "required": ["storyId", "schemaVersion", "round", "criteria"],
+  "properties": {
+    "storyId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "GitHub Issue number of the Story being evaluated."
+    },
+    "epicId": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "Parent Epic id when the Story is Epic-attached; null for standalone Stories."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Verdict-record schema version. Bumped on breaking changes to the record shape."
+    },
+    "round": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "1-based index of this eval round. Round 1 is the first evaluation after implementation; rounds 2..N are post-redraft re-evaluations. Bounded by delivery.acceptanceEval.maxRounds (clamped to an undisableable hard ceiling)."
+    },
+    "commitSha": {
+      "type": ["string", "null"],
+      "pattern": "^[0-9a-f]{7,64}$",
+      "description": "Output of `git rev-parse HEAD` at the moment the diff was evaluated. Optional but recommended for traceability."
+    },
+    "criteria": {
+      "type": "array",
+      "minItems": 1,
+      "description": "One verdict per inline acceptance[] item, in the same order as the Story body. Every acceptance item MUST appear exactly once.",
+      "items": {
+        "type": "object",
+        "required": ["index", "criterion", "verdict", "evidence"],
+        "properties": {
+          "index": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "0-based position of this criterion in the Story's acceptance[] array."
+          },
+          "criterion": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The verbatim (or faithfully summarised) acceptance[] item text being scored."
+          },
+          "verdict": {
+            "type": "string",
+            "enum": ["met", "partial", "unmet"],
+            "description": "Per-criterion judgment of the working diff. `met` clears the criterion; `partial` and `unmet` both trigger a redraft round (subject to the cap)."
+          },
+          "evidence": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short concrete evidence supporting the verdict — file:line references, test names, command output excerpts. Never an empty self-attestation."
+          },
+          "verifyEvidence": {
+            "type": "array",
+            "description": "Required evidence drawn from the Story's verify[] commands the critic ran (or inspected) while scoring this criterion. verify[] is promoted from optional advisory pre-flight to required evidence the eval pass consumes. Empty only when no verify[] command is relevant to this criterion.",
+            "items": {
+              "type": "object",
+              "required": ["command", "outcome"],
+              "properties": {
+                "command": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "The verify[] command that was run or inspected."
+                },
+                "outcome": {
+                  "type": "string",
+                  "enum": ["pass", "fail", "skipped"],
+                  "description": "Result of the verify[] command. `skipped` is permitted only with a stated reason and never for a criterion marked `met`."
+                },
+                "detail": {
+                  "type": ["string", "null"],
+                  "description": "Optional excerpt of command output or the reason a command was skipped."
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}