@1aboveio/skills 1.0.9 → 1.0.11

package/skills/engineering/better-review/references/passes.md

@@ -17,11 +17,10 @@ finding's `rule` and `paths` ([result.md](result.md)). Below a P0/P1, skip them.
    it is a P2 follow-up. On a delta, search again only when the fix diff adds or moves a writer.
    Example: grep every call that changes a balance: the refund route, the batch refund job, and
    the chargeback webhook are three rows, not the one the trigger used.
-3. **Check every path against one shared list of conditions, including its own failure.** For
-   a path that guards a session, credentials, money, or a deletion, settle it each way
-   (success, refusal, error, timeout) against the same list of events for every path; for other
-   paths, the events that can reach it. An event the program cannot produce is ruled out in one
-   line; one guard that rules out a whole row of events closes every cell in it.
+3. **Check relevant conditions on every path.** Select reachable outcomes and interleavings
+   from the broken rule, changed contract, and material risks, including failures where they
+   matter. Follow binding repo hazard and proof requirements. Rule out a case using code, not
+   assumptions about how it is reached; do not build a full event matrix by default.
    Example: an org switch was tried against "offline" and "a second tab", never against "the
    role lookup times out after the switch", and that cell granted the old org's role.
 4. **One rule, one finding, one id, every round.** A new witness that breaks the same guarded
@@ -30,47 +29,40 @@ finding's `rule` and `paths` ([result.md](result.md)). Below a P0/P1, skip them.
    an id resolved in an earlier round that breaks again is a new id whose summary names it.
    Example: a cache-invalidation finding fixed for writes is still open when a bulk import
    leaves the cache stale: same id, one more open row.
-5. **Name one owner as the fix.** Prefer the place every path passes through: a guard copied to
-   each path misses the next one. Copied guards that close every row still resolve the
-   finding; when no such place exists, say so, and the rows are the fix.
+5. **Identify the applicable paths, not a mandatory architecture.** A shared owner may help
+   explain a defect, but do not require centralization or prescribe a new framework. Copied
+   guards that close every row resolve the finding.
    Example: three handlers each re-check the tenant; the owner is the repository method all
    three call.
-6. **A rule that breaks again after a fix means the approach is wrong.** Say so in the
-   finding, name the owner (5), and re-derive every path (2); never review the next patch as if
-   it were the first. Example: the refund cap is open after two fixes, each adding a check to
+6. **A rule still broken after a fix stays open.** Say so in the finding and re-derive every
+   path (2); never review the next patch as if it were the first. Example: the refund cap is open after two fixes, each adding a check to
    one route: the finding names the balance service as the owner and lists every writer.
 
 ## Adversarial techniques
 
 "Be adversarial" means nothing without a method. The one move behind all four: **build the
-specific artifact that would fail, and cite it.** A finding with no concrete trigger is a hunch.
+specific artifact that would fail, and cite it.** Alternatively cite an explicit unmet requirement
+and evidence; a finding supported by neither is a hunch.
 
 - **Diff each new or changed function against its siblings.** Find its family: the same module,
   naming pattern, or role (a set of `detect*`, `validate*`, `parse*`, or route handlers). Compare
   the logic line by line. A function that handles a case differently, uses a looser or tighter
-  pattern, orders its guards differently, or lacks a branch all its siblings have is a defect until
-  the difference is justified. Name the sibling and the exact divergence, for example:
+  pattern, orders its guards differently, or lacks a branch all its siblings have is a lead to
+  investigate, not a defect without a supported failure or unmet requirement. Name the sibling
+  and the exact divergence, for example:
   "`detectOverMockedEvidence` matches `route.fulfill` but its sibling `detectTier1UiOnlyEvidence`
   also matches `page.route(`, so the first misses that vector."
