mandrel 1.57.0

package/.agents/rules/changelog-style.md

@@ -0,0 +1,238 @@
+# CHANGELOG Style Contract
+
+This rule governs the shape of per-release entries in the project CHANGELOG
+(typically `docs/CHANGELOG.md` or `CHANGELOG.md`). It applies whenever a
+release entry is authored or edited — most commonly inside Story #N's
+docs sweep before `/epic-deliver` opens the release PR.
+
+The contract is **guidance-tier** in v1: no automated gate fails a close when
+an entry drifts off-template. It still binds every author.
+
+## Goal
+
+A reader scanning release notes should identify what ships in a release in
+under 30 seconds. Breaking changes, config-shape changes, and CLI renames
+must be impossible to miss. Internal refactor detail belongs in commit
+messages and PR descriptions — not here.
+
+## Per-Release Entry Shape
+
+Every entry starts with a version header line already produced by the
+release tooling:
+
+```markdown
+## [X.Y.Z] - YYYY-MM-DD
+```
+
+Immediately below, the entry MUST have:
+
+1. **A short section header** naming the theme of the release — one line,
+   Sentence case, no trailing punctuation.
+
+   ```markdown
+   ### Epic-runner throughput & caching pass
+   ```
+
+2. **A 1–3 sentence theme paragraph** that tells the reader, in plain
+   English, what the release is about and why it matters. No bullets, no
+   sub-headers, no code fences.
+
+3. **Bullets of user-visible changes**, grouped by natural topic if the
+   release spans more than one theme. Each bullet leads with a bold phrase
+   naming the change, followed by a one- or two-sentence explanation.
+
+```markdown
+## [5.21.0] - 2026-04-24
+
+### Epic-runner throughput & caching pass
+
+Performance and observability pass across the epic-runner hot paths — wave
+gating, commit assertion, progress reporting, and label polling. Caching
+and bounded concurrency throughout; new per-phase timing surface.
+
+- **Bounded-concurrency parallelism.** Wave gating, commit assertion, and
+  progress reporting now fan out in parallel with a configurable cap.
+- **Per-phase timing surface.** Story close posts a structured comment
+  with per-phase timings; the Epic progress comment aggregates median
+  and p95 across closed stories.
+```
+
+## Bullets: What Counts as "User-Visible"
+
+Include:
+
+- New CLI commands, flags, or scripts the operator invokes.
+- New or renamed labels, ticket shapes, or workflow phases the operator
+  touches.
+- New or renamed configuration keys, with the old → new mapping if any.
+- New behavioural guarantees (e.g., "retries on transient errors").
+- Bug fixes the operator would otherwise trip over.
+- Performance changes with a user-observable magnitude.
+
+Exclude:
+
+- Internal refactors with no behavioural delta.
+- Test additions, coverage bumps, lint cleanups.
+- Module renames or file moves invisible to operators.
+- Per-phase implementation details ("now uses a BFS walker").
+
+## Banned Content
+
+The following MUST NOT appear in a release entry:
+
+- **Per-ticket citations.** No `(Epic #553)`, `(resolves #612)`,
+  `(Story #645)` in bullet text. The theme paragraph may reference the
+  Epic once when the release is scoped to one Epic — that is the only
+  allowed citation, and only there.
+- **Internal file paths** (`lib/orchestration/epic-runner/commit-assertion.js`,
+  `.agents/scripts/story-init.js`). Callers care what changed, not
+  where it lives.
+- **Internal function, class, or method names** (`finalizeMerge`,
+  `WorkspaceProvisioner.verify`, `cascadeCompletion`). Name the behaviour,
+  not the symbol — unless the symbol is part of the public API.
+- **Test counts** (`47 new tests`, `95% coverage`). Tests are a means, not
+  a ship artefact.
+- **Module-sizing stats** (`shrinks epic-runner from 840 to 420 LOC`).
+- **Implementation mechanics** (`BFS walker`, `Promise.all over parents`,
+  `exponential backoff with 3 attempts, 500ms base`) unless the mechanism
+  is part of a new public contract.
+
+## Mandatory Prominence
+
+The following categories MUST be called out visibly — typically in **bold**
+at the start of a bullet, or in a short dedicated section above the
+bullet list:
+
+- **Breaking changes.** A bullet leading with `**Breaking:**` or a
+  `### Breaking Changes` sub-section. Include the migration path.
+- **Config-shape changes.** Moved, removed, renamed, or newly-required
+  config keys. Old key → new key, or removal notice with remediation.
+- **CLI renames.** Old command → new command, including whether the old
+  name remains as a deprecation alias and for how long.
+- **Schema shape changes** on structured comments, manifest files, or
+  public API payloads. Readers parsing these surfaces must be told.
+
+If a release ships any of the above, they belong at the top of the bullet
+list (or in a dedicated sub-section), not buried mid-list.
+
+## Line-Count Guidance
+
+Soft ceilings, not hard fails:
+
+- **Non-major release** (patch or minor): **≤60 lines**, including
+  header, theme paragraph, blank lines, and bullets.
+- **Major release**: **≤150 lines**. Major releases span larger surface
+  and warrant more prominence.
+
+If an entry exceeds the ceiling, prefer splitting a genuinely multi-theme
+release into grouped sub-sections over padding the bullet list. Before
+accepting a long entry, ask: which bullets are user-visible, and which
+are internal detail that migrated in from the Epic body?
+
+## Worked Example — Before/After
+
+The "before" reflects the style that drove the Epic #553 retro action item:
+multi-section entries where each bullet leaked internal function names,
+file paths, and implementation mechanics. The "after" applies the contract
+above.
+
+### Before (off-contract, ~48 lines)
+
+```markdown
+## [5.8.7] - 2026-04-15
+
+### Robust story→epic merge at story close
+
+Parallel wave execution kept producing conflicts — Stories branched
+early in a wave landed after peers had merged. `finalizeMerge` now:
+
+1. **Pre-merge rebase in the story worktree** onto
+   `origin/<epicBranch>`, shrinking the conflict surface to the
+   Story's real delta. Failed rebase is aborted and merge still
+   proceeds.
+2. **Conflict triage via `mergeFeatureBranch`** — same threshold-based
+   triage used at integration time (major ≥3 files or ≥20 markers =
+   abort; minor = auto-resolve by accepting Story's version with audit
+   log).
+
+### Per-worktree node_modules collapsed into shared store
+
+Per-worktree `npm install` duplicated dependencies across every story
+tree and blew out disk on parallel waves. `ensure()` now links each
+worktree's `node_modules` to a primed donor tree (junction on Windows)
+and `reap()` removes the link before `git worktree remove`.
+Auto-detected: if the configured strategy is `symlink`, the link
+applies.
+
+### Deliver tail auto-invokes pre-merge gates
+
+`/epic-deliver` auto-invokes the code-review module (Phase 4) and
+the retro runner (Phase 5) inline instead of halting to ask the
+operator to run them separately. `--skip-code-review` available as
+an override.
+
+### Epic Health ticket closed alongside PRD/Tech Spec
+
+Step 8's closure sweep now matches any ticket carrying `type::health`
+or a title starting with `📉 Epic Health:`, in addition to
+`context::prd` / `context::tech-spec`.
+
+### Stale-lock sweep for shared `.git/` dir
+
+`WorktreeManager.sweepStaleLocks({ maxAgeMs = 30_000 })` removes
+well-known lock files (`index.lock`, `HEAD.lock`, `packed-refs.lock`,
+`config.lock`, `shallow.lock`) whose mtime exceeds the threshold.
+Fresh locks belonging to in-flight ops are skipped. Runs at
+`/epic-deliver` start, before worktree GC.
+```
+
+Contract violations: five separate `###` sub-sections where one theme
+would do; internal function names (`finalizeMerge`, `mergeFeatureBranch`,
+`ensure()`, `reap()`, `WorktreeManager.sweepStaleLocks`); implementation
+mechanics (`BFS walker` equivalent, exact argument shapes, internal step
+numbering like "Step 1.4", "Step 8"); lock-file name list leaks
+implementation detail that operators cannot act on.
+
+### After (on-contract, ~18 lines)
+
+```markdown
+## [5.8.7] - 2026-04-15
+
+### Parallel-wave merge robustness
+
+Parallel story waves kept tripping over each other at integration time.
+This release reduces the conflict surface at story close and stabilises
+worktree cleanup.
+
+- **Pre-merge rebase at story close** shrinks the conflict window to
+  each story's real delta; conflicts above the triage threshold abort
+  and surface to the operator.
+- **Shared-store worktrees.** Per-story worktrees link a shared
+  `node_modules` store, so parallel waves no longer duplicate installs
+  or leave residue that blocks reap.
+- **`/epic-deliver` auto-invokes pre-merge gates** (code review, retro)
+  inline. `--skip-code-review` is available as an override.
+- **Closure sweep covers Epic Health tickets** in addition to PRD and
+  Tech Spec tickets.
+- **Stale-lock sweep** on the shared `.git/` directory runs at
+  `/epic-deliver` start, clearing lock files left behind by interrupted
+  operations.
+```
+
+What changed: one theme section instead of five; the paragraph gives the
+"why" in two sentences; each bullet leads with the user-visible behaviour
+and drops internal symbols, file paths, and step numbers; the override
+flag (`--skip-code-review`) is kept because it is part of the public CLI
+surface; the lock-file list is dropped because operators do not act on
+individual lock names.
+
+## When to Deviate
+
+- **Major releases** may warrant multiple `###` sub-sections under a
+  single version header when the release genuinely spans multiple themes.
+  Keep each sub-section on-contract individually.
+- **Security fixes** may include CVE-style detail and remediation steps
+  beyond normal bullet shape — those callouts are always on-contract.
+- **When in doubt**, cut more aggressively. A reader can always follow
+  the Epic link for detail; they cannot un-read bullets that told them
+  nothing.

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

