@1aboveio/skills 1.0.9 → 1.0.11

package/skills/engineering/engineering/references/feature-delivery.md

@@ -0,0 +1,8 @@
+## Feature delivery
+
+Prioritize the requested business outcome. Supporting engineering work must
+directly enable it, satisfy a binding requirement, or fix a concrete defect.
+Do not expand feature work into hardening, frameworks, coverage campaigns,
+or new gates without approval. Preserve required safety and correctness.
+Reuse sufficient proof and stop when the outcome and agreed checks pass.
+Report unrelated debt without implementing it.

package/skills/engineering/engineering/references/init-scope.md

@@ -0,0 +1,37 @@
+# What initialization includes
+
+The default is durable project guidance, not an orchestration or infrastructure setup.
+This review covers every active first-party skill in the Engineering package and
+the related delivery, CI, and merge-queue convention owners. Archived skills are
+not initialization sources; pinned external skills keep their upstream ownership.
+
+| Skill | Include in guidance | Keep as a separate action |
+| --- | --- | --- |
+| engineering (formerly contributing) | Feature priorities, guidance lookup, tracker routing | Tracker refresh or project-policy changes |
+| resolve-issues | Agreed outcome, bounded supporting work, explicit stopping point | Issue planning, workers, PRs, scheduling |
+| rush-issues | Same delivery principles as resolve-issues | Shortcut workflow invocation |
+| ensure-coverage | Smallest sufficient proof, stable acceptance, required checks preserved | Ledger adoption, broad audits, new gates |
+| test-quality | Canonical seven-principle `Testing conventions` section, added only when missing | Refreshing existing testing policy or suite cleanup |
+| e2e-test | Focus on affected journeys; distinguish real browser/backend proof | Harness, manifest, whole-app sweep |
+| better-review | Concrete blockers, optional improvements do not enlarge acceptance | Review passes, JSON records, re-review workflow |
+| golden-path | People choose release-blocking journeys | Path selection, contract, workflow and gate generation |
+| resolve-release | Respect existing release ownership and permissions | Flow selection, tags, deployment, promotion |
+| rush-release | Same release boundaries as resolve-release | Shortcut release invocation |
+| engineering-runtime | No user convention; support-only | Runtime installation or configuration |
+| harness-runtime | No user convention; support-only | Harness setup or configuration |
+| github-flow | Follow existing delivery policy; do not infer authorization | Declaring or changing Delivery and CI sections |
+| github-actions | Preserve existing required checks | Workflow generation, runner/caching/security policy |
+| mergify | Honor an existing queue policy | Queue installation, configuration, or enqueueing |
+| data-catalog | No general default; warehouse-specific rules need explicit setup | Data catalog conventions, catalog generation and CI |
+
+Do not invoke the separate actions as a side effect of `init`. In particular, do
+not call other skills' convention writers: they own their sections and may need
+additional decisions. Init reads `test-quality`'s canonical template directly;
+the testing owner and `conventions:testing` section identity remain unchanged.
+Existing project sections, including old testing and tracker blocks, stay unchanged.
+Delivery, CI, and Data Catalog conventions require separate explicit setup with
+their owning skills. Setup may point to these capabilities without requiring them.
+
+Stack-specific tools, commands, cloud projects, release branches, required gates,
+and golden paths are project facts, not defaults to manufacture. Read established
+guidance; ask for missing decisions only when a requested action needs them.

package/skills/engineering/engineering/scripts/init.mjs