-- **Break patterns with boundary inputs.** For each regex, glob, string match, or parser the diff
-  adds or changes, write the input that breaks it before you trust it: prefix or substring leakage
-  (does `/foo` also match `/foobar`? is it anchored?), empty or whitespace, case, escaping and
-  metacharacters, unicode, very long input. Put the failing string in the finding.
-- **Hold each async step open.** For every async step the change relies on (sign-out, revoke,
-  refresh, cancel, save, upload), ask what the code does *while it is pending*, and settle it
-  each way (success, refusal, error, timeout) against every event that can coincide:
-  backgrounded or hidden, offline, a second request, a retry, a sign-in as the same or a
-  different subject, sign-out, expiry ([principle 3](#review-the-rule-not-the-instance) scopes
-  the list). Write the sequence that interleaves them. Rule a cell out only by code that prevents
-  it (a guard, a lock, a state check), never by how you expect the step to be reached: list every
-  caller of the step, including timers, push events, expiry, and error handlers, not just the
-  button a user presses. A test that awaits the step to completion never runs this window, so it
-  proves nothing about it. Example: "export a report to a temp
-  file, put the app in the background, then log out and leave the logout request hanging: the
-  cleanup waits for logout to finish, so the exported file outlives the session."
-- **Name a test for each new branch.** For every conditional, `else`, early return, switch case,
-  and error path in the diff, find the test that drives it. A branch whose failure would be
-  observable and has no test is a gap; line coverage is not branch coverage.
+- **Break relevant patterns with boundary inputs.** Choose inputs from the contract and material
+  risks, such as prefix leakage, empty values, case, escaping, or malformed input. Put a failing
+  input in the finding; do not require every boundary for every pattern.
+- **Examine relevant async windows.** Where the contract or material risk depends on pending
+  state or ordering, trace reachable callers and interleavings, including failure outcomes that
+  matter. Cite the sequence or the code that rules it out. A completed async test does not prove
+  a pending state. Example: "export a report to a temp file, background the app, then leave
+  logout hanging: cleanup waits for logout, so the file outlives the session."
+- **Assess test evidence for the changed behavior.** Look for tests that can expose material
+  failures and for proof explicitly required by the agreement or binding repo rules. Do not
+  demand a test for every branch or invent a new harness.
 
 Shapes to look for while doing this:
 
@@ -85,12 +77,12 @@ Shapes to look for while doing this:
   can pin its own expected state, so the service accepting it proves nothing about the action the
   button calls.
 - **A permanent event routed through a temporary path.** Code that handles "paused, hidden,
-  checking" and "revoked, signed out, deleted" in one branch keeps data or access alive after it
-  should be gone. Check each permanent event arriving during each temporary state, and record it
-  under `windows` (see "Revocation during a pause" in [domain-hazards.md](domain-hazards.md)).
+  checking" and "revoked, signed out, deleted" in one branch can keep data or access alive after
+  it should be gone. Check relevant reachable interleavings and record them under `windows`
+  (see "Revocation during a pause" in [domain-hazards.md](domain-hazards.md)).
 - **Centralizing drops an edge.** A refactor that moves a cross-cutting concern into one place (an
   auth redirect into a layout, error handling into a shared hook) silently loses edges the old
-  paths handled. Check that the old edges are pinned by a test that existed before the move.
+  paths handled. Check relevant old behavior against the changed contract and any required proof.
 
 ## Enforcement-point sweep
 
@@ -122,10 +114,10 @@ searching for the old value, not by rerunning the suite.
 
 Search hard; then report only what survives this bar.
 
-- **Provable.** Every finding cites the diff hunk, and for a ripple effect the code it provably
-  breaks. Label any inference.
-- **One finding per broken rule.** Say the rule, every open path in `paths`, and the one owner
-  that fixes it. Example: four places miss the generation check: one finding with four open
+- **Provable.** Cite the diff hunk and a supported failure, or the explicit unmet requirement
+  and evidence. For a ripple effect cite the code it breaks. Label any inference.
+- **One finding per broken rule.** Say the rule and every open path in `paths`; identify a
+  shared owner when useful, without making an architecture decision. Example: four places miss the generation check: one finding with four open
   rows, not four findings and not one row.
 - **The author would fix it.** Do not flag intended changes or rely on guesses about intent.
 - **Rigor in proportion.** Hold the code to the bar the surrounding code already holds.
@@ -135,6 +127,8 @@ Do not raise:
 
 - a sibling divergence that is justified by a genuinely different case;
 - an unanchored pattern whose inputs come from a closed, validated set;
+- a missing test or hypothetical hardening as a blocker without required proof or a concrete
+  material defect; do not invent gates, expanded acceptance, a new harness, or unrelated cleanup;
 - an "untested" branch already driven by an integration or E2E test, or whose failure is harmless;
 - a fake of a real external boundary (third-party API, clock, email, randomness);
 - a pre-existing issue the diff neither depends on nor worsens as a blocker (P2 at most);

package/skills/engineering/better-review/references/result.md

@@ -10,8 +10,8 @@ Only P0/P1 block. Pick the level by consequence, not by which pass found it. Nev
 | Level | Meaning |
 |---|---|
 | **P0** | Exploitable security, auth, tenancy, money, or data-loss defect on a reachable path. |
-| **P1** | A contract break: an acceptance criterion unmet or wrong, required behavior wrong, a correctness bug with a concrete breaking input, a required repo standard or gate violated, a dishonest test cited as proof, or prose agents act on that contradicts the code. |
-| **P2** | A real defect outside the contract: optional hardening, an untested branch whose failure is observable, scope creep, test tooling that hides no product bug. |
+| **P1** | A supported contract break: an explicit acceptance criterion or binding repo rule unmet, agreed or binding required proof missing, or a correctness defect with a concrete breaking input or sequence. Cite the requirement and evidence or the supported failure. |
+| **P2** | A material non-blocking issue: for example, a test weakness or scope creep that does not violate required proof or show a concrete material defect. Optional hardening alone is not a blocker. |
 | **P3** | Not reported. Cleanup, naming, smells, cosmetics, architecture opinions, minor pre-existing issues: leave them out of the result and the chat report. |
 
 A pre-existing defect the diff neither causes nor worsens is never P0/P1 for this change, however
@@ -101,7 +101,9 @@ P2 lacks its follow-up URL when the caller asked for follow-ups.
 - `commands` lists the checks you ran against the code. Leave out this skill's update check and its
   scripts (`pr-context.mjs`, `scan-diff.mjs`, `rereview-scope.mjs`): a caller reads a non-empty
   list as proof the code was checked.
-- `trigger` is required on P0/P1: the input, state, or sequence that breaks it.
+- `trigger` is required on P0/P1: the concrete input, state, or sequence that breaks it; for
+  an explicitly unmet requirement or missing required proof, identify the requirement and the
+  evidence of what is missing.
 - `rule` and `paths` are required on P0/P1, with at least one row `open`: the rule as one
   sentence, and one row per path the diff adds, changes, or relies on (a writer, caller, sweep
   place, or async cell), each `open` or `closed`, a closed row citing its guard's `file:line`.
@@ -124,12 +126,11 @@ P2 lacks its follow-up URL when the caller asked for follow-ups.
   needs both matching identities, otherwise review in full. Empty `sweeps` is `[]`.
 - On a delta, retain the tier decision (`reasons`, `integrationFiles`, `integrationLines`,
   `baseMovedFiles`, and prior HEAD) so carry-forward approval names what was checked.
-- `windows` lists each async step the change relies on, every caller of it you found (timers,
-  push events, expiry, and error handlers too), the events it was checked against, and for each
-  outcome (success, refusal, error, timeout) what the code did or the guard that rules the cell
-  out; `[]` when the diff has none.
-- `boundaries` lists each regex, glob, parser, or validator the diff adds or changes with the
-  inputs tried against it; `[]` when the diff has none.
+- `windows` lists the async windows selected for the changed contract and material risks,
+  their relevant callers, events and outcomes checked, and what the code did or what ruled a
+  case out; `[]` when none was selected. Binding repo proof requirements still apply.
+- `boundaries` lists the patterns, parsers, or validators selected for the changed contract and
+  material risks with the inputs tried; `[]` when none was selected.
 - On a re-review, keep a prior finding's `id` while its rule is broken anywhere, with every
   row updated; a new witness of that rule is a new row, never a new id.
 

package/skills/engineering/e2e-test/SKILL.md

@@ -1,22 +1,22 @@
 ---
 name: e2e-test
-description: "Playwright end-to-end standard: the 3-tier suite (render-health / functional / journey), generated route manifest, and presentation sweep. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
-release-version: 0.44.0
+description: "Playwright end-to-end guidance for affected browser journeys, render health and presentation checks, with route manifests and sweeps for broader audits. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # E2E Testing Standard
 
-The executable browser layer for `ensure-coverage`'s doctrine. ensure-coverage says *what must be proven* (required levels, the ledger, the presentation floor, the golden-path-only CI contract). This skill is *how* browser and journey surfaces get proven. `resolve-issues` implementers author the tests and run the sweep; `better-review` checks them against [reviewing.md](references/reviewing.md); `golden-path` selects the `@golden-path` subset of Tier 3 as the sole per-PR liveness gate.
+The executable browser layer for `ensure-coverage`: that skill determines what needs proof; this skill shows how to obtain browser evidence. For routine feature work, use the existing suite and exercise the affected business journey, relevant render checks, and material errors. Reuse a journey's assertions for each render, functional, or presentation claim they actually check. Do not create a new harness, duplicate tests by tier, regenerate an all-routes manifest, run a whole-app sweep, or add a golden-path gate automatically. Follow existing binding repo requirements and safety rules. Route product policy and broad architecture decisions to their owners.
 
 ## Test tiers
 
 | Tier | Name | What to test | Required when |
 |---|---|---|---|
-| 1 | **Render-health** | Route loads, no crash, heading visible, no console errors (the `presentation:render-health` spine) | Every route not already proven by a Tier 2/3 test that calls `assertRenderHealthy` |
-| 2 | **Functional** | Forms, filters, auth, API responses, error states | Routes with user interaction |
-| 3 | **Journey** | Multi-step flows crossing pages and APIs; the golden paths whose failure means do-not-ship | Core business flows |
+| 1 | **Render-health** | Route loads, no crash, meaningful content visible, no material console errors | Relevant affected renders |
+| 2 | **Functional** | Forms, filters, auth, API responses, error states | Affected behavior needing proof |
+| 3 | **Journey** | Multi-step flows crossing pages and APIs | Affected business journey |
 
-Tier 3 is where the golden paths live. `golden-path` authors nothing new: it selects the curated `@golden-path`-tagged subset and gates it ALIVE/DEAD. A tagged spec holds one journey, named by one `@covers <journey-id>` beside its surface `@covers`.
+These tiers describe kinds of evidence, not three required tests. Existing golden paths may select a curated journey subset; changing that contract belongs to `golden-path` and needs an appropriate request or binding requirement.
 
 ## Directory layout
 
@@ -33,10 +33,10 @@ e2e/
 
 ## Writing tests
 
-1. Every new route needs render-health proof: a Tier 1 test, or a Tier 2/3 test on that route that calls `assertRenderHealthy`. Interactive routes need Tier 2 with success, error, and edge cases. Core flows need a Tier 3 journey; tag the do-not-ship subset `@golden-path`.
-2. One test per page and behavior. Never add a Tier 1 test for a route a Tier 2/3 test already proves, and never repeat an assertion another test on the same page makes.
-3. The manifest is generated, never hand-edited. Regenerate it and put curation in the overlay ([route-manifest.md](references/route-manifest.md)).
-4. Tag every spec `// @covers <surface-id>` and `// @level <level>` so the ledger resolves it. Untagged specs are invisible to the accounting gate.
+1. Extend or run existing tests for the affected journey and relevant render health, including material errors and appropriate success or failure cases. Add focused proof where existing tests leave a meaningful gap.
+2. Reuse assertions where they actually prove the claim; do not duplicate a journey solely to fill separate tiers. Real UX and layout claims need real-browser evidence, and a functional pass alone does not prove contrast.
+3. When an audit or binding repo requirement calls for a manifest, generate it rather than hand-editing it; put curation in the overlay ([route-manifest.md](references/route-manifest.md)).
+4. Follow existing `// @covers <surface-id>` and `// @level <level>` conventions where the repo uses a ledger.
 5. `getByRole` / `getByLabel` / `getByText`, never CSS selectors. Wait for real state, never `waitForTimeout()`.
 6. Auth lives in shared fixtures. Seeded accounts and tenants carry the `e2e-` prefix with a run-scoped suffix ([auth-flows.md](references/authoring/auth-flows.md)).
 7. Journeys drive real APIs. Mock only external third-party boundaries; a first-party `page.route` in a journey grades `Over-mocked`.
@@ -45,9 +45,9 @@ e2e/
 
 Patterns and tier examples: [playwright-patterns.md](references/authoring/playwright-patterns.md). Config and the AGENTS.md snippet: [playwright-config.md](references/authoring/playwright-config.md).
 
-## The two commands every browser change owes
+## Whole-app audit tools
 
-Regenerate the manifest from the inventory:
+Run a whole-app sweep only for an explicit audit, a changed shared shell with a real broad blast radius, or an existing binding repo requirement. When that scope needs a current manifest, regenerate it from the inventory:
 
 ```bash
 node "$SKILL_DIR/scripts/project-route-manifest.mjs" \
@@ -55,7 +55,7 @@ node "$SKILL_DIR/scripts/project-route-manifest.mjs" \
   --overlay e2e/route-manifest.overlay.json --out e2e/route-manifest.json
 ```
 
-Run the presentation sweep over every manifest route against the real render path:
+For a whole-app sweep, run it over every manifest route against the real render path:
 
 ```bash
 E2E_AUTH_BYPASS=1 node "$SKILL_DIR/scripts/presentation-sweep.mjs" \
@@ -65,7 +65,7 @@ E2E_AUTH_BYPASS=1 node "$SKILL_DIR/scripts/presentation-sweep.mjs" \
 
 `SKILL_DIR` is this skill's own directory, the path you read this file from. Never resolve a script against your CWD, and never locate one with `find` over `$HOME`.
 
-The sweep is separate evidence from the functional suite. A green functional run is not presentation proof: a spec that intercepts its own API never exercises the render path that crashes. Instruments, fixtures, mutate-health, and the result shape the ledger reads: [presentation-sweep.md](references/presentation-sweep.md). A route with no in-app link is still reachable by URL; "no way to view it" is never `blocked`.
+A real-browser journey can also prove the render and presentation properties it explicitly checks; functional success alone does not prove contrast or other untested layout properties. A spec intercepting first-party APIs does not prove the real backend render path. Instruments, fixtures, mutate-health, and the result shape: [presentation-sweep.md](references/presentation-sweep.md). A route with no in-app link can still be reached by URL.
 
 ## Verify locally before the queue
 
@@ -77,11 +77,11 @@ Whether you added tests, wrote notes, or reviewed a PR, the first line answers "
 
 ## CI
 
-Curated golden-path smoke is the sole CI gate (`ensure-coverage/references/enforcement/ci-contract.md`). On GitHub Actions, `golden-path init --write` generates the workflow from the repo's contract; on Cloud Build, copy [`assets/ci-gates.cloudbuild.yaml`](assets/ci-gates.cloudbuild.yaml). Verify either with `ci-audit.mjs`. Wiring notes: [ci-integration.md](references/ci-integration.md). Running Playwright in a pinned container on self-hosted runners: [ci-playwright-container.md](references/ci-playwright-container.md).
+Run the repo's existing required checks; routine feature work does not create or change a golden-path gate. When explicitly tasked with CI wiring, see [ci-integration.md](references/ci-integration.md) and [ci-playwright-container.md](references/ci-playwright-container.md).
 
 ## Reviewing
 
-Checklist and comment template: [reviewing.md](references/reviewing.md). Block on: a new route without a manifest entry, an interactive route without Tier 2, a browser-route change with no sweep run, any skipped or guarded test, or an assertion that would pass on a 404 or empty page.
+Checklist and comment template: [reviewing.md](references/reviewing.md). Report missing relevant proof and actual failures; do not block solely because a manifest, sweep, or separate tier is absent unless explicitly agreed or required by the repo. Preserve required checks and do not count a 404 or empty page as a real render.
 
 ## Scripts
 

package/skills/engineering/e2e-test/references/authoring/playwright-config.md

@@ -42,17 +42,17 @@ export default defineConfig({
 
 ## AGENTS.md section
 
-Drop into each repo's AGENTS.md or CLAUDE.md:
+Use this snippet only when explicitly authorized to update a repo's AGENTS.md or CLAUDE.md; preserve existing binding requirements:
 
 ```markdown
 ## E2E Testing
 
 ### Rules
-1. Every new route/endpoint MUST be added to `e2e/route-manifest.json` (the coverage audit will fail otherwise)
-2. Every new route needs at least a Tier 1 render-health test
-3. Interactive routes need Tier 2 functional tests (success + error + edge cases)
-4. Core business flows need Tier 3 journey tests — the golden paths (multi-step, real API); tag the do-not-ship subset `@golden-path`
-5. Directory: `render/`, `functional/`, `journeys/`
+1. Use the existing suite to prove the affected business journey, relevant render health, and material errors.
+2. Reuse journey assertions for the render, functional, and presentation properties they actually check; do not duplicate tests by tier.
+3. Prove UX and layout claims in a real browser; functional success alone does not prove contrast.
+4. Journeys claiming real backend proof use real first-party APIs. Do not add a golden-path gate automatically.
+5. Follow the repo's existing test layout and required checks.
 6. Use `getByRole`/`getByLabel`/`getByText` -- not CSS selectors
 7. No `waitForTimeout()` -- wait for real state
 8. Run route discovery and reachability analysis before E2E coverage audits; do not audit from memory, sampling, or file enumeration alone
@@ -61,13 +61,11 @@ Drop into each repo's AGENTS.md or CLAUDE.md:
 11. Timeouts: 15s per action/assertion (`actionTimeout`/`expect.timeout`); no per-test timeout raises without justification
 
 ### Checks before a PR
-- Run route detection -- a page/endpoint without a manifest entry is a gap
-- Run the presentation sweep -- a route that throws on render is a bug even when a functional spec passes
-- Reviewer will block PRs with uncovered interactive routes without justification
+- Run affected specs and relevant real-browser checks; report failures and unverified claims.
+- Run a whole-app sweep only for an explicit audit, a shared-shell change with a real broad blast radius, or an existing binding repo requirement.
+- Do not require a manifest, separate tier, or sweep solely because a browser route changed.
 
 ### CI
-- Curated golden-path smoke is the sole CI gate
-- Smoke drives the real app with deterministic seeded state and no first-party interception
-- the job passes only on an ALIVE verdict (DEAD, CANNOT-RUN, and EMPTY fail it)
-- Reviewer will block uncovered interactive routes based on the audit evidence, not CI wiring
+- Run existing required CI checks; do not create a new gate for routine feature work.
+- Existing real-backend smoke drives the real app with deterministic seeded state and no first-party interception.
 ```

package/skills/engineering/e2e-test/references/presentation-sweep.md

@@ -4,7 +4,7 @@
 
 A green functional suite can pass while a route throws on render — when the only spec for that route **intercepts its own API** (`page.route('**/api/**')`), it never exercises the real render path that crashes. The presentation sweep catches this: it opens **every manifest route** in a real browser over the real render path (no first-party interception) and asserts the presentation floor **spine first**. It is the runner half of ensure-coverage's presentation axis (that skill *grades* the axis; this skill *runs* it and owns the result shape below).
 
-**It is separate evidence from the functional/journey suite, even though both use Playwright.** A passing functional E2E run is not presentation proof.
+A real-browser journey can prove the presentation properties it actually asserts. A functional pass alone does not prove contrast or other unchecked presentation properties; first-party interception does not prove the real backend render path.
 
 ## Instruments (import into a spec, or use the sweep)
 
@@ -28,9 +28,9 @@ test('/tasks renders without error', async ({ page, baseURL }) => {
 })
 ```
 
-## The sweep (mandatory for browser-route changes)
+## The sweep (scoped whole-app work)
 
-Run the whole-manifest sweep as review evidence, not a per-route afterthought:
+Run a whole-app sweep only for an explicit audit, a changed shared shell with a real broad blast radius, or an existing binding repo requirement. Routine changes use affected journey and render checks instead. When a sweep is in scope:
 ```bash
 E2E_AUTH_BYPASS=1 node <skill-dir>/scripts/presentation-sweep.mjs \
   --manifest e2e/route-manifest.json --base-url http://127.0.0.1:3000 \
@@ -42,9 +42,9 @@ It exits non-zero on any `fail`/`blocked` and writes the per-`(route, level)` re
 
 #### "No in-app way to view it" is not blocked
 
-Reaching the route is your job. The sweep navigates *by URL*, so a route with no nav link or in-app entry point is still fully reachable. `blocked` is reserved for the genuinely un-renderable conditions above; "I had no convenient route to it" is never an excuse to skip the gate or merge without it. Stand up the local build (dev server + disposable DB + seeded/bypass auth) and drive the route's URL directly:
+The sweep navigates *by URL*, so a route with no nav link or in-app entry point may still be reachable. A missing convenient link alone is not evidence that a required check is impossible. When needed, stand up the local build (dev server + disposable DB + seeded/bypass auth) and drive the route's URL directly:
 
-- **Manifest route → `presentation-sweep.mjs`** — the result the ledger and reviewer consume; run it whenever the route is in the manifest.
+- **Whole-app sweep in scope → `presentation-sweep.mjs`** — produces the per-route results the ledger can consume.
 - **Ad-hoc one-route check → `agent-browser` (preferred).** Navigate, screenshot the states that matter (expanded/collapsed/popover), read the console, clean up. The default for "is this one route OK before I merge."
 - When agent-browser doesn't fit: **chrome-devtools MCP** for devtools surfaces (console, network, a perf/Lighthouse trace) alongside the render; **raw Playwright** (`page.goto(url)`) when scripting navigation into an authored spec.
 
@@ -73,7 +73,7 @@ Opt-in, for a surface built from a cited design source. ensure-coverage owns the
 
 ## What the sweep must do, and the result shape the ledger consumes
 
-`coverage-ledger.mjs` is a static analyzer: it proves a qualifying real-browser, non-intercepting, attested test was *authored*. It cannot observe a `pageerror`, an overflow, or a layout shift. The coverage verdict therefore needs two evidence sources: **accounting** (the ledger) and **rendering** (this sweep). Neither is a CI gate; curated golden-path smoke is the sole CI gate.
+`coverage-ledger.mjs` is a static analyzer: it cannot observe a `pageerror`, an overflow, or a layout shift. Use observed real-browser evidence for claims about those properties. A sweep can supply that evidence when in scope; an existing journey can supply it for the properties it actually checks. Follow the repo's required checks.
 
 Given the generated route manifest (the `kind: "route"` surfaces from the surface inventory), the sweep must:
 
@@ -101,4 +101,4 @@ Emit JSON to `docs/tests/_generated/presentation-results.json`:
 
 - `status` is `pass | fail | unverified | blocked`. `fail` and `blocked` exit the sweep non-zero. `unverified` is a ledger warning by default.
 - `evidence` names the concrete observation: the `pageerror` text, the offending selector and overflow px, the unreachable param.
-- The ledger reconciles these against each route's required levels: a `fail` / `blocked` / missing result on a required level is a finding; a `pass` still needs a clean authored test, read and marked `verified: true`, to reach `Covered`.
+- The ledger reconciles results against its configured required levels. Report a `fail`, `blocked`, or missing required result accurately; do not claim a missing sweep alone blocks routine work unless explicitly agreed or required by the repo.

package/skills/engineering/e2e-test/references/reviewing.md

@@ -4,11 +4,11 @@
 
 Checklist:
 
-- [ ] Route discovery and reachability analysis were run before coverage audit
-- [ ] Route manifest regenerated (projection) if routes added/removed; no drift vs the surface inventory
-- [ ] New routes have render-health proof (Tier 1, or a Tier 2/3 test calling `assertRenderHealthy`); no duplicate Tier 1 for a route already proven
-- [ ] Interactive routes have Tier 2 (success + error cases)
-- [ ] Browser-route changes ran the presentation sweep (a separate run); no `fail` results. **A `blocked` result depends on who is running this list.** Producing the work (fixtures yours to supply), `blocked` is a genuine gap — a route the harness cannot render is a route nobody proved renders, so it blocks. *Reviewing* a diff from a read-only sandbox, `blocked` usually means your environment lacks a `DATABASE_URL`, an auth session, or a resolvable param — an inability to verify, which is never evidence of absence. Report the route and the error and take `BLOCKED` for that route's obligation; do not convert it into a finding against the diff
+- [ ] The affected business journey, relevant renders, and material errors have appropriate evidence from the existing suite or focused checks
+- [ ] Reused journey assertions are credited only for what they actually check; functional success alone does not prove contrast or layout
+- [ ] UX and layout claims have real-browser evidence; first-party interception is not real backend proof
+- [ ] A whole-app sweep is scoped to an explicit audit, a shared-shell change with a real broad blast radius, or an existing binding repo requirement; discover and check reachability when conducting an audit
+- [ ] Required checks ran, and actual failures or unverified obligations are reported with their cause. A reviewer's inability to run a check is not evidence that the diff lacks coverage
 - [ ] No `waitForTimeout()` -- use explicit waits
 - [ ] No CSS class assertions -- test user-visible behavior
 - [ ] **No test skipped or disabled.** The PR adds no `test.skip` / `xit` / `describe.skip`, no conditional skip unless CI still runs the test where the condition is false (a platform or optional-dependency skip), no disguised `if (!x) return` guard. A missing precondition is **seeded**; an un-sandboxable/flaky case goes to the **quarantine lane** (non-blocking, graded `Unverified`), never skipped. A `TODO`/issue link does **not** authorize a skip (policy: `ensure-coverage/references/process/test-strategy.md`)
@@ -17,10 +17,9 @@ Checklist:
 - [ ] Auth in shared fixtures, not duplicated
 - [ ] Bugfix PRs have regression test covering the exact failure
 - [ ] Tier 3 journeys use real APIs (no mocking internal endpoints)
-- [ ] Do-not-ship golden journeys (sign in → core action → pay) are tagged `@golden-path` so the golden-path check selects them; a new critical flow with no `@golden-path` tag / `golden-paths.json` entry is a gap
-- [ ] Specs tagged `@covers`/`@level` so the ledger resolves them
+- [ ] Existing golden-path and ledger conventions are followed where required; no new gate is demanded automatically
 
-**Red flags (block PR):** route discovery/reachability not run before audit, route treated as valid only because a file exists, tests assert implementation details, fixed sleeps, new route without manifest entry, copy-pasted auth setup, happy-path-only Tier 2, no presentation sweep run for a browser-route change (a sweep you could not *run* is a `BLOCKED`, not a red flag — the distinction is whether the sweep is missing or your environment is), **any test skipped/disabled/guarded** instead of seeded-or-quarantined, an assertion that passes on a 404/not-found/empty page where a real render is expected, **an authorized lane whose only observed failure mode is a timeout** (it is failing closed before it renders, not asserting).
+**Red flags:** treating a route as rendered only because a file exists, assertions that pass on a 404 or empty page, fixed sleeps, unsupported skips or guards, and an authorized lane that only times out instead of proving its subject rendered. Report material gaps and failures. Do not block solely for an absent manifest, sweep, or separate tier unless explicitly agreed or required by the repo.
 
 **Lead with the verdict, then follow-ups.** Put the verdict at the **top** of the review (and any coverage `notes.md`) — *is this surface covered / ship-ready, or do gaps remain?* — then what the tests prove and deliberately don't, and concrete follow-up action items (owner/level where known) for anything uncovered.
 
@@ -29,9 +28,8 @@ Checklist:
 ### E2E Coverage
 
 **Missing:**
-- Route `/new-page` added but not in the surface inventory / route manifest
-- No Tier 2 test for the date filter (need: valid range, invalid range, empty)
-- `/tasks` has no presentation-sweep result (render unproven)
+- The affected date-filter journey has no evidence for its error state
+- The claimed contrast improvement has no real-browser contrast evidence
 
 **Issues:**
 - `line 42`: Uses `waitForTimeout(3000)` -- replace with `waitForResponse`

package/skills/engineering/e2e-test/references/route-manifest.md

@@ -1,6 +1,6 @@
 # Route Discovery and the Route Manifest
 
-> Read when: a route was added or removed, the manifest is stale, or an audit needs the route inventory before it can grade anything.
+> Read when: an audit, a shared-shell change with a real broad blast radius, or a binding repo requirement needs route discovery or a current manifest. A routine route change does not itself require a whole-app inventory or regeneration.
 
 ## Discover first, never audit from memory
 

package/skills/engineering/engineering/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: engineering
+description: "Project engineering conventions and explicit /engineering init: feature-delivery priorities, focused verification and review, operational boundaries, and tracker routing. Use when setting up AGENTS.md or CONTRIBUTING.md, saving engineering defaults, or before creating an engineering issue, spec, epic, ticket, or sub-issue on GitHub or Linear. Reads existing policy without writing during ordinary work. NOT the issue-to-PR workflow (resolve-issues), release execution (resolve-release), Git delivery (github-flow), or CI setup (github-actions)."
+release-version: 0.45.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Engineering
+
+Keep engineering work focused on the requested business outcome. Read the project's
+existing `AGENTS.md` and `CONTRIBUTING.md` and the relevant domain
+hazards or ADRs. Follow binding local requirements. Do not turn ordinary feature
+work into a setup, audit, framework, or gate project.
+
+## Find the task
+
+| Task | Action |
+| --- | --- |
+| `/engineering init` or an explicit request to register project defaults | [Initialize](#initialize-project-guidance) |
+| Ordinary implementation or review | Read applicable guidance; apply the defaults below without writing files |
+| Create an issue, spec, epic, or sub-issue | [Tracker routing](#tracker-routing); do not initialize as a side effect |
+| Existing guidance conflicts with a proposed default | Preserve it; ask for a decision only if the requested action needs one |
+| Choose additional setup capabilities | [Initialization scope](references/init-scope.md); route to the owning skill |
+
+## Delivery defaults
+
+Prioritize the requested outcome. Supporting code, tests, and infrastructure need
+a direct dependency, a binding requirement, or a demonstrated defect. Reuse existing
+patterns and sufficient proof. Preserve security, tenancy, financial correctness,
+data integrity, and cleanup. Do not invent recovery, compatibility, test layers,
+frameworks, or gates for speculative scenarios. Keep acceptance stable and stop when
+the outcome works and the agreed checks pass. Report unrelated debt without fixing it.
+
+These defaults do not waive project rules, authorize external actions, or require
+extra planning roles. Ordinary implementation choices stay with the implementer.
+
+## Initialize project guidance
+
+An explicit `/engineering init` authorizes the additions described here in the
+selected project. Automatic skill discovery, an issue-routing trigger, installation,
+updates, and quoted examples do not authorize writes. When defaults would help an
+unconfigured project, offer init once and continue; setup is not a feature prerequisite.
+
+1. Read existing project guidance and check for policy conflicts. The script preserves
+   existing sections; it does not interpret or replace the project's decisions.
+2. Set `SKILL_DIR` to this installed skill's directory. Preview:
+
+   ```sh
+   node "$SKILL_DIR/scripts/init.mjs" [--repo-root <project-root>] \
+     [--github-repo <owner/name>] [--linear-project "<name>"]...
+   ```
+
+3. For the explicitly authorized init, run the same command with `--write`. A preview
+   request alone stays read-only. No second approval is needed for the additions
+   already requested; a conflicting policy change needs separate agreement.
+4. Report created, updated, and preserved files and any unresolved project decisions.
+   Do not install dependencies, generate CI, create issues, push, or deploy as part of init.
+
+The default scope is the nearest Git root, or the current directory without a Git
+repository. `--repo-root` explicitly selects a different project. Do not walk parent
+projects or edit global agent files. A GitHub origin or explicit `--github-repo` supplies
+the known issue destination; without one, write neutral routing instructions and
+resolve the destination before any issue creation. Never infer a Linear project.
+
+| File or section | Init owns |
+| --- | --- |
+| `AGENTS.md` | Missing `Feature delivery` section and a pointer to `CONTRIBUTING.md` |
+| `CONTRIBUTING.md` | Missing `Engineering conventions`, `Testing conventions`, and `Issue tracking` sections |
+
+The templates are [feature delivery](references/feature-delivery.md),
+[engineering conventions](references/engineering-conventions.md),
+[testing conventions](../test-quality/references/testing-conventions.md), and
+[tracker conventions](references/tracker-conventions.md). Install `engineering` with
+its required sibling `test-quality`; init reads that skill's canonical template
+without invoking its writer. `test-quality` owns the testing rules and deliberate
+updates; init only adds a missing section. The [skill review](references/init-scope.md)
+explains what is included and what remains opt-in.
+
+Existing sections, including legacy `conventions:tracker` blocks written by
+`contributing`, are preserved byte-for-byte. Repeated init is not a refresh and
+leaves manual edits unchanged. No force/update mode is implied. If policy needs to
+change, agree the specific change rather than rerunning setup over it.
+
+Every target is checked before writing. Invalid targets, unreadable files, malformed
+owned markers, dangling links, and links outside the selected project refuse setup.
+Valid in-project symlinks are preserved. Keep distinct agent-instruction and
+contributor-guide files. Init does not read, create, or update `CLAUDE.md`.
+Report a write error honestly; do not claim setup completed when it did not.
+
+## Tracker routing
+
+Read the destination from project guidance first, then the GitHub resources linked
+from a source Linear project; ask if unresolved. An explicit user destination wins.
+
+| Work | Default tracker |
+| --- | --- |
+| Product goals, business requirements, consulting work, delivery summaries | Linear where used by the project |
+| Engineering specs, implementation epics, technical tasks, engineering bugs | GitHub |
+
+Before creating work:
+
+1. Classify the work, not the conversation it came from. Engineering implementation
+   stays in GitHub even when the request started in Linear.
+2. Resolve the actual repository. Do not guess among multiple repos or fall back to
+   Linear because the GitHub destination is missing.
+3. Search the destination for duplicates and reuse a match.
+4. Link the GitHub epic to its Linear source requirement once. Do not create
+   implementation children in Linear or mirror every ticket there.
+5. Report engineering delivery in Linear as a linked summary; the requester owns
+   product acceptance.
+
+The retained tracker-only helper supports explicit requests to persist or update
+that section:
+
+```sh
+node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <project-root> \
+  [--github-repo <owner/name>] [--linear-project "<name>"]... [--if-missing] [--write]
+```
+
+It previews without `--write`; `--if-missing` preserves an existing tracker block.
+Without that flag, an authorized tracker refresh replaces only its managed block.
+It retains the existing shared convention-writer behavior; use `init.mjs` for
+project setup with the all-target validation and preservation rules above. Ordinary
+issue routing never runs either writer automatically. The old `contributing` name
+is archived, not a second active policy owner.

package/skills/engineering/engineering/references/engineering-conventions.md

@@ -0,0 +1,32 @@
+## Engineering conventions
+
+### Deliver the requested outcome
+
+Build the smallest complete end-to-end change using existing patterns and tools.
+Supporting code, tests, and infrastructure need a direct dependency, a binding
+requirement, or a concrete defect. Do not invent fallback values, retries,
+compatibility modes, or abstractions for hypothetical future needs. Preserve
+necessary input validation and report unexpected failures through existing boundaries.
+
+### Verify proportionately
+
+Reuse tests and checks that already prove the changed behavior. Add focused proof
+for material risks at the lowest level that observes the real outcome. Mocks do
+not prove the persistence, authorization, or transaction behavior they replace.
+Do not duplicate proof across layers, pin source text instead of behavior, or
+start a whole-app audit for a local change. Run the project's required checks;
+report failed or unavailable checks honestly, without weakening them to get green.
+
+### Review and finish
+
+Block delivery for a concrete supported failure, an explicit unmet requirement,
+or missing agreed required proof, not speculative hardening or optional tests.
+Keep acceptance criteria stable; new scope needs agreement. Stop when the outcome
+works and the agreed checks pass. Report unrelated debt without fixing it.
+
+### Respect operational boundaries
+
+Preserve authentication, tenant isolation, financial correctness, data integrity,
+and cleanup. Follow this project's existing commit, PR, queue, and release policy.
+Do not invent a delivery flow, introduce new CI gates, or treat initialization as
+authorization to push, deploy, migrate shared data, change permissions, or release.