@@ -0,0 +1,146 @@
+# Gherkin Authoring Standards
+
+Rules for authoring `.feature` files so scenarios remain business-readable,
+reusable across projects, and free of implementation leakage. Applies to every
+Gherkin file (`*.feature`) in any project that consumes this framework. The
+companion stack skill is
+[`stack/qa/gherkin-authoring`](../skills/stack/qa/gherkin-authoring/SKILL.md);
+test-layer responsibilities live in
+[`testing-standards.md`](./testing-standards.md).
+
+## Tag Taxonomy
+
+Tags are the only supported mechanism for selecting, filtering, and routing
+scenarios. Use the canonical set below; do not invent ad-hoc tags.
+
+- `@smoke` — minimal critical-path scenarios that MUST pass on every PR.
+- `@risk-high` — scenarios covering flows flagged `risk::high` on their
+  originating ticket. Run on every release candidate.
+- `@platform-web` — scenarios that only make sense on the web client.
+- `@platform-mobile` — scenarios that only make sense on the mobile client.
+- `@domain-<slug>` — domain scope (e.g. `@domain-billing`, `@domain-auth`).
+  The slug is project-defined; one tag per scenario.
+- `@flaky` — operational quarantine tag. Scenarios carrying this tag are
+  excluded from the gating suite and run in a dedicated non-blocking job
+  until stabilized. Treat `@flaky` as a debt marker, not a permanent label.
+
+Rules:
+
+- Every `Scenario` or `Scenario Outline` MUST carry exactly one `@domain-*`
+  tag.
+- Platform tags are mutually exclusive. A scenario that applies to both
+  platforms carries neither.
+- `@smoke` and `@risk-high` are orthogonal to domain/platform and may be
+  combined freely.
+- Tag at the `Feature:` level when every scenario shares the tag; tag at the
+  scenario level otherwise. Do not duplicate feature-level tags onto
+  scenarios.
+- Tags not in this taxonomy MUST be proposed in a PR that updates this rule
+  before use.
+
+## Forbidden Patterns
+
+`.feature` files describe business intent. The following MUST NOT appear in
+any `Feature`, `Background`, `Scenario`, `Scenario Outline`, or `Examples`
+block. They belong in step definitions or contract-layer tests instead.
+
+- **Raw SQL or ORM calls.** `SELECT ... FROM ...`, `INSERT INTO ...`,
+  `prisma.user.findMany(...)`, Knex builders, etc. Database access is a step
+  definition concern.
+- **HTTP status codes.** `200`, `401`, `expect status 404`. Status-code
+  assertions are contract-layer tests; scenarios assert user-visible
+  outcomes.
+- **DOM selectors.** CSS selectors, XPath, `#id`, `.class`, `[data-testid=...]`,
+  element tag names. Selectors live inside step definitions.
+- **Raw URLs or route paths.** `/api/v1/users/123`, `https://...`. Reference
+  the business resource (e.g. "the user's profile"), not the transport path.
+- **JSON/request/response payloads.** Shape and field assertions belong in
+  contract-layer tests.
+- **Framework or tooling names.** No `Playwright`, `Cucumber`, `Jest`,
+  `Prisma`, `React` in scenario text.
+- **Timings or waits.** `wait 2 seconds`, `sleep`, `retry 3 times`. Use
+  business-level readiness ("until the invoice is issued"); step definitions
+  own timing.
+
+## Scenario Outline Conventions
+
+Use `Scenario Outline` only when the same behavior is exercised across a
+bounded matrix (roles, permissions, plan tiers, locales). For divergent
+behavior, write separate `Scenario` blocks.
+
+- Placeholders use `<angle-bracket-names>` that match `Examples` column
+  headers exactly.
+- Each `Examples` block MUST include a header row whose names are kebab-case
+  and self-describing (`<user-role>`, not `<x>`).
+- For role/permission matrices, dedicate one column to the role and one
+  column per observable outcome. Do not encode multiple outcomes in a single
+  free-text column.
+- Split `Examples` tables by tag when rows need different tags (e.g.
+  `@risk-high` for admin rows). Each `Examples` block may carry its own
+  tags.
+- Keep `Examples` tables under ~12 rows. Larger matrices indicate the
+  scenario is really several scenarios and should be split.
+
+Example skeleton:
+
+```gherkin
+@domain-billing
+Scenario Outline: <user-role> access to invoice exports
+  Given a signed-in <user-role>
+  When they request an invoice export
+  Then the export is <export-outcome>
+
+  Examples:
+    | user-role      | export-outcome   |
+    | account-owner  | delivered        |
+    | billing-admin  | delivered        |
+    | viewer         | denied           |
+```
+
+## Selector & `data-testid` Discipline
+
+Steps reference **business intent**; selectors are a step-definition
+implementation detail.
+
+- Scenario text names the user-visible concept: "the submit button", "the
+  invoices table", "the error banner".
+- Step definitions resolve concepts to selectors. Prefer `data-testid`
+  attributes (e.g. `data-testid="submit-invoice"`); fall back to role-based
+  queries (`getByRole`) only when `data-testid` is unavailable.
+- `data-testid` values MUST NOT appear in `.feature` files. If a step needs
+  to distinguish between two similar elements, encode the distinction in
+  business language ("the primary submit button"), then let the step
+  definition map that to the `data-testid`.
+- When a new UI element needs a stable hook, add the `data-testid` in the
+  component and reference the business concept in the scenario in the same
+  PR.
+
+## Step Reuse — Grep Before You Write
+
+Before authoring a new step, search the existing step-definition library for
+an equivalent phrase. New steps are a cost: they fragment the vocabulary and
+multiply step-definition maintenance.
+
+Workflow:
+
+1. Identify the verb phrase you want to write (e.g. "the user signs in as").
+2. Grep the step-definition directory for the verb stem:
+
+   ```bash
+   rg -n "signs? in" tests/steps
+   ```
+
+3. If a matching step exists, reuse it verbatim — adjust your scenario
+   phrasing to fit the existing step, not the reverse.
+4. If a near-match exists, extend the existing step (add a parameter, widen
+   the regex) rather than forking a new one. Update every call site in the
+   same PR.
+5. Only when no reasonable match exists, add a new step definition.
+   Co-locate it with related steps and follow the library's naming
+   convention.
+6. Never copy-paste a step implementation to support a paraphrased scenario.
+   Rephrase the scenario instead.
+
+Deprecations: when a step is superseded, mark the old definition deprecated
+in code and migrate all call sites in the same PR. Do not leave two
+near-identical steps live.

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