@@ -0,0 +1,160 @@
+// Explicit project setup. Preview by default; preserve existing policy on every run.
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const reference = name => fs.readFileSync(fileURLToPath(new URL(`../references/${name}.md`, import.meta.url)), 'utf8').trim()
+const usage = 'node init.mjs [--repo-root <dir>] [--github-repo <owner/name>] [--linear-project <name>]... [--write]'
+
+function parseArgs(argv) {
+  const options = { write: false, linearProjects: [] }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (arg === '--write') options.write = true
+    else if (arg === '--help') options.help = true
+    else if (['--repo-root', '--github-repo', '--linear-project'].includes(arg)) {
+      const value = argv[++i]
+      if (!value || value.startsWith('--') || /[\r\n]/.test(value)) throw new Error(`missing or invalid value for ${arg}`)
+      if (arg === '--repo-root') options.repoRoot = path.resolve(value)
+      else if (arg === '--github-repo') {
+        if (!/^[\w.-]+\/[\w.-]+$/.test(value)) throw new Error('invalid GitHub repository; use owner/name')
+        options.githubRepo = value
+      } else options.linearProjects.push(value)
+    } else throw new Error(`unknown argument ${arg}`)
+  }
+  return options
+}
+
+function gitOutput(root, args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' })
+  return result.status === 0 ? result.stdout.trim() : null
+}
+
+function githubRepo(root) {
+  const remote = gitOutput(root, ['remote', 'get-url', 'origin'])
+  return remote?.match(/^(?:git@github\.com:|https:\/\/github\.com\/|ssh:\/\/git@github\.com\/)([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/)?.[1] ?? null
+}
+
+function inspectTarget(root, name) {
+  const file = path.join(root, name)
+  const stat = fs.lstatSync(file, { throwIfNoEntry: false })
+  if (!stat) return { name, file, target: file, current: null }
+  const target = fs.realpathSync(file)
+  const relative = path.relative(root, target)
+  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`${name} resolves outside the selected project`)
+  }
+  if (!fs.statSync(target).isFile()) throw new Error(`${name} is not a regular file`)
+  return { name, file, target, current: new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(fs.readFileSync(target)) }
+}
+
+function append(current, body) {
+  const separator = current.endsWith('\n\n') ? '' : current.endsWith('\n') ? '\n' : '\n\n'
+  return `${current}${separator}${body.trim()}\n`
+}
+
+function preserveOrAdd(current, title, id, body) {
+  const start = `<!-- conventions:${id}:start -->`
+  const end = `<!-- conventions:${id}:end -->`
+  const starts = current.split(start).length - 1
+  const ends = current.split(end).length - 1
+  if (starts !== ends || starts > 1 || (starts && current.indexOf(start) > current.indexOf(end))) {
+    throw new Error(`malformed ${title} section markers; preserve and repair existing guidance first`)
+  }
+  if (starts || current.split(/\r?\n/).some(line => line.trim() === `## ${title}`)) return current
+  return append(current, `${start}\n${body}\n${end}`)
+}
+
+function linkFrom(from, to) {
+  return path.relative(path.dirname(from.target), to.file).split(path.sep).join('/')
+}
+
+function hasLoader(current, from, to) {
+  const links = /\[[^\]\r\n]*\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^"'\r\n]*["'])?\s*\)/g
+  for (const match of current.matchAll(links)) {
+    const href = (match[1] ?? match[2]).split(/[?#]/)[0]
+    if (!href || /^[a-z][a-z\d+.-]*:|^\/\//i.test(href)) continue
+    let target
+    try {
+      target = path.resolve(path.dirname(from.target), decodeURIComponent(href))
+    } catch {
+      continue
+    }
+    if (fs.existsSync(target)) target = fs.realpathSync(target)
+    if (target === to.target) return true
+  }
+  return false
+}
+
+function trackerBody(repo, projects) {
+  if (repo) {
+    return reference('tracker-conventions')
+      .replaceAll('{{githubRepo}}', repo)
+      .replaceAll('{{linearProjects}}', projects.length ? ` (projects: ${projects.join(', ')})` : '')
+  }
+  return [
+    '## Issue tracking',
+    '',
+    'Follow existing project tracker decisions; an explicit user destination wins.',
+    'Use GitHub for engineering implementation and Linear for product requirements',
+    'and delivery summaries where the project uses those trackers. Before creating',
+    'an issue, resolve the actual repository from project guidance or the source',
+    'requirement; ask if it is unknown. Do not invent a repository or create trackers.',
+    'Search for duplicates and link implementation work back to its requirement.',
+    'Do not create implementation children in Linear.',
+    ...(projects.length ? ['', `Known Linear projects: ${projects.join(', ')}.`] : []),
+  ].join('\n')
+}
+
+function planInitialization(root, options) {
+  const [agents, contributing] = ['AGENTS.md', 'CONTRIBUTING.md']
+    .map(name => inspectTarget(root, name))
+  if (agents.target === contributing.target) {
+    throw new Error('agent instructions and CONTRIBUTING.md must use distinct files')
+  }
+
+  let agentText = preserveOrAdd(agents.current ?? '# Agent instructions\n', 'Feature delivery',
+    'feature-delivery', reference('feature-delivery'))
+  if (!hasLoader(agentText, agents, contributing)) {
+    agentText = append(agentText, `## Contributing\n\nFollow [CONTRIBUTING.md](${linkFrom(agents, contributing)}) for this project's engineering conventions and existing delivery requirements.`)
+  }
+
+  let contributingText = preserveOrAdd(contributing.current ?? '# Contributing\n', 'Engineering conventions',
+    'engineering', reference('engineering-conventions'))
+  const testing = fs.readFileSync(new URL('../../test-quality/references/testing-conventions.md', import.meta.url), 'utf8').trim()
+  contributingText = preserveOrAdd(contributingText, 'Testing conventions', 'testing', testing)
+  contributingText = preserveOrAdd(contributingText, 'Issue tracking', 'tracker',
+    trackerBody(options.githubRepo ?? githubRepo(root), options.linearProjects))
+
+  return [
+    { ...agents, next: agentText },
+    { ...contributing, next: contributingText },
+  ]
+}
+
+function main(argv) {
+  const options = parseArgs(argv)
+  if (options.help) {
+    console.log(usage)
+    return
+  }
+  const selected = options.repoRoot ?? gitOutput(process.cwd(), ['rev-parse', '--show-toplevel']) ?? process.cwd()
+  const root = fs.realpathSync(selected)
+  if (!fs.statSync(root).isDirectory()) throw new Error('project root is not a directory')
+  const plan = planInitialization(root, options)
+  console.log(`engineering init: ${options.write ? 'write' : 'preview only'} (${root})`)
+  for (const entry of plan) {
+    const action = entry.current === entry.next ? 'unchanged' : entry.current === null ? 'create' : 'update'
+    if (options.write && action !== 'unchanged') fs.writeFileSync(entry.target, entry.next)
+    console.log(`  ${entry.name}: ${!options.write && action !== 'unchanged' ? 'would ' : ''}${action}`)
+  }
+  console.log('Existing sections are preserved; initialization does not refresh project policy or authorize delivery actions.')
+}
+
+try {
+  main(process.argv.slice(2))
+} catch (error) {
+  console.error(`engineering init: ${error.message}`)
+  process.exitCode = 2
+}

package/skills/engineering/{contributing → engineering}/scripts/persist-conventions.mjs

@@ -77,7 +77,7 @@ function main(argv, { log = console.log } = {}) {
       return 0
     }
   }
-  const section = { id: ID, owner: 'contributing', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
+  const section = { id: ID, owner: 'engineering', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
   return runCli(rest, section, { log })
 }
 

package/skills/engineering/engineering-runtime/SKILL.md

@@ -3,7 +3,7 @@ name: engineering-runtime
 description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
 disable-model-invocation: true
 user-invocable: false
-release-version: 0.44.0
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Engineering Runtime

package/skills/engineering/engineering-runtime/coherence/workflow.json

@@ -11,7 +11,7 @@
     "golden-path",
     "test-quality",
     "better-review",
-    "contributing",
+    "engineering",
     "engineering-runtime"
   ],
   "dependencies": [
@@ -369,7 +369,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ae8ace5c97889e14e669829d72a92bd90d593ba1099c4bd690c98eca8b9c94e3",
+      "contentDigest": "8ab89f526fd30be9a81c8dc602d797e7aa8d2f09c63da0b56d8d214966e7e1fc",
       "digestExcludes": []
     },
     {
@@ -382,7 +382,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "ddf8e11e23f667cdc677c9d70edb6ed59da53b5a0b82af29f6be36eda35861c2",
+      "contentDigest": "386ab76e0a90f031da690ca27ee5066684d895290ae0c97faabf6aaad94cd495",
       "digestExcludes": []
     },
     {
@@ -395,7 +395,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "0e3c87b01b5c337a7628ae5ba5c78a3b208ab404b8d848e4d8299f221224726d",
+      "contentDigest": "0399fc78af9e7823ace55e04aa867b30b12c738f2a47e28395184512525861bf",
       "digestExcludes": []
     },
     {
@@ -408,7 +408,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "de98656af030369ea229112e90f441626863dcca5e21f2f358e26041d0624f3e",
+      "contentDigest": "2bc51a5c6ed89007075d51f174c7b76d0a743b61f0d299c2067487679c86dd3f",
       "digestExcludes": []
     },
     {
@@ -421,7 +421,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "c4f55e7aed013006d00fde40504db87c32c48ca8b04ef4aeacf9c7fe31995fed",
+      "contentDigest": "c3cd951d823c6ce4f2b9b229892e450ad285e27cda157c5eead0d8ddc3d550f5",
       "digestExcludes": []
     },
     {
@@ -434,7 +434,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "7ec336f6920ec1195fbe08b40234ac72f8213a3b94f575e2c463108b36884a25",
+      "contentDigest": "639a25b40d67942c5355abee9d791b02784bedc50fa1f5fb8b4d90125f0b95e7",
       "digestExcludes": []
     },
     {
@@ -447,7 +447,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "845c78252f5308aa71b8eaabc80718c25a772d016d5d74eb888737cd7ffbe664",
+      "contentDigest": "c595e281773af00b485dcb7d18e762f487b85761db42afa8287015581acdd8b5",
       "digestExcludes": []
     },
     {
@@ -460,7 +460,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "0c9e35d5014ebd7b4512aeb7705cd39977252ccaa639821fa87f8f463364b613",
+      "contentDigest": "ec21e8eb116ccf6b3c1e798f4039fc2fa05558e63cae157e0bcb75ea81627d68",
       "digestExcludes": []
     },
     {
@@ -473,7 +473,7 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "1c5c3dd92653706d7ca78926f10dbf266e4be4a807e6759ea6e8560b3be72f24",
+      "contentDigest": "d973f6bb977f4cba06e26afa42a54bbaa90d29001086c87a83d84f335df590d4",
       "digestExcludes": []
     },
     {
@@ -486,20 +486,20 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d4f589fdb746755388a47eef8d34670a631584fac2bd32af1550da741434b4d6",
+      "contentDigest": "43d2be290e65e536f0b9ff21087cce81c337158948edbdf901c609d3e73b9b0b",
       "digestExcludes": []
     },
     {
-      "installName": "contributing",
+      "installName": "engineering",
       "ownership": "owned",
-      "sourcePath": "skills/engineering/contributing",
+      "sourcePath": "skills/engineering/engineering",
       "expectedSource": {
         "id": "first-party",
         "type": "first-party",
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "d8b6513b1259b3b91f81c4ac9e9ebe66c2c3735534326ee793b99dc305dc3897",
+      "contentDigest": "73163c04711d6901162bd3cdb3a847db2845e8e51dbd53169ad13e7d2817f45c",
       "digestExcludes": []
     },
     {
@@ -512,13 +512,13 @@
         "repository": "1aboveio/ai",
         "revision": "main"
       },
-      "contentDigest": "bf49dc85c84e81e6561b6682003709bb792f4309a295cddad2c5e97e5e85f5b1",
+      "contentDigest": "9086b011f69d48e264c00241c6c1864e04678f791f575625cff2e788a2b58163",
       "digestExcludes": [
         "coherence/workflow.json"
       ]
     }
   ],
-  "releaseIdentity": "a7f5ec670bb7b0f8dcfb585c5de1d5cfd0bd55799d72e994034674c7c84f5c40",
+  "releaseIdentity": "986e36012356e16fd54d77f0844860cd5ed9c4cac6f18ef1d3d540a3697dcfdf",
   "lifecycleAuthority": "native-skills-cli",
   "repairRecipe": {
     "id": "engineering-workflow-dependency-first",
@@ -589,17 +589,17 @@
           "golden-path",
           "test-quality",
           "better-review",
-          "contributing",
+          "engineering",
           "engineering-runtime"
         ],
         "commands": [
           {
             "transport": "https",
-            "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
+            "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
           },
           {
             "transport": "ssh",
-            "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
+            "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
           }
         ],
         "onFailure": {

package/skills/engineering/engineering-runtime/scripts/workflow-policy.mjs

@@ -16,7 +16,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
   'golden-path',
   'test-quality',
   'better-review',
-  'contributing',
+  'engineering',
   'engineering-runtime',
 ]);
 

package/skills/engineering/ensure-coverage/SKILL.md

@@ -2,128 +2,41 @@
 name: ensure-coverage
 description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
 disable-model-invocation: true
-release-version: 0.44.0
+release-version: 0.45.0
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # Ensure Coverage
 
-Define **what must be proven** before a change is ready. This skill states obligations and grades evidence; it does not run CI, wire gates, author tests, or issue merge verdicts.
+Define what must be proven for the agreed business outcome and material risks. This skill scopes criteria and grades evidence; it does not implement tests, wire gates, or issue a merge verdict.
 
-- **Create mode** — turn an ADR, PRD, spec, issue, or bug brief into `/docs/tests/YYYY-MM-DD-<slug>-criteria.md` ([template](references/process/output-template.md)).
-- **Audit mode** — grade existing code and tests against those criteria into `/docs/tests/YYYY-MM-DD-<slug>-audit.md` ([steps](references/process/audit-mode.md)).
+- **Create mode:** agree observable criteria and suitable proof before implementation. Record them in the issue or conversation; create a criteria document only when requested or required by the repository.
+- **Audit mode:** assess evidence against the agreed scope. A feature audit stays scoped to the feature; a whole-repo census is appropriate only for an explicitly requested broad audit. Use the [audit guidance](references/process/audit-mode.md) and [optional output template](references/process/output-template.md).
 
-No source document? Derive candidate ACs from the issue, repro steps, sibling flows, or the public surface. Mark inferred behavior `Assumption` and undecided product questions `BLOCKED`. Never invent product semantics.
+Read the relevant source and governing project guidance. When product behavior or authorization is unclear and blocks the task, ask the owner; do not invent semantics or add planning handoffs for ordinary implementation choices. Keep agreed criteria stable during implementation and proof. A newly discovered concrete defect may need a fix; speculative robustness ideas and test preferences are follow-ups, not new acceptance conditions. Escalate a proposed scope change for agreement.
 
-## Stance: it ships broken until proven otherwise
+## Scope and proof
 
-Default to "not ready" and make the code earn the verdict. The one question: **if this launched now, how likely is a real user to hit a bug in the first week?**
+- Choose the smallest sufficient proof for the outcome and material risks; reuse existing tests and required CI results when they prove the behavior. Do not automatically require multiple test layers, a ledger, a criteria document, a presentation campaign, or reconciliation of every ADR.
+- Existing required repository checks and adopted coverage floors remain binding unless an approved change alters them. Authentication, money, tenancy, and data-integrity protections remain binding. Read applicable ADRs and project policy for the touched work, not every ADR in the repository.
+- Consider breadth, depth, and presentation where relevant: what behavior is in scope, whether evidence actually exercises it, and whether a user can perceive and use a changed interface. Do not turn every axis or hypothetical state into a separate blocking obligation.
+- The [surface baseline](references/breadth/surface-baseline.md) is guidance for selecting proof, not a universal new floor. The bundled ledger and presentation tools implement stricter mechanical rules; use them only when requested or already required, and report their actual results without claiming their defaults are new policy.
+- Avoid tests that bypass the behavior they claim to prove, especially for security or durable state. Select boundaries and test levels for the risk, following applicable repo rules ([mock policy](references/depth/mock-policy.md), [strategy](references/process/test-strategy.md)). A relevant existing test can suffice; characterization and fails-first runs are useful when warranted, not automatic requirements ([characterization](references/depth/characterization.md)).
+- Do not weaken or disable tests merely to get green. Report a required check that cannot run or fails; do not claim it passed.
+- Do not recommend or wire new CI gates unless asked. Existing required checks still apply ([CI contract](references/enforcement/ci-contract.md)). Integrated release campaigns run at their assigned gate, not automatically for each feature.
 
-- A test you have not read is not coverage. State what each passing test exercises and what it silently skips.
-- Walk what a user does first — open the page, fill the form, submit, hit the error path — and name the test that proves each step.
-- Name the concrete failure ("username dropped, submit returns 400"), not "coverage is partial."
-- End with an explicit ship / no-ship call and the counts that drive it. Never round up to `Covered` to be agreeable.
+## Grade honestly
 
-## Three axes
+Inspect the relevant test and its assertions before claiming it proves a behavior. A passing execution proves it ran, not that it covered every claim. Use [grading](references/depth/grading.md): `Covered`, `Partial`, `Missing`, `Wrong Level`, `Over-mocked`, `Unverified`, `Excluded`, or `BLOCKED`. Describe what the evidence proves and what remains unverified; never promote a hypothetical state to a blocker merely because it lacks a test. Missing agreed proof, a concrete material defect, or a failed required check can block; distinguish those from follow-ups. Report unavailable evidence or unresolved decisions without a false success.
 
-Each axis is blind to the others' failure; a coverage claim holds only when all three pass.
+## Workflow and output
 
-- **Breadth** (requirement-inward): did we enumerate everything that must be proven? Catches surfaces with no test at all. Output is a **complete surface census**, never a top-N list.
-- **Depth** (test-outward): does each test prove the behavior against real state? Catches false green: over-mocking, proxy wiring, shallow assertions, wrong level.
-- **Presentation** (render-outward): can a human *see and act on* the rendered page? Catches the invisible control, the overlapping layout, the route nothing links to.
+1. Identify the agreed outcome, touched behavior, material risks, required repo checks, and applicable guidance. Resolve only decisions needed to proceed.
+2. Agree observable acceptance criteria and sufficient proof before implementation. Note existing proof and select focused additions only where needed.
+3. For an audit, inspect relevant tests and results, grade the agreed scope, and report concrete gaps, blockers, and non-blocking follow-ups. Do not expand criteria after the fact. An explicitly requested broad audit may use [surface discovery](references/breadth/surface-discovery.md) and the [coverage ledger](references/breadth/coverage-ledger.md); state any limits on its completeness.
+4. Record what was verified, what was not, and why. Use the repository's existing format or a concise response; no new document is required by default.
 
-## The obligations
-
-**Every surface owes a floor the moment it exists.** A requirement doc is not a precondition. The floor keys off the surface's kind and class, computed mechanically; humans may raise it or exclude through a gated path, never lower it. A reachable mutation route can never be excluded. Full table, taxonomy keys, exclusion gate: [surface-baseline](references/breadth/surface-baseline.md).
-
-| kind | class | owes | the test must show |
-|---|---|---|---|
-| route | read / detail | browser-journey | real rendered data, no first-party mock |
-| route | mutation | browser-journey | fill the real form → backend accepts → durable state changes |
-| route | +sensitive | + api | + auth / tenant isolation |
-| api | read | api | status, shape, auth |
-| api | mutation | api + integration | durable state changed |
-| api | +sensitive | + auth | mandatory auth / tenant isolation |
-| table / event / job | — | none (transitive) | dead-surface warning if nothing reaches it |
-
-**Every browser route also owes the presentation floor**, proven only against a real rendered page at `[375, 1280]`: `render-health` (no page error, console error, error boundary, or first-party 5xx, held *through* interactions), `spatial` (no overflow or overlap), `perceivability` (visible, contrast-passing controls; absent things are absent), `reachability` (navigable from an entry point, focus visible, ≥44px targets), `temporal` (no first-party layout shift). A functional journey satisfies none of these; a DOM-only assertion is `Over-mocked`. A unit that cites a design source also owes `fidelity`: expected values read off the source, rendered side by side ([axis](references/presentation/axis.md)).
-
-**Real internals, faked externals, nothing in between.** Substitute only at a boundary you do not own (third-party APIs, providers, clock, randomness). Never mock-only: DB transactions, idempotency, concurrency, events/outbox/retry, auth and tenant isolation, schema compatibility, orchestrator recovery. A journey that intercepts first-party traffic proves proxy wiring, not behavior. Over-mocked is worse than untested: fix it or delete it ([policy](references/depth/mock-policy.md)).
-
-**Prove the test would fail.** Modifying existing behavior owes a characterization test that passes on the pre-change tree. A bug fix owes a test red before the fix. A feature test counts only if it would go red were the behavior removed ([characterization](references/depth/characterization.md)).
-
-**No test is skipped, disabled, guarded into a no-op, or weakened to get green.** Missing state is seeded. Un-sandboxable flake goes to a quarantine lane that still runs and reports. Obsolete tests are deleted ([strategy](references/process/test-strategy.md)).
-
-**Every accepted ADR with runtime behavior owns a criteria doc and a coverage file.** An ADR that changes behavior with no proof attached is the un-spec'd route's mirror image: stated intent nobody checked. An ADR with no runtime behavior says so in its text; a known gap names a tracked issue. Mechanized by the ledger's acceptance gate ([ledger](references/breadth/coverage-ledger.md)).
-
-**Every AC maps to a named test at the required level.** Read the test to judge what it proves. A green run of it (exit 0) is the only execution proof needed: do not collect logs, screenshots, traces, or read-backs on top. Prior docs and PR summaries are leads, never proof.
-
-**Assign each obligation to its gate.** Coding acceptance is proven per change, by the tests at the required level, and stops once they pass. Integrated release acceptance (a device or system campaign, all-ABI or signed builds, cross-feature journeys) runs once at the release or campaign gate the spec or repository assigns it. A change's verdict never depends on that campaign and never claims it passed; record it once, as pending, in its owning issue. Define the criteria before execution; never expand them or add evidence obligations while proving them.
-
-**Gates are added by humans only.** Do not recommend, require, wire, or audit for CI gates unless the user explicitly asks. A repo with no coverage gates in CI is not a finding. The gate menu ([ci-contract](references/enforcement/ci-contract.md)) and `ci-audit.mjs` are opt-in tools for when the user asks for gates.
-
-**CI has one supported gate: curated golden-path smoke.** The ledger, inventory freshness, presentation sweep, broad E2E suite, test lint, over-mock scan, design parity, and quarantine expiry are audit and review evidence, not CI gates. When the user asks about CI coverage, propose or audit only the real-app golden-path smoke contract ([ci-contract](references/enforcement/ci-contract.md)); `ci-audit.mjs` checks only that smoke wiring.
-
-## Classifications
-
-Full definitions: [grading](references/depth/grading.md). Whether a single test is any good is `test-quality`'s call; how its labels become these grades, and which smells are lint rules versus reviewer leads: [test-smells](references/depth/test-smells.md). A self-declared level is a claim to refute, never a pass.
-
-- **`Covered`** — inspected test proves the behavior at the required level, acceptable mocks. The ledger shows it once the test is marked read (`verified: true`).
-- **`Partial`** — some behavior tested; edge cases, failures, permissions, state, or evidence incomplete.
-- **`Missing`** — no meaningful test maps to the obligation.
-- **`Wrong Level`** — a test exists but is too shallow for the risk.
-- **`Over-mocked`** — mocks bypass the behavior under test.
-- **`Unverified`** — satisfied statically; nobody has marked the test read yet. A warning, not a block, unless the user turns on `unverifiedBlocks`. No evidence is required unless the user asks for it.
-- **`Excluded`** — human-declared out of scope with category and reason, permitted by the gate, visible in the census.
-- **`BLOCKED`** — source, code, tests, environment, or a product decision is unavailable.
-
-## Workflow
-
-1. **Understand the source.** Read the accepted ADRs (`docs/adr`, status accepted) that govern the touched surfaces; they are a requirement source, not background. Pick the output path; list observable behavior; mark assumptions and blockers.
-2. **Model correctness.** Number the ACs, name the critical journeys, assign each a required level ([levels](references/process/test-strategy.md)).
-3. **Plan coverage.** Test matrix, mock policy, E2E needs.
-4. **Grade all three axes.** Enumerate every surface ([discovery protocol](references/breadth/surface-discovery.md); the adapter's output shape is the [inventory contract](references/breadth/inventory-contract.md)), grade each test by reading it, confirm each browser route's presentation floor. Reconcile every accepted ADR against the census: one with runtime behavior and no coverage file is a finding.
-5. **Validate and decide.** Reject implementation-shaped, over-mocked, skipped, or incomplete coverage. Verdict at the top.
-
-## Deliverable
-
-Verdict first, then the evidence that justifies it ([full template](references/process/output-template.md); worked examples: [refund flow](references/examples/refund-flow.md), [ledger](references/examples/coverage-ledger.md)):
-
-```markdown
-## Verdict: Ship / No-ship — <one-sentence reason with the driving counts>
-## Source · Scope · Assumptions · Blockers · Design source (or `none`)
-## Acceptance Criteria (numbered, observable, independently testable)
-## Critical Journeys (actor, start state, trigger, end state, side effects)
-## Test Matrix (scenario · AC · level · mock policy · setup · assertions · proving test)
-## Surface Census (audit) — one row per surface, status, proving test or —
-## Gaps and follow-ups (each with level, setup, assertions)
-## Blocking Decisions (product choices that change the verdict)
-```
-
-## Common wrong answers
-
-- Green CI is not coverage. Read the test.
-- An API test under a page does not prove the page.
-- "Every ADR covered" is not "every surface covered." And an accepted ADR with no coverage file is a gap, not a pass.
-- A write form covered by a validator or schema test is not covered. Only a rendered-form submission proves the form emits what the backend accepts.
-- Excluding a surface is not fixing it. Exclusion is gated and visible.
-- "The script isn't in the audited repo" is not `BLOCKED`. The scripts live in this skill; run them against the repo.
-- A top-3 gap list is not an audit. Emit the census.
-- "Out of scope" excludes behaviors, never the axis the unit is about.
-
-## Mechanization
-
-The decidable parts of these obligations are decided by scripts, not prose. Every script lives under **this skill's directory** (the path you read this file from). Set `SKILL_DIR` to it and run `node "$SKILL_DIR/scripts/<name>.mjs"`. Never resolve a script against your CWD, and never locate one with `find` over `$HOME`; if `SKILL_DIR` is unknown, stop and ask. Usage and flags: [scripts/README.md](scripts/README.md).
-
-| script | decides |
-|---|---|
-| `coverage-ledger.mjs` | breadth accounting: every surface's floor owned and proven; grades depth and presentation from `@covers`/`@level`; with `requirementGlobs`, every accepted ADR or PRD owns a coverage file with criteria or a tracked gap |
-| `lint-tests.mjs` | added skips, fixed timeouts, empty tests, swallowed assertions, and mocks of first-party seams (zero-tolerance) |
-| `design-parity.mjs` | the built page matches the cited design source |
-| `check-quarantine-expiry.mjs` | a dated quarantine exit re-blocks when it expires |
-| `ci-audit.mjs` | CI wires curated golden-path smoke as a blocking check |
-
-In audit mode, always run the over-mock scan whole-tree and count every hit in the verdict.
+The scripts in this skill are optional tools unless the repo already requires them. Set `SKILL_DIR` to this skill's directory and see [scripts/README.md](scripts/README.md) for usage. Their fixed checks and outputs can be broader or stricter than the agreed feature scope; do not silently change or bypass an adopted gate. Escalate conflicts rather than presenting tool defaults as policy.
 
 ## Downstream
 
-This skill defines what must be proven. `test-quality` judges whether each test is any good (one bar, one skip rule, shared with this skill). `e2e-test` authors browser tests and runs the presentation sweep as review evidence. `golden-path` checks the do-not-ship subset of the critical journeys against a running app and is the sole CI gate ([ci-contract](references/enforcement/ci-contract.md), verified by `ci-audit.mjs`). `resolve-issues` delivers and reviews through `better-review`. Some rules (no skips, fake only externals) are deliberately repeated in `e2e-test` and `golden-path` so each works on its own; this skill is the source when they differ.
+`test-quality` judges individual tests; `e2e-test` authors browser tests; `golden-path` owns curated release-critical journeys; `resolve-issues` delivers and `better-review` provides independent review. Other skills and existing repository policy may still carry stricter requirements: preserve them and surface conflicts to the appropriate owner rather than silently overriding them.

package/skills/engineering/ensure-coverage/references/breadth/coverage-ledger.md

@@ -2,6 +2,8 @@
 
 > Read when: building or auditing the breadth axis — reconciling requirement sources against the surface inventory. Holds both the **doctrine** (what the ledger is) and the **mechanics** (how to operate it). Siblings: [surface-baseline.md](surface-baseline.md) (the floor each surface owes), [surface-discovery.md](surface-discovery.md) (how surfaces are found), [inventory-contract.md](inventory-contract.md) (the discovery adapter), [examples/coverage-ledger.md](../examples/coverage-ledger.md) (worked shapes).
 
+This reference describes an optional ledger and its existing mechanical behavior, not a requirement to create a ledger or reconcile all ADRs for routine features. Use it when requested or already required by the repository. Its errors and floors remain binding when an existing required check enforces them; seek approval rather than bypassing or silently changing that policy. A whole-repo census requires an explicitly requested broad audit.
+
 ## Doctrine: the ledger is a reconciliation, not an anchor
 
 Breadth is a reconciliation of independent enumerations, never a single anchor. **No one requirement source is complete** — anchoring only on ADRs misses surfaces nobody wrote an ADR for; anchoring only on code misses intent that was never built.
@@ -22,7 +24,7 @@ Once a row is `Aligned` (or an `Orphan surface` carrying its baseline floor), th
 
 ## Three layers
 
-Separate discovery, curated intent, and the generated aggregation; let CI reconcile them. Status is **computed, never stored**, so per-requirement files for a shared surface cannot diverge — there is no status field to disagree on.
+When using the ledger, separate discovery, curated intent, and the generated aggregation; reconcile them where requested or already required. Status is **computed, never stored**, so per-requirement files for a shared surface cannot diverge — there is no status field to disagree on.
 
 - **Generated inventory** (never hand-edited): surface discovery from code — routes, APIs, tables, events. Regenerated on every change.
 - **Curated coverage** (hand-maintained, one file per requirement at `docs/tests/<adr|prd|design>/<id>-<slug>.coverage.yml`): the surfaces that requirement owns, each with required test level, `uiOnly`, criteria link, optional gap issue. Ownership and intent only — **not** status.
@@ -53,9 +55,9 @@ The aggregation maps `@covers` → surface, checks required levels, flags intern
 
 ## Acceptance gate
 
-Make coverage a precondition of accepting a requirement, not an optional follow-up.
+When the repository has adopted this ledger acceptance gate, follow its configured requirements. Otherwise this is an optional mechanism, not a new acceptance gate.
 
-- Every accepted requirement with runtime behavior must own `docs/tests/<source>/<id>-*.coverage.yml` that links its `criteria` doc, before it can merge; the requirement's own PR adds both.
+- If the adopted gate requires it, an accepted requirement with runtime behavior owns `docs/tests/<source>/<id>-*.coverage.yml` linked to its `criteria` doc.
 - A known gap is declared, not hidden: the coverage file names a `gapIssue` or `gapDoc` in place of `criteria` while the gap is open.
 - A requirement with no runtime behavior (pure architecture, terminology) says "no runtime behavior" in its own text and needs no coverage file.
 - The gate is mechanical: `coverage.config.json` → `requirementGlobs: { adr: "docs/adr" }` (and `prd`, `design`, …); `coverage-ledger.mjs validate` then errors on every accepted document with no coverage file, or a coverage file with neither criteria nor a tracked gap. `acceptedMarker` overrides the default `status: accepted` / `**Status:** accepted` match.
@@ -74,7 +76,7 @@ The breadth axis is enforced by checks that fail (error) or warn:
 - required level is integration/API/journey but only unit/mock evidence resolves;
 - internal interception counted as behavior coverage (`Over-mocked`).
 
-Run reconciliation during the audit regardless of who authored the change. Keep the generated inputs deterministic and report stale inventory rather than repairing it during an audit. This validator is evidence for the coverage verdict, not a CI gate; curated golden-path smoke is the sole CI gate ([CI contract](../enforcement/ci-contract.md)).
+Run reconciliation when requested or required by the repository, within the authorized scope. Keep generated inputs deterministic and report stale inventory rather than repairing it during an audit. Existing required CI checks remain binding; do not add a gate without authorization ([CI contract](../enforcement/ci-contract.md)).
 
 ## Reference validator
 
@@ -87,6 +89,6 @@ node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs validate [--co
 node ~/.agents/skills/ensure-coverage/scripts/coverage-ledger.mjs report                       # markdown index + ADR matrix view
 ```
 
-**Outputs.** `aggregate` writes the surface-keyed `coverage-index.json` **and** a sibling `coverage-metrics.json` — roll-up counts plus the **over-mock rate** (`overMocked / tested` depth-graded surfaces, split `overMockedBehavior` / `overMockedPresentation`). The metric is a separate file, not a key in the index. `validate` and the `report` header print the rate inline (`N/T tested surfaces over-mocked (X%)`). The over-mock *count* is zero-tolerance in the audit verdict ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* lets the reviewer **trend honesty as the suite grows** (a count rises just from more tests, a rate does not).
+**Outputs.** `aggregate` writes the surface-keyed `coverage-index.json` **and** a sibling `coverage-metrics.json` — roll-up counts plus the **over-mock rate** (`overMocked / tested` depth-graded surfaces, split `overMockedBehavior` / `overMockedPresentation`). The metric is a separate file, not a key in the index. `validate` and the `report` header print the rate inline (`N/T tested surfaces over-mocked (X%)`). Treat the over-mock count as a lead to inspect in context ([../depth/mock-policy.md](../depth/mock-policy.md)); the *rate* is a trend signal, not an automatic feature blocker. An adopted required gate retains its configured result.
 
 Surface *discovery* is the one repo-specific piece — supply an inventory adapter per [inventory-contract.md](inventory-contract.md) (a reference Next.js one ships at `scripts/adapters/nextjs-inventory.mjs`). Curated files follow `schemas/coverage-file.schema.json`.