From 4dba7af5c958a86fd35da12ed291def1bd2b3fce Mon Sep 17 00:00:00 2001 From: Pascal Andy Date: Mon, 2 Nov 2026 14:42:13 -0500 Subject: [PATCH 1/3] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20docs:=20mo?= =?UTF-8?q?ve=20the=20other=20folders=20of=20the=20architecture=20to=20the?= =?UTF-8?q?ir=20own=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit architecture.md holds 9,943 bytes, and just limits caps a growing file at 10,000. The list of the folders outside the code map now has its own file, with no change of its text, so that the next commit can add a section. architecture.md links the new file in place of the list. --- docs/north-star/architecture.md | 12 +----------- docs/north-star/architecture/other-folders.md | 13 +++++++++++++ 2 files changed, 14 insertions(+), 11 deletions(-) create mode 100644 docs/north-star/architecture/other-folders.md diff --git a/docs/north-star/architecture.md b/docs/north-star/architecture.md index 8975380c..c3b063e4 100644 --- a/docs/north-star/architecture.md +++ b/docs/north-star/architecture.md @@ -75,17 +75,7 @@ Each part has one owner: one package and one spec section. A later shared service starts in `sdk/`. Core keeps in `internal/` only what an extension never runs: the host, core's commands and catalog, and the keychain. [The backlog](../backlog/README.md) records when each implementation arrives. -The other folders: - -- `cmd/ncly/`: the entry point. It passes core an explicit list of bundled extensions and the keychain backend. When started under an extension's name, it runs that extension -- `internal/specdoc/`: reads the tables of the north-star docs for the tests that compare code and spec -- `testdata/script/`: core's testscript scenarios. An extension keeps its own in `extensions//testdata/script/`, and the test binary of `cmd/ncly` runs both -- `testdata/extensions/hello/`: the Go fixture extension that proves the SDK, laid out as a first-party extension. `./...` skips it, so `just lint` and `just test` name it -- `testdata/extensions/keyed/`: the Go fixture whose commands need a key: `keyed fetch` reads it through `Call.Key`, and `keyed relay` passes it to a program through `sdk/wrap`. Only the scenarios install it, so `hello`, which `just verify` installs in every run, declares no key, and doctor passes in a run without one -- `testdata/extensions/video-convert/` and `video-subtitle/`: named fixtures for root execution and sibling completion. `testdata/extensions/shared/export/` exports their embedded sidecars for verification -- `testdata/extensions/standalone/`: the whole-domain fixture repository of the test kit, a separate Go module that tests `sdk/extensiontest` against `go tool ncly`. Its named-extension counterpart is `testdata/extensions/standalone-named/`. `./...` skips both modules, so `just test`, `just lint`, `just fmt-check`, and `just tidy-check` cover both explicitly -- `copier.yml` and `template/`: the extension template, which creates an extension repository. Its Go files end in `.jinja`, so `./...` never builds them. `just template` renders it with `scripts/template-test.sh` and checks the rendered repository -- `tools/`: a separate module that pins the dev tools and holds the plan checker behind `just next` and `just test` +[Other folders](architecture/other-folders.md) says what each folder outside the code map holds, such as `cmd/ncly/`, `testdata/`, `template/`, and `tools/`. ## Domains and commands diff --git a/docs/north-star/architecture/other-folders.md b/docs/north-star/architecture/other-folders.md new file mode 100644 index 00000000..42a4bf6a --- /dev/null +++ b/docs/north-star/architecture/other-folders.md @@ -0,0 +1,13 @@ +# Other folders + +This part of [Architecture](../architecture.md#code-map) says what each folder outside the code map holds. + +- `cmd/ncly/`: the entry point. It passes core an explicit list of bundled extensions and the keychain backend. When started under an extension's name, it runs that extension +- `internal/specdoc/`: reads the tables of the north-star docs for the tests that compare code and spec +- `testdata/script/`: core's testscript scenarios. An extension keeps its own in `extensions//testdata/script/`, and the test binary of `cmd/ncly` runs both +- `testdata/extensions/hello/`: the Go fixture extension that proves the SDK, laid out as a first-party extension. `./...` skips it, so `just lint` and `just test` name it +- `testdata/extensions/keyed/`: the Go fixture whose commands need a key: `keyed fetch` reads it through `Call.Key`, and `keyed relay` passes it to a program through `sdk/wrap`. Only the scenarios install it, so `hello`, which `just verify` installs in every run, declares no key, and doctor passes in a run without one +- `testdata/extensions/video-convert/` and `video-subtitle/`: named fixtures for root execution and sibling completion. `testdata/extensions/shared/export/` exports their embedded sidecars for verification +- `testdata/extensions/standalone/`: the whole-domain fixture repository of the test kit, a separate Go module that tests `sdk/extensiontest` against `go tool ncly`. Its named-extension counterpart is `testdata/extensions/standalone-named/`. `./...` skips both modules, so `just test`, `just lint`, `just fmt-check`, and `just tidy-check` cover both explicitly +- `copier.yml` and `template/`: the extension template, which creates an extension repository. Its Go files end in `.jinja`, so `./...` never builds them. `just template` renders it with `scripts/template-test.sh` and checks the rendered repository +- `tools/`: a separate module that pins the dev tools and holds the plan checker behind `just next` and `just test` From cc560495c4dcab7c853abe85ceb3bddfa0918c4b Mon Sep 17 00:00:00 2001 From: Pascal Andy Date: Mon, 2 Nov 2026 14:48:43 -0500 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20docs:=20plan:=20map=20each?= =?UTF-8?q?=20check=20to=20an=20owner=20and=20a=20level,=20as=20COR-104?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit D068 extends D067 with the owner and level map of the verification loop: core, the template, and each extension, at the levels of code, checks, prose, then QA and UAT. It says how a correction moves up a level and across owners, and it replaces the score of the 36 trial cases with three measures: the prose-only rules of each rule index, the level and owner of each correction in the ledger, and the real use of the loop by video-convert. architecture.md gets a short section that links D067 and D068, and the glossary defines a verification level apart from a layer. COR-104 holds ten cards, core and template first, then video-convert, which adopts the loop as #427 asks. It follows COR-102 in the queue. The evidence is in nicely-research, under synthesis/verification-map. --- docs/backlog/COR-104-verification-map.md | 176 ++++++++++++++++++ docs/backlog/README.md | 3 +- docs/north-star/architecture.md | 7 + .../D067-share-verification-rules.md | 1 + .../decisions/D068-verification-map.md | 93 +++++++++ docs/north-star/decisions/README.md | 1 + docs/north-star/glossary/acceptance.md | 4 + 7 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 docs/backlog/COR-104-verification-map.md create mode 100644 docs/north-star/decisions/D068-verification-map.md diff --git a/docs/backlog/COR-104-verification-map.md b/docs/backlog/COR-104-verification-map.md new file mode 100644 index 00000000..5e428f79 --- /dev/null +++ b/docs/backlog/COR-104-verification-map.md @@ -0,0 +1,176 @@ +--- +id: COR-104 +core: "verification map" +state: "Ready. Core and template first, then video-convert" +--- + +# COR-104 verification map + +## Demo + +`just status` counts prose-only rules, the ledger names the level and owner of each correction, and video-convert releases through the kit. + +## Scope + +[D068][d068] holds the map, the way a correction moves, and the measures. +Each card names its owner (A, B, or C) and level, and fails first on a past mistake. +Trial findings are evidence of gaps only. + +## Cards + +| Card | Title | Owner | Depends on | Status | +|---|---|---|---|---| +| COR-104-T1 | Rule indexes and ledger columns | agent | - | todo | +| COR-104-T2 | SDK analyzers in every check | agent | - | todo | +| COR-104-T3 | Owned verification runs | agent | COR-104-T2 | todo | +| COR-104-T4 | Typed build records | agent | - | todo | +| COR-104-T5 | Acceptance evaluator in the kit | agent | - | todo | +| COR-104-T6 | Publication declaration | agent | - | todo | +| COR-104-T7 | Publication helpers | agent | COR-104-T6 | todo | +| COR-104-T8 | TLC runner in the kit | agent | - | todo | +| COR-104-T9 | Adoption and shared corrections | agent | COR-104-T4 | todo | +| COR-104-T10 | Video-convert adopts the loop | agent | COR-104-T1, COR-104-T2, COR-104-T3, COR-104-T4, COR-104-T5, COR-104-T6, COR-104-T7, COR-104-T8, COR-104-T9 | todo | + +### COR-104-T1 Rule indexes and ledger columns + +- **Read:** [D068][d068], [N2][n2], [QA ledger](../qa/ledger.md) +- **Proves:** `tools/cmd/plan/rules_test.go`, `tools/cmd/plan/qa_test.go` + +A, level 2, measures 1 and 2. +Core gets an index of the 154 rules of N2 in `docs/north-star/rules/`. +`just test` checks both indexes: each enforcer links a file, or says `Prose only` or `Prose on purpose`. +Each Go file of `sdk/extensiontest` and `sdk/extensionrepo`, except tests, enforces an indexed rule or is a listed helper. +`just status` prints the `Prose only` count of each index, and `extensionrepo check` that of an extension. +The template index marks 11 judgment rules `Prose on purpose`, and deletes one rule that signoff replay enforces. +The QA ledger gets a Corrections table, with Level and Owner columns for each correction. +It fails first at 7f3ae60e, where `ledger_history.go` enforced rules that no row named until b3dc8b48. + +### COR-104-T2 SDK analyzers in every check + +- **Read:** [D068](../north-star/decisions/D068-verification-map.md), [P1][p1] +- **Proves:** `sdk/analysis/runnerdiscard/runnerdiscard_test.go`, `scripts/template-test.sh` + +A, level 2, measure 2. +`sdk/analysis` holds Go analyzers, and `go vet -vettool` runs them. +Core's `just lint` and `extensionrepo check` run them, at the Nicely version that the extension pins. +The first rule refuses `io.Discard` in `Stdout` or `Stderr` of a `runner.Program`. +It fails first on the parent of 3e6a4eff, and on a rendered extension with that line. + +### COR-104-T3 Owned verification runs + +- **Read:** [D068](../north-star/decisions/D068-verification-map.md), [N1][n1] +- **Proves:** `sdk/extensiontest/isolation_test.go`, `scripts/template-recipes-test.sh` + +A, level 1, measure 2, for 26 corrections of caller state and lost notices. +One SDK constructor builds the environment and scratch folder of the kit, signoff, release, and acceptance. +One result carries the answer, notices, and exit code to the caller. +An analyzer rule refuses `os.Environ` in these packages outside that constructor. Replacing `HOME` alone is no isolation. +It fails first on the parent of 09809608, which passed `os.Environ()`, and on the lost notices of e35bd0bb. + +### COR-104-T4 Typed build records + +- **Read:** [D068][d068], [Finish gate](../north-star/contract/finish-gate.md), [N2][n2] +- **Proves:** `scripts/template-finish-test.sh`, `scripts/template-ledger-test.sh` + +A, level 1, measures 1 and 2, for 17 corrections of review prose and five template rules. +Intake facts and review findings become typed records that the SDK reads. +A fact is sourced, an inference, or unknown, and an unknown fact opens a line. +A finding has one ID, severity, state, spec ID, and family. `fixed` needs a passing and a refused test of its family. +The SDK writes `## Intake` and `readiness.md` from them, and finish reads only the records. +It fails first on the parent of 59d33f38, where a finding with no state passed finish, and on the free-form grades of #422. + +### COR-104-T5 Acceptance evaluator in the kit + +- **Read:** [D068][d068], [Test kit](../north-star/contract/test-kit.md), [N2][n2] +- **Proves:** `sdk/extensiontest/acceptance_test.go`, `scripts/template-test.sh` + +A, level 2, measures 1 and 2, for five template rules. +The extension declares each acceptance case: a made input, a reader other than the wrapped program, a reference, and any private marker. +The kit reads the output with that reader, compares it with the reference, and searches the marker. +It requires the declared bad variant to fail, and a case for each Output case that applies by the first review. +It fails first on the parent of 86d24e83, where a prefix match accepted a larger number, and on the private text of #425. + +### COR-104-T6 Publication declaration + +- **Read:** [D068][d068], [Generic cases](../north-star/contract/generic-cases.md), [N3][n3] +- **Proves:** `sdk/extensiontest/publication_test.go`, `scripts/template-test.sh` + +A, level 2, measure 2. +The `spec.md` form declares each command that creates or replaces a user file. +It gives the destination, protected paths, operation of each mode, needed file system abilities, and dry-run treatment. +The kit requires an executed check for each declared obligation, or a reason. +A successful dry run changes no protected path, and predicts the destination and overwrite choice of the run. +It fails first on #425: a dry run passed, and the run failed on a destination with no hard link. + +### COR-104-T7 Publication helpers + +- **Read:** [D068][d068], [Scenario commands](../north-star/contract/scenario-commands.md), [N3][n3] +- **Proves:** `sdk/extensiontest/paired_test.go` + +A, level 2, measure 2. +A helper protects the declared paths around any call, and checks children before its own cleanup. +Another holds a worker after a partial staged write, then observes the public path and the commit. +A Linux fixture refuses link, no-replace rename, or replacing rename for the child only, and names a platform that cannot. +`replace-a-file.md` covers every writer, private exclusive staging, the permission policy, and failure before and after commit. +It fails first on a fallback that checks the output, then renames over it, which generic cases forbid ([N3][n3]). + +### COR-104-T8 TLC runner in the kit + +- **Read:** [D068](../north-star/decisions/D068-verification-map.md), [P2][p2] +- **Proves:** `sdk/verification/verification_test.go`, `verification/finish/Finish.tla` + +A, level 2, measure 2. +`sdk/verification` gets TLC, checks its SHA-256 before Java starts, runs model suites, and records only matching outcomes. +It accepts a local jar with that digest. Changed bytes, as on 2026-11-02, never prove a model, and a new pin needs a review. +The template gets one optional `just verify-models` recipe, and `just check` reads only the record. +Core's first model, its finish gate, fails first on the behavior before 59d33f38. + +### COR-104-T9 Adoption and shared corrections + +- **Read:** [D068][d068], [Update an extension](../north-star/contract/update-an-extension.md) +- **Proves:** `scripts/template-update-test.sh`, `scripts/template-test.sh` + +B, level 2, measure 3. +As #427 asks, the contract and the template skill say how an existing extension adopts `just finish`. +Its first build starts at the update commit, its intake reads its current `spec.md`, and it keeps past review SHAs. +The update test renders an extension at v0.23.4, updates it, runs that first build, and requires `just signoff` to pass. +The skill also teaches the step of D068 for a correction of A or B, as prose on purpose. +It fails first on #427, and the step on #407, where an extension could not fix answers of `sdk/wrap`. + +### COR-104-T10 Video-convert adopts the loop + +- **Read:** [D068](../north-star/decisions/D068-verification-map.md), [P2][p2] +- **Proves:** readiness.md and the release receipt, in ncly-video-convert + +C, level 2, measures 2 and 3. +In ncly-video-convert, after the release of its dependencies, update and run the first build of #427. +Its publication proof runs through `sdk/verification`, and keeps its model, mapping, probes, and expected results. +It declares its publications and acceptance cases. +Each correction gets a ledger row, and a correction of A or B gets the step of D068. +It fails first on its record, which rejects the new pin ([P1][p1]), and on #427. Done when `just signoff` and `just release` pass. + +## After + +Pascal runs a UAT of video-convert at the release of COR-104-T10, and its corrections enter the ledger. + +## Later + +### Unprivileged scratch runs + +Tests, acceptance, and reviews run in a new scratch folder, with no root, mount, or system service. +Two template rules stay `Prose only` until then. + +Revisit condition: a review stalls on a recursive delete or mounts a file system again, as in #425. + +### Process lifetime in the runner + +`sdk/runner` makes the output of each program an explicit choice, and the COR-104-T2 rule on `io.Discard` goes. + +Revisit condition: a new correction of exit, signal, drain, or cleanup, class K04 of [N1][n1]. + +[d068]: ../north-star/decisions/D068-verification-map.md +[n1]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/analysis/N1-correct.md +[n2]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/analysis/N2-prose-triage.md +[n3]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/analysis/N3-publication.md +[p1]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/proto/P1/REPORT.md +[p2]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/proto/P2/REPORT.md diff --git a/docs/backlog/README.md b/docs/backlog/README.md index 3884dbc1..0ceb21da 100644 --- a/docs/backlog/README.md +++ b/docs/backlog/README.md @@ -7,6 +7,7 @@ This folder holds one file per extension or core item and the ordered delivery q ## Queue 1. COR-102 +2. COR-104 ## Plan rules @@ -58,7 +59,7 @@ Create no new M file. | Shipped | Has no todo card or open questions | An extension maintained in its own repository, such as XT-101, keeps its cards in that repository's Epic. -The exception is COR-103, which holds the verification cards of video-convert. +The exceptions are COR-103 and COR-104, which hold the verification cards of video-convert. ## Make an item ready diff --git a/docs/north-star/architecture.md b/docs/north-star/architecture.md index c3b063e4..ad4bbe33 100644 --- a/docs/north-star/architecture.md +++ b/docs/north-star/architecture.md @@ -77,6 +77,13 @@ A later shared service starts in `sdk/`. Core keeps in `internal/` only what an [Other folders](architecture/other-folders.md) says what each folder outside the code map holds, such as `cmd/ncly/`, `testdata/`, `template/`, and `tools/`. +## Verification + +Three owners verify Nicely: core, the template, and each extension. +Each correction lands at the highest of four verification levels that can prevent it: code, checks, prose, then QA and UAT. +[D067](decisions/D067-share-verification-rules.md) chooses the owner of a check. +[D068](decisions/D068-verification-map.md) maps each owner and level to its mechanism, and names the three measures. + ## Domains and commands | Command | What it does | Kind | diff --git a/docs/north-star/decisions/D067-share-verification-rules.md b/docs/north-star/decisions/D067-share-verification-rules.md index f912ca62..dc9471de 100644 --- a/docs/north-star/decisions/D067-share-verification-rules.md +++ b/docs/north-star/decisions/D067-share-verification-rules.md @@ -4,6 +4,7 @@ Decided for [COR-103-T13](../../backlog/COR-103-verification-loop.md#cor-103-t13 Core's imported SDK and test kit own shared checks. Each extension supplies its inputs, fixtures, expected values, and independent checks. The template copies only tool calls and forms for the author. +[D068](D068-verification-map.md) maps each owner and verification level to its mechanism, and names the measures. ## Choose the owner diff --git a/docs/north-star/decisions/D068-verification-map.md b/docs/north-star/decisions/D068-verification-map.md new file mode 100644 index 00000000..55c195e7 --- /dev/null +++ b/docs/north-star/decisions/D068-verification-map.md @@ -0,0 +1,93 @@ +# D068 Map each check to an owner and a level + +Decided 2026-11-02 by Pascal, for [COR-104](../../backlog/COR-104-verification-map.md). +It extends [D067](D067-share-verification-rules.md) and keeps its line: evaluators in the SDK and kit, facts in each extension, only wiring and forms in the template. + +## Owners and levels + +Three owners verify Nicely: + +- **A, core**: the SDK, the test kit `sdk/extensiontest`, the repository gates `sdk/extensionrepo`, CI, and the `nicely` skill +- **B, the template**: `template/`, with its wiring, its forms, the `nicely-extension` skill, and its rule index +- **C, each extension**: its code, its facts, its tests, and its own skill. ncly-video-convert is the first + +Four verification levels form a pyramid, with level 1 at the top: + +1. Code: the architecture, types, and invariants that make a wrong state impossible to write +2. Checks: lint, analyzers, tests, scenarios, acceptance, CI, and formal models +3. Prose: rules, skills, and `AGENTS.md` +4. QA by an agent that did not write the change, and UAT by a human + +These levels are not the layers of the [code map](../architecture.md#code-map). + +## The map + +| Level | A, core | B, template | C, each extension | +|---|---|---|---| +| 1. Code | SDK types with one owner for each invariant, such as `sdk/runner`, `sdk/record`, `sdk/wrap`, and `sdk/contract` | Rendered entry points that only call the SDK | Domain code: shared preparation, input refusal, and its own publication | +| 2. Checks | Kit checks and helpers, repository gates, Go analyzers, the TLC runner, `just check`, and core CI | One-line recipes, the CI workflow, and the forms that the gates read | Scenarios, Go tests, `acceptance.sh`, declared facts, and its TLA+ model with its mapping | +| 3. Prose | `AGENTS.md`, the decisions, the core rule index, and the `nicely` skill | Its `AGENTS.md`, the rule index, and the `nicely-extension` skill | Its `AGENTS.md`, its skill, and **Limits.** in `spec.md` | +| 4. QA and UAT | verify-nicely by another agent, the UAT protocol, and the [UAT ledger](../../qa/ledger.md) | The readiness review by another agent, and the `qa.md` form | `just acceptance` on real input, its UAT, and the acceptance of Pascal | + +Each extension keeps its publication logic: staging, link, rename, and replace. +A and B give the checks, helpers, fixtures, forms, and skill lines that prove it. +The TLC runner is a kit tool. +Each extension keeps its TLA+ model, its mapping to its code, its probes, and its expected results. + +A and B get each practice first. C adopts it last, through `just update`. +A card that adds an evaluator ships its template form in the same pull request. + +## Move a correction + +1. Choose the owner with D067. +2. Choose the highest level that can prevent the failure: + - Level 1 when one type, one owner, or one constructor makes the wrong state impossible to write + - Level 2 when a machine can decide from the code, a declaration, or an observed run + - Level 3 only for a judgment that no machine can make + - Level 4 for authority, perception, and consent +3. Prove the correction with a fixture that reproduces the past failure. The fixture fails without the correction. +4. Update the rule index of the owner, and add a row with its level and owner to the correction ledger. + +A rule index gives each rule one enforcer: a link to its check, `Prose only`, or `Prose on purpose` with the judgment that keeps it in prose. +`Prose only` marks a rule that waits for a check. +A card that adds the check moves the rule up. +A correction can also land below the level of step 2, such as one scenario for a class that a type could prevent. +Its ledger row shows that gap, and a later card moves the class up. + +When an extension finds a correction that belongs to A or B: + +1. Its agent opens an issue in pascalandy/nicely with the input, the host, and the failure. +2. The extension records a limit under **Limits.** of `spec.md` that links the issue. The user accepts it like any other limit. +3. A Nicely release carries the fix. After `just update`, a proven line replaces the limit. + +The `nicely-extension` skill teaches this step. + +## Measures + +These three measures replace the score of the 36 trial cases. + +| Measure | What it counts | Where to read it | Start | +|---|---|---|---| +| 1. Pyramid shape | The rules whose enforcer is `Prose only`, for each owner | `just status` for the core and template indexes, `extensionrepo check` for an extension | A: 79 of 154 rules. B: 24 of 57 rules ([N2][n2]). C, video-convert: 3 of 15 ([S4][s4]) | +| 2. Correction ledger | The level where each correction landed, and its owner | The Level and Owner columns of the Corrections table in the [QA ledger](../../qa/ledger.md) | 66 of 237 past corrections landed below their highest working level ([N1][n1]) | +| 3. Real use | Video-convert adopts the loop, and its corrections feed measure 2 | COR-104-T10, and the rows of video-convert in the ledger | Not adopted, as #427 says | + +**Why.** Since 2026-10-01, 232 of 237 corrections reached level 1 or 2 ([N1][n1]). +But 66 landed below the highest level that works, and four classes hold 50 of them. +These classes are review prose read as state, caller state in checks, lost notices, and process lifetime. +The trial score measured a fixed set of cases. A full score still hid gaps in private data, preparation, and review. +A map tells each correction its owner and level before anyone writes it. +An SDK analyzer reached an extension at its pinned version through the unchanged template recipe ([P1][p1]). +The TLC runner moved into the kit, and video-convert kept the same 12 outcomes ([P2][p2]). + +**Rejected.** A fifth level for formal models, because a model is a check of level 2. +A new count of trial cases, because a count does not say where a correction belongs. +A publication service in the SDK, because it takes publication away from the extension. +A copy of the TLC runner or of analyzer rules in each extension, for the reasons of D067. +One count of all prose, because a judgment belongs in prose and would hide the rules that wait for a check. + +[n1]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/analysis/N1-correct.md +[s4]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/scouts/S4-inventory.md +[n2]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/analysis/N2-prose-triage.md +[p1]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/proto/P1/REPORT.md +[p2]: https://github.com/pascalandy/nicely-research/blob/main/synthesis/verification-map/proto/P2/REPORT.md diff --git a/docs/north-star/decisions/README.md b/docs/north-star/decisions/README.md index 836bd43c..fe5ed131 100644 --- a/docs/north-star/decisions/README.md +++ b/docs/north-star/decisions/README.md @@ -73,3 +73,4 @@ A new decision takes the next number, a file named `D0NN-.md` that s | [D065](D065-backlog-items.md) | Plan work by extension and core backlog items | | [D066](D066-refuse-unreadable-variables.md) | Refuse a variable or a language that ncly cannot read | | [D067](D067-share-verification-rules.md) | Share verification rules and keep extension facts | +| [D068](D068-verification-map.md) | Map each check to an owner and a level | diff --git a/docs/north-star/glossary/acceptance.md b/docs/north-star/glossary/acceptance.md index f0c78d99..34c4a72e 100644 --- a/docs/north-star/glossary/acceptance.md +++ b/docs/north-star/glossary/acceptance.md @@ -30,3 +30,7 @@ - Human escalation - Def.: a case where the agent of a UAT stops and calls a human, as [protocol.md](../../qa/protocol.md#human-escalation) lists them - Project note: each UAT issue names its cases in a section of that name +- Verification level + - Def.: one of the four steps of the verification pyramid: code, checks, prose, then QA and UAT. Level 1, code, is the top + - Project note: [D068](../decisions/D068-verification-map.md) maps each owner and level to its mechanism + - Distinct from: a layer of the [code map](../architecture.md#code-map), which says what code may import From 70919c5e89228cf3aa2e1e7e9716d048a739beee Mon Sep 17 00:00:00 2001 From: Pascal Andy Date: Mon, 2 Nov 2026 15:33:59 -0500 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20docs:=20plan:=20COR-104=20na?= =?UTF-8?q?mes=20its=20release=20before=20video-convert,=20and=20the=20his?= =?UTF-8?q?tory=20of=20old=20records?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Video-convert updates to a Nicely release, but D043 releases an item only when it ships. The last merge of T1 to T9 now releases a minor version, as this plan asks. An extension with Markdown build records starts a new build when it updates and keeps them as history. Co-Authored-By: Claude Opus 5.5 --- docs/backlog/COR-104-verification-map.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/backlog/COR-104-verification-map.md b/docs/backlog/COR-104-verification-map.md index 5e428f79..7e65ab87 100644 --- a/docs/backlog/COR-104-verification-map.md +++ b/docs/backlog/COR-104-verification-map.md @@ -14,6 +14,7 @@ state: "Ready. Core and template first, then video-convert" [D068][d068] holds the map, the way a correction moves, and the measures. Each card names its owner (A, B, or C) and level, and fails first on a past mistake. +The last merge of T1 to T9 releases a minor version with release-nicely, as this plan asks. Trial findings are evidence of gaps only. ## Cards @@ -39,7 +40,6 @@ Trial findings are evidence of gaps only. A, level 2, measures 1 and 2. Core gets an index of the 154 rules of N2 in `docs/north-star/rules/`. `just test` checks both indexes: each enforcer links a file, or says `Prose only` or `Prose on purpose`. -Each Go file of `sdk/extensiontest` and `sdk/extensionrepo`, except tests, enforces an indexed rule or is a listed helper. `just status` prints the `Prose only` count of each index, and `extensionrepo check` that of an extension. The template index marks 11 judgment rules `Prose on purpose`, and deletes one rule that signoff replay enforces. The QA ledger gets a Corrections table, with Level and Owner columns for each correction. @@ -77,6 +77,7 @@ Intake facts and review findings become typed records that the SDK reads. A fact is sourced, an inference, or unknown, and an unknown fact opens a line. A finding has one ID, severity, state, spec ID, and family. `fixed` needs a passing and a refused test of its family. The SDK writes `## Intake` and `readiness.md` from them, and finish reads only the records. +An extension with Markdown records starts a new build when it updates, and keeps them as history. It fails first on the parent of 59d33f38, where a finding with no state passed finish, and on the free-form grades of #422. ### COR-104-T5 Acceptance evaluator in the kit @@ -132,7 +133,7 @@ Core's first model, its finish gate, fails first on the behavior before 59d33f38 B, level 2, measure 3. As #427 asks, the contract and the template skill say how an existing extension adopts `just finish`. -Its first build starts at the update commit, its intake reads its current `spec.md`, and it keeps past review SHAs. +Its first build starts at the update commit, and its intake reads its current `spec.md`. The update test renders an extension at v0.23.4, updates it, runs that first build, and requires `just signoff` to pass. The skill also teaches the step of D068 for a correction of A or B, as prose on purpose. It fails first on #427, and the step on #407, where an extension could not fix answers of `sdk/wrap`. @@ -143,7 +144,7 @@ It fails first on #427, and the step on #407, where an extension could not fix a - **Proves:** readiness.md and the release receipt, in ncly-video-convert C, level 2, measures 2 and 3. -In ncly-video-convert, after the release of its dependencies, update and run the first build of #427. +In ncly-video-convert, update to that release and run the first build of #427. Its publication proof runs through `sdk/verification`, and keeps its model, mapping, probes, and expected results. It declares its publications and acceptance cases. Each correction gets a ledger row, and a correction of A or B gets the step of D068.