@@ -0,0 +1,146 @@
+# Git & Version Control Conventions
+
+This rule applies globally to all repository changes to maintain a clean git
+history.
+
+## Canonical Branching (v5 Orchestration)
+
+### Epic Base Branch
+
+Each Epic operates on a dedicated **Epic base branch** named `epic/[EPIC_ID]`
+(e.g., `epic/98`). This branch is created from the project's base branch
+(`main` by default) and serves as the integration target for all Stories
+within that Epic.
+
+### Story-Level Branching
+
+All tasks within a Story MUST be committed to a shared **Story branch**:
+`story-<storyId>` (e.g., `story-104`). The runtime owns Story branch
+creation via `story-init.js`; agents commit on the active Story branch only.
+
+> **Commit subjects.** Under the 3-tier hierarchy
+> (Epic → Feature → Story), Stories have no child tickets. Commits
+> land on `story-<storyId>` directly from the agent and the
+> Conventional Commit subject references the parent Story via
+> `(refs #<storyId>)`. See
+> [`.agents/instructions.md` § 5.D](../instructions.md) for the
+> full hierarchy contract.
+
+## 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.
+
+## Contract Cutovers — No Shim Layer
+
+Mandrel ships as the `mandrel` npm package, whose consumers pin an
+exact lockfile version; they opt into breaks at upgrade time. Operator policy
+for any contract change (config shape, baseline shape, schema, lifecycle
+payload, ticket label, dispatch artifact, public API of a script) is
+therefore:
+
+1. **Hard cutovers only.** Contract changes ship as a single in-tree
+   migration of every producer and consumer. There is no parallel
+   old-shape support code, no read-side tolerance branch, and no
+   feature flag that toggles between the two shapes.
+2. **The PR diff IS the migration.** A consumer upgrading to a release
+   with the change adopts the new shape by upgrading the
+   `mandrel` package (`mandrel update`). The PR that lands on
+   `main` already moved every internal call site; consumers move on the
+   same beat by upgrading.
+3. **No deprecation ledger, no version-windowed sunsets.** The framework
+   does not track "to be removed in vX.Y" entries or run two shapes side
+   by side for a release window. If a shape changes, the old shape is
+   deleted in the same PR.
+
+The codifying decision is **Epic #2646** (the "Hard-Cutover Cleanup Epic"),
+which deleted the existing compatibility shim layer across
+`config-resolver.js`, `lib/config/*.js`, `lib/baselines/`,
+`wave-session.js`, `IExecutionAdapter` / `ManualDispatchAdapter`, lifecycle
+emit shims, and duplicate progress/comment writers in one pass. The
+per-finding closing references (audit Findings #10, #11, #13, #17) live in
+the merged PRs and the Epic #2646 history; the standing forward-looking
+audit lives at [`docs/roadmap.md`](../../docs/roadmap.md) (Part 1 — Model-Evolution Audit).
+
+Practical guidance when authoring a contract change:
+
+- If you are tempted to add a "legacy shape" branch in a parser or
+  resolver, **don't** — update every call site instead, and delete the
+  old shape in the same PR.
+- If you cannot land every call site in a single PR (e.g. a
+  cross-repository change), the contract change is too large for one
+  hard cutover. Split the contract itself, not the rollout.
+- Schema versions remain useful as **identifiers** (so a future consumer
+  can detect "I cannot read this artifact"); they are **not** an
+  invitation to keep multiple readers alive in the same release.
+
+## 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.
+
+## Meta Labels (Retrospective Signal Routing)
+
+Two `meta::*` labels route retrospective signals into durable substrates so
+the `/epic-plan` Phase 0 fetcher (see
+[`prior-feedback-fetcher.js`](../scripts/lib/feedback-loop/prior-feedback-fetcher.js))
+can surface open feedback issues to the planner. Both labels live in
+[`label-constants.js`](../scripts/lib/label-constants.js) under the
+`META_LABELS` export — reference them by symbol from scripts rather than
+hard-coding the string.
+
+### `meta::framework-gap`
+
+Apply this label to a GitHub issue that surfaces a defect, missing
+capability, or weak ergonomic in the **framework itself** (anything under
+`.agents/` or the dispatcher engine). Typical sources: a retrospective that
+identifies a workflow that does not yet exist, a hook that should fire but
+does not, or a script-level usability problem that should be solved
+upstream rather than worked around in a consumer project.
+
+### `meta::consumer-improvement`
+
+Apply this label to a GitHub issue that surfaces an improvement that lives
+in a **consumer project** (workflow tweaks, ergonomic asks, doc polish, or
+project-local automation). The work is scoped to the consumer's
+`.agents/`-driven layer or the consumer's own codebase, not to upstream
+framework changes. Issues that span both axes should carry both labels —
+`fetchPriorFeedback` dedupes by issue number so a dual-labeled issue
+appears exactly once in the planner context.
+
+## 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.

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

@@ -0,0 +1,35 @@
+# Orchestration Error Handling
+
+This rule applies to contributors writing or modifying orchestration scripts
+under `.agents/scripts/*.js` and the helper modules under
+`.agents/scripts/lib/orchestration/**`. Most agent task work does not touch
+these files; consult this rule only when implementing or refactoring
+orchestrators themselves.
+
+## Throw, Never Fatal
+
+Orchestration scripts MUST surface unrecoverable failures with
+`throw new Error(<message>)` rather than `Logger.fatal(<message>)`.
+
+### Why
+
+The `runAsCli` boundary catches the throw and maps it to `process.exit(1)`,
+preserving the operator-visible message verbatim while staying robust under
+a mocked `process.exit` (in tests or when the harness stubs it). By contrast,
+`Logger.fatal` falls through silently when `process.exit` is stubbed, which
+lets execution continue past the intended hard-stop and masks failures.
+
+### Precedent
+
+Story #959 converted every `Logger.fatal` call inside the story-close
+orchestrator surface to `throw` and established this rule for future
+orchestration work.
+
+### Where it applies
+
+- `.agents/scripts/<orchestrator>.js` (top-level CLI entry points)
+- `.agents/scripts/lib/orchestration/**/*.js` (helper modules)
+
+Non-orchestration scripts (one-shot utilities, audit reporters, doc
+generators) may continue to use `Logger.fatal` where the lifetime guarantees
+are simpler.

package/.agents/rules/security-baseline.md

@@ -0,0 +1,92 @@
+# Application Security Baseline
+
+Non-negotiable security MUSTs that apply to every piece of code generated. This
+rule is the SSOT for security taxonomy and constraints; the companion skill
+[`core/security-and-hardening`](../skills/core/security-and-hardening/SKILL.md)
+shows **how** to apply these MUSTs with code patterns, examples, and process
+guidance. Conflicts resolve per the central ordering in
+[`.agents/instructions.md` § 1.K](../instructions.md) — this rule sits above
+the skill, and its security MUSTs are **inviolable**: no persona, skill, or
+local override may relax them. The skill is updated to match.
+
+## Input Validation
+
+- ALL input received from the client (body, query params, headers, path params)
+  MUST be validated at the edge using a strict schema (e.g., Zod). Validation
+  runs at the system boundary — never trust client-side validation as a
+  security control.
+- Never trust client-provided IDs without verifying ownership recursively.
+- File uploads MUST validate type (mimetype, optionally magic bytes) and size
+  before persisting or processing.
+
+## Authentication
+
+- Passwords MUST be hashed with `bcrypt`, `scrypt`, or `argon2`. Salt rounds
+  for bcrypt MUST be ≥ 12. Plaintext password storage is forbidden.
+- Session tokens MUST be stored in cookies that are `httpOnly`, `secure`, and
+  carry an explicit `sameSite` policy (`lax` or `strict`). Auth tokens MUST
+  NOT be placed in client-accessible storage (e.g., `localStorage`,
+  `sessionStorage`).
+- Authentication endpoints MUST be rate-limited.
+
+## Authorization
+
+- Every protected endpoint MUST check user permissions, not just authentication.
+  "Logged in" is not "allowed".
+- Users MUST only be able to access or modify resources they own; ownership
+  checks MUST run server-side before any state change.
+- Admin or elevated actions MUST verify the role server-side; never trust a
+  client-asserted role claim.
+
+## Output & Rendering
+
+- Database queries MUST be parameterized. Never concatenate user input into
+  SQL, NoSQL filters, or shell commands.
+- HTML output MUST be encoded via the framework's auto-escaping. If raw HTML
+  rendering is unavoidable, sanitize with a vetted library (e.g., DOMPurify)
+  first.
+- `eval()`, `Function()`, and `innerHTML` (or framework equivalents like
+  `dangerouslySetInnerHTML`) MUST NOT receive user-provided data without
+  sanitization.
+- API responses MUST exclude sensitive fields (password hashes, reset tokens,
+  internal IDs not intended for clients). Stack traces and internal error
+  details MUST NOT be exposed to users.
+
+## Data Leakage & Logging
+
+- NEVER log Personal Identifiable Information (PII) such as emails, passwords,
+  full credit card numbers, session tokens, or phone numbers.
+- Avoid logging complete objects directly; destructure out safe properties.
+
+## Transport & Headers
+
+- All external communication MUST use HTTPS.
+- Security headers MUST be configured: `Content-Security-Policy`,
+  `Strict-Transport-Security`, `X-Frame-Options`, `X-Content-Type-Options`.
+- CORS MUST be restricted to a known origin allowlist. Wildcard (`*`) origins
+  are forbidden on endpoints that accept credentials.
+
+## Secrets Management
+
+- Keys, passwords, and tokens MUST be pulled from environment variables.
+  Fallback or placeholder secrets MUST NOT be committed in code.
+- `.env` files containing real secrets MUST be gitignored. Only `.env.example`
+  (placeholder values) is committed.
+
+## Dependency Hygiene
+
+- `npm audit` (or the project equivalent) MUST run before every release.
+  Critical and high-severity vulnerabilities reachable in production code MUST
+  be remediated before shipping; deferred findings MUST be documented with a
+  review date.
+
+## Forbidden Practices
+
+- Committing secrets to version control.
+- Logging passwords, tokens, or full credit-card numbers.
+- Trusting client-side validation as a security boundary.
+- Disabling security headers for convenience.
+- Using `eval()` or `innerHTML` with user-provided data.
+- Storing auth tokens in client-accessible storage.
+- Exposing stack traces or internal error details to users.
+- Hardcoding fallback secrets ("default" API keys, debug bypasses) in source.