jamminrebel/pom-omp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: make audit gates evidence-backed and correct stale check-count claims

Browse Source 
- wire npm audit (prod + full dev tree) through readGate instead of hardcoded NOT RUN reasons
- record real results: production 0 vulns PASS; dev tree 16 dev-only advisories FAIL, disclosed with reach and remediation
- docs/VERIFICATION.md: six checks -> seven, add package-metadata section and mutation row, record executed row-7 proof
- README/SETTINGS: replace six-gate wording with the actual gate ledger
This commit is contained in:
Antigravity
2026-08-19 11:40:18 +02:00
parent 0164fcbddb
commit 7b714bfc6b
8 changed files with 93 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/SETTINGS.md
View File

@@ -57,4 +57,4 @@ built-in defaults
| Bun | `>=1.3.14` | `engines.bun` |
| Node.js + npm | Node 22 or newer | Local scripts and the `node:test` suite |
Verification state: the six repository-local gates pass and `npm run verify` exits 0 from a clean `npm install`; the four host-dependent gates (both `npm audit` scopes, `npm run doctor`, interactive TUI smoke) remain NOT RUN. See the README section Verification status.
Verification state: `npm run verify` exits 0 from a clean `npm install`. Seven evidence-backed gates PASS, `npm audit` on the full development tree FAILS on 16 dev-only transitive advisories under the `@oh-my-pi/*` peer SDK (production audit reports 0, so nothing reaches the published tarball), and two host-dependent gates (`npm run doctor`, interactive TUI smoke) remain NOT RUN. See the README section Verification status.

38
docs/VERIFICATION.md
View File

@@ -1,6 +1,6 @@
---
title: Documentation verification
description: The six documentation-contract checks in scripts/check-docs.mjs and how to prove they fail
description: The seven documentation-contract checks in scripts/check-docs.mjs and how to prove they fail
---
# Documentation verification
@@ -32,10 +32,10 @@ POM docs verification FAIL (1/6: layout-contract)
```
The final line is `POM docs verification PASS` with exit code 0, or
`POM docs verification FAIL (<count>/6: <check names>)` with exit code 1. All six checks always
`POM docs verification FAIL (<count>/7: <check names>)` with exit code 1. All seven checks always
run; one failure never hides another.
## The six checks
## The seven checks
| # | Name | Canonical owner | Mirrors checked |
|---|---|---|---|
@@ -45,6 +45,7 @@ run; one failure never hides another.
| 4 | `prompt-order-contract` | `src/prompts.ts` `composePromptStack` and `renderStagePrompt` | `POM.yml` `prompt_precedence` |
| 5 | `link-and-orphan` | the `docs/` tree on disk | every `docs/*.md` page |
| 6 | `release-evidence` | `scripts/release-manifest.mjs` gate readers | `RELEASE.json` `verification` |
| 7 | `package-metadata` | `package.json` `repository`, `homepage`, `bugs` | canonical `loca.zone` hosts, no placeholders |
### 1. resource-package-parity
@@ -116,6 +117,17 @@ keeps them evidence-bound.
Historical defect: the manifest carried hard-coded `"PASS"` strings for gates that had never been
executed, so the release claimed verification it could not support.
### 7. package-metadata
Defends canonical project coordinates. `package.json` `repository`, `homepage`, and `bugs` must each
be a string or an object carrying a string `url`, must not retain the `UNRESOLVED` placeholder, must
parse as absolute URLs, and must resolve to `loca.zone` or a subdomain of it, because no third-party
forge mirror has been confirmed for this package. A `repository.url` on owned infrastructure prints a
`note:` line recording its serving state.
Historical defect: the metadata fields carried `UNRESOLVED` placeholders, and later recorded a
`repository.url` that was reserved but not serving Git while the prose claimed it was usable.
## Known divergences
`KNOWN_COMMAND_DIVERGENCES` in `scripts/check-docs.mjs` is the only escape hatch, and it contains
@@ -131,17 +143,21 @@ Each row is a specified procedure for proving that a check actually defends its
mutation, run `node scripts/check-docs.mjs`, confirm the named check reports `FAIL` with the
expected message, then revert the mutation and confirm the run returns to
`POM docs verification PASS`. Mutations are destructive edits to canonical files and must be
reverted before any commit or package step. This section specifies the procedure and the expected
output; it records no executed results, because the checker was not run when this page was written.
reverted before any commit or package step. Rows 1–6 specify the procedure and expected output
without recorded results. Row 7 was executed on 2026-08-19: pointing `homepage` at
`https://example.com/` produced `FAIL check 7/7 package-metadata` and
`POM docs verification FAIL (1/7: package-metadata)` with exit code 1, and restoring the file
returned `POM docs verification PASS` with exit code 0.
| Check | Mutation to apply | Expected failure |
|---|---|---|
| 1 `resource-package-parity` | Remove `"prompts"` from the `files` array in `package.json` | `FAIL check 1/6 resource-package-parity` — `package.json: files must contain "prompts" because src/prompts.ts and src/events.ts load it at runtime` |
| 2 `command-parity` | Delete the `/pom status [--json]` row from the `## Command map` table in `README.md` | `FAIL check 2/6 command-parity` — `/pom status is documented in src/command.ts HELP, POM.yml commands: but absent from README.md ## Command map` |
| 3 `layout-contract` | Rename `06_ledgers` to `06_logs` on the ledger line of `skills/pom/references/artifacts.md` | `FAIL check 3/6 layout-contract` — `skills/pom/references/artifacts.md:10 names "06_logs", which src/persistence.ts bootstrapProject never creates` |
| 4 `prompt-order-contract` | In `POM.yml` `prompt_precedence`, move the executable stage contract entry above the project-local fragment entry so it is no longer last | `FAIL check 4/6 prompt-order-contract` — `POM.yml: prompt_precedence must end with the executable stage contract appended by renderStagePrompt`, plus the misplaced-entry position |
| 5 `link-and-orphan` | In `docs/index.md`, change the Package inventory link target from `INVENTORY.md` to `INVENTORY-old.md` | `FAIL check 5/6 link-and-orphan` — `docs/index.md: broken relative link INVENTORY-old.md resolves to docs/INVENTORY-old.md, which does not exist on disk`, and `docs/INVENTORY.md: unreachable page` if `docs/navigation.md` no longer links it either |
| 6 `release-evidence` | Replace the `verification.runtimeSmoke` object in `RELEASE.json` with the bare string `"PASS"` | `FAIL check 6/6 release-evidence` — `RELEASE.json: verification.runtimeSmoke is the bare string "PASS"; every gate must be an evidence object carrying a status` |
| 1 `resource-package-parity` | Remove `"prompts"` from the `files` array in `package.json` | `FAIL check 1/7 resource-package-parity` — `package.json: files must contain "prompts" because src/prompts.ts and src/events.ts load it at runtime` |
| 2 `command-parity` | Delete the `/pom status [--json]` row from the `## Command map` table in `README.md` | `FAIL check 2/7 command-parity` — `/pom status is documented in src/command.ts HELP, POM.yml commands: but absent from README.md ## Command map` |
| 3 `layout-contract` | Rename `06_ledgers` to `06_logs` on the ledger line of `skills/pom/references/artifacts.md` | `FAIL check 3/7 layout-contract` — `skills/pom/references/artifacts.md:10 names "06_logs", which src/persistence.ts bootstrapProject never creates` |
| 4 `prompt-order-contract` | In `POM.yml` `prompt_precedence`, move the executable stage contract entry above the project-local fragment entry so it is no longer last | `FAIL check 4/7 prompt-order-contract` — `POM.yml: prompt_precedence must end with the executable stage contract appended by renderStagePrompt`, plus the misplaced-entry position |
| 5 `link-and-orphan` | In `docs/index.md`, change the Package inventory link target from `INVENTORY.md` to `INVENTORY-old.md` | `FAIL check 5/7 link-and-orphan` — `docs/index.md: broken relative link INVENTORY-old.md resolves to docs/INVENTORY-old.md, which does not exist on disk`, and `docs/INVENTORY.md: unreachable page` if `docs/navigation.md` no longer links it either |
| 6 `release-evidence` | Replace the `verification.runtimeSmoke` object in `RELEASE.json` with the bare string `"PASS"` | `FAIL check 6/7 release-evidence` — `RELEASE.json: verification.runtimeSmoke is the bare string "PASS"; every gate must be an evidence object carrying a status` |
| 7 `package-metadata` | Point `homepage` in `package.json` at `https://example.com/` | `FAIL check 7/7 package-metadata` — `package.json: homepage points at "example.com", which is outside the canonical loca.zone infrastructure` |
Row 5 mutates a link rather than deleting a file, so the mutation is a one-token edit and the revert
is exact. Row 6 must be reverted by regenerating the manifest with `npm run release:manifest` rather