From 1b6d6d5c289a7b3065ce75e985db5179f89a9b99 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 16:27:34 +0200 Subject: [PATCH 01/23] docs(harness): bootstrap reference-export-drift-gate leaf Stages the authored slice brief for #1296 (wave 2, internals lane). Refs #1296 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01DkCGyCU4GvfDs3Kk1yEUty --- .../reference-export-drift-gate/implement.md | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/implement.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/implement.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/implement.md new file mode 100644 index 0000000000..85ca486ff7 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/implement.md @@ -0,0 +1,113 @@ +use harness + +## SKILL + +Read `AGENTS.md`, then the `netscript-harness`, `netscript-tools`, `netscript-pr`, +`netscript-doctrine`, `netscript-deno-toolchain`, and `jsr-audit` skills. Then read issue **#1296** +in full. You are the implementation author for a new internals leaf. + +## Identity + +- Leaf: `reference-export-drift-gate`, wave 2, internals lane +- Worktree: `/home/codex/repos/netscript-007-reference-export` (already created, clean) +- Branch: `fix/reference-export-drift-gate`, based on `origin/main` `baf1cdf67` +- Run dir: `.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/` +- Closes exactly **#1296** +- Archetype `6-cli-tooling`, overlays `frontend` + `docs` + +## This pass: research and plan only. No implementation. + +Produce `research.md` and `plan.md`, commit, push, open the PR as **draft**, comment, then **stop**. +I run Tier-A on your exact pushed head. State explicitly in `plan.md` whether a fresh PLAN-EVAL is +required and why — that gate is the coordinator's to grant, not yours to assume. + +## Authorized file surface — exactly nine paths, from the frozen leaf contract + +``` +.github/workflows/ +.llm/tools/docs/check-accuracy-and-discoverability.ts +.llm/tools/docs/check-exports-drift.ts +deno.json +docs/exports +docs/site/reference/fresh-ui/index.md +packages/contracts/src/application/contract-primitives.ts +packages/contracts/src/application/paginated-query.ts +packages/contracts/src/public/mod.ts +``` + +Narrow this with per-path justification and name what you deliberately will **not** touch. A tenth +path is rescope: stop and ask me. Note `docs/exports` **does not exist** on baseline — see A2 below. + +## Ground truth I measured before briefing you — verify each, do not trust it + +**A1 — the drift gate is real, passing, and wired to nothing.** +`deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts` +returns **raw exit 0** and prints `Exports & Symbols drift check: PASS`. But +`grep -rn 'check-exports-drift\|exports-drift' deno.json .github/workflows/` returns **zero hits**. +The tool exists, works, and **guards nothing** — no task, no workflow, not in `docs:maintenance` +(which is `docs:links && docs:accuracy && docs:contract-derivation && agentic:sync-claude:check && +agentic:check-claude`). This is the live core of acceptance row 5, and it is the same +coverage-versus-compliance defect this lane keeps finding: a green that proves nothing because +nobody runs it. Re-derive this yourself; do not cite my measurement as your evidence. + +**A2 — a contracted surface does not exist.** `docs/exports` is in the frozen contract but is absent +on baseline `baf1cdf67`. Determine whether it is a path you are expected to *create* (a generated +export inventory) or a stale contract entry, and say which in `research.md`. Do not invent a +directory just to satisfy the contract, and do not silently drop it. + +**A3 — acceptance row 1 is already satisfied on baseline.** The coordinator's Step-0 synthesis +found: `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, and +`OffsetPaginationQuerySchema` are all re-exported from the root (`src/public/mod.ts:2-6,65`) and the +JSDoc at `contract-primitives.ts:72,112,144` already imports correctly. **Four rows remain live.** +Verify this independently. If it holds, reconcile the issue row **honestly and visibly** — state in +the PR that it was already satisfied at baseline rather than ticking a box you did not earn. If your +measurement contradicts Step-0, say so with evidence; that is a finding, not a problem. + +**A4 — the #1112 / MySQL half is not yours.** #1296's body defers it to **#1293**, which is still +`OPEN` / `status:impl`. The frozen surface contains no `prisma-adapter-mysql` path, confirming the +split. Do not touch it and do not block on it. + +## The four live acceptance rows + +1. Contracts reference inventory advertises no non-exports. +2. Fresh UI reference surface repaired to match its published exports. +3. Intentional omissions expressed **machine-readably** rather than being silently incomplete. +4. Maintainer regeneration runbook documented **and** the drift check wired into the documentation + verification path. + +Row 3 is the design decision in this leaf — choose the machine-readable format deliberately and +justify it against how the existing checkers consume data. Row 4 is where A1 lands: pick the wiring +point (task graph, `docs:maintenance`, CI workflow, or a combination) and defend it. Wiring a gate +that then fails on baseline is a legitimate outcome — report it, do not tune the gate until it goes +quiet. + +## Proving gates from the contract + +`check`, `test`, `publish-dry-run`, `quality-job`, `arch-check`, `docs-source-format`, +`docs-accuracy` — plus **`fresh-browser`**, which **this lane may not execute**. Plan for +`fresh-browser`, classify it, and **ask, not take**: state in `plan.md` what it would prove and +whether it is genuinely required for this surface. Do not run Aspire, Docker, browsers, or +`e2e:cli`. `jsrAudit` is **applicable**: audit public exports and exact `@netscript` dependency pins +for every touched publishable member, and plan an isolated-declaration `publish:dry-run`. +`packages/contracts` is a **published** member — if you change its public surface or JSDoc that +ships, say so in the JSR table honestly. The #1663 leaf was failed by its evaluator for claiming +"no publish delta" over a surface it had not examined; do not repeat that. + +## Evidence discipline + +- Read raw exit codes **unpiped** (`"${PIPESTATUS[0]}"` or no pipe). A masked exit is a false green; + this exact trap has bitten this lane. +- An empty selection is a **refusal**, not a pass. +- A command that did not fire is NOT FIRED — never infer a result. +- Scratch belongs in `.llm/tmp/`, never inside a measured selection root. +- Prefer `deno doc` over broad source reads for public surfaces. + +## Boundaries + +Do not merge, publish, flip ready, relabel beyond the leaf's own `status:`, close issues, alter +milestone scope, mutate central cluster state, or touch another lane's worktree. PR targets `main` +and stays **draft**. + +Commit, push, open the draft PR with `Closes #1296` in the body and the namespaced labels, post the +structured `[PHASE: RESEARCH]` / `[PHASE: PLAN]` comment, then **stop**. If a proof comes out red, +report it red — an honest red is worth more than a green I have to disbelieve. From 9d0b4bf128ba52fcd52091ba50590661d09470c1 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 16:42:09 +0200 Subject: [PATCH 02/23] plan(docs): lock reference export drift gate --- .../reference-export-drift-gate/plan.md | 234 +++++++++++++++++ .../reference-export-drift-gate/research.md | 240 ++++++++++++++++++ 2 files changed, 474 insertions(+) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md new file mode 100644 index 0000000000..33769d83c3 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md @@ -0,0 +1,234 @@ +# Plan: reference-export-drift-gate + +## Run metadata + +| Field | Value | +| ------------------------- | ------------------------------------------------------------------------------ | +| Run ID | `release-0.0.7-internals--orchestration/slices/reference-export-drift-gate` | +| Leaf / lane | `reference-export-drift-gate` / wave 2 internals | +| Branch / base | `fix/reference-export-drift-gate` / `baf1cdf67a4e931af17b4772ddf6101f36152184` | +| Phase | research + plan only; implementation prohibited in this pass | +| Closing issue | exactly `Closes #1296` | +| Archetype | frozen `6 — CLI / Tooling` | +| Overlays | `frontend`, `docs` | +| Package doctrine subjects | Contracts: Archetype 1 / Keep; Fresh UI: Archetype 4 / Keep | + +## Goal + +Make the claimed reference boundary falsifiable: correct the remaining shipped Contracts query +import, reconcile Fresh UI's reference with its six-entrypoint/168-symbol published surface, make +every symbol-coverage omission an explicit machine-readable policy decision, document the maintainer +update path, and expose/run the already-existing drift gate through named local and Pages +verification edges. + +The leaf preserves the already-correct Contracts root exports/examples and does not manufacture a +`docs/exports` inventory. + +## Exact narrowed edit surface (locked) + +The nine frozen implementation paths are narrowed as follows. Run artifacts requested by the +coordinator (`research.md`, `plan.md`, and later harness evidence) are control-plane records, not a +tenth implementation path. + +| Frozen path | Planned action | Per-path justification | +| ----------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.github/workflows/` | Edit only `.github/workflows/pages.yml`. | Add one named `deno task docs:exports-drift` step in the existing build job. Current triggers already cover docs, packages, plugins, docs tooling, and root task configuration; no new workflow or path filters. | +| `.llm/tools/docs/check-accuracy-and-discoverability.ts` | Edit only the existing child invocation. | Call the named task instead of a hidden raw script argv while preserving fail-closed child-exit handling and single execution under `docs:accuracy`. | +| `.llm/tools/docs/check-exports-drift.ts` | Edit. | Introduce reason-bearing symbol coverage policy, reject invalid/empty policy, parse only actual symbol-inventory tables, normalize display generics, support explicitly labeled doc-only copy-source symbols, and enable Fresh UI symbol checking without false greens. | +| `deno.json` | Edit tasks only. | Add `docs:exports-drift` with least required permissions. Keep `docs:accuracy` and therefore `docs:maintenance` as the aggregate local path; do not duplicate the drift command in the same maintenance run. | +| `docs/exports` | **Do not create or edit.** | No baseline/history path, producer, or consumer exists. The live checker derives inventories in memory; creating this directory would add a drifting second authority. This frozen entry is stale. | +| `docs/site/reference/fresh-ui/index.md` | Edit. | Correct stale public-surface claims; add the missing desktop, ActionMenu/Combobox, registry, render-UI, DataGrid, namespace/contract inventory; keep Dropzone visibly copy-source; add maintainer regeneration/update runbook. | +| `packages/contracts/src/application/contract-primitives.ts` | **Do not edit.** | The named examples already import valid root exports. Editing would falsely claim work already present at baseline and would create unnecessary published JSDoc delta. | +| `packages/contracts/src/application/paginated-query.ts` | Edit JSDoc only. | Change the shipped module example from the non-exporting root to `@netscript/contracts/query`. No runtime/type semantics. | +| `packages/contracts/src/public/mod.ts` | **Do not edit.** | The briefed contract symbols already resolve from the root. No export addition/removal is warranted. | + +No tenth implementation path is authorized. In particular, do not touch +`.llm/tools/docs/check-exports-drift_test.ts`, the Contracts reference page, any Fresh UI package +source/config, MySQL package/reference paths, `deno.lock`, doctrine/debt, central cluster state, or +another lane's worktree. If implementation needs one, stop and request rescope from the coordinator. + +## Locked decisions + +| ID | Decision | Rationale | +| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| D1 | Keep package `deno.json.exports` and per-entrypoint `deno doc --json` as the sole export/symbol authority; never materialize `docs/exports`. | Avoids a second generated/handwritten inventory and preserves A1/A14 dependency direction. | +| D2 | Replace `checkSymbols` + free-standing `excludedSymbols` with a discriminated `symbolCoverage` policy. | A boolean `false` silently disables proof. A discriminant makes completeness versus deliberate entrypoint-only coverage machine-readable and exhaustively consumable. | +| D3 | `symbolCoverage` has two modes: `complete` with reason-bearing omission groups, and `entrypoints-only` with one required nonempty reason. | A skipped symbol gate is a policy fact, not absence of configuration. Empty/malformed reasons are refusal, never pass. | +| D4 | Complete-mode mappings may name reason-bearing `documentedNonExports` groups for copy-source/API-adjacent symbols that the page explicitly labels as non-package exports. | Fresh UI's Dropzone section is useful and honest. The checker must distinguish explicit copy-source docs from invented package exports without globally weakening invented-symbol detection. | +| D5 | Parse symbol inventories only from Markdown tables whose first header cell is exactly `Symbol`; ignore prop/field/shape tables, strip display generic suffixes such as ``, and retain grouped symbol-cell support. | Eliminates the measured false positives (`columns`, `label`, `layout`, generic display names) before enabling enforcement. Exclusions must never compensate for parser defects. | +| D6 | Fresh UI uses `complete` mode. Document user-facing components/functions/constants/namespaces and their public contract families; every intentionally omitted low-level member type is enumerated in sorted reason-bearing groups. | Repairs the reproduced Fresh UI surface and makes remaining curation auditable. A newly exported symbol must be documented or explicitly classified before the gate returns green. | +| D7 | Existing currently entrypoint-only mappings remain entrypoint-only only with explicit reasons; Config, Contracts, Fresh UI, and Telemetry remain/enter complete mode. | Satisfies machine-readable omission policy without pretending this leaf authored complete prose for unrelated packages. Promotion of other packages can occur independently. | +| D8 | Correct only `paginated-query.ts` to `/query`; preserve `contract-primitives.ts` and `src/public/mod.ts`. | Independent `deno doc` proves the briefed root symbols are already valid, while `paginatedQuery` is absent from root and present on `/query`. | +| D9 | Add `docs:exports-drift`; make `docs:accuracy` call it; add the same named task as a Pages build step. | Gives maintainers a fast direct command, retains the existing aggregate local/maintenance gate, and makes workflow execution explicit on already-correct triggers. No duplicate execution occurs within either path. | +| D10 | The Fresh UI runbook documents derivation, not file generation: inspect every `deno.json.exports` entry with `deno doc --json`, update the page and coverage policy, run the direct drift task, then the aggregate accuracy task. | There is no generator today. Calling a manual derived update "regeneration" is honest only when the source of truth and verification steps are explicit. | +| D11 | Do not tune the checker to baseline green. First land semantics that refuse malformed coverage, then reconcile the page/policy until the unchanged live export authority passes. | Coverage and compliance remain distinct. A real red after wiring is reported red. | + +## Open-decision sweep + +| Decision | Status | Resolution | +| -------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------- | +| Whether `docs/exports` should be created | resolved now | No; stale frozen entry, explicitly non-touched. | +| Machine-readable omission format | resolved now | D2-D4 discriminated, reason-bearing mapping policy. | +| Symbol-table parser boundary | resolved now | D5 exact `Symbol` header plus display-name normalization. | +| Direct task versus aggregate versus workflow wiring | resolved now | D9 combination: named task, existing accuracy/maintenance aggregate, Pages step. | +| Whether the briefed Contracts root exports need edits | resolved now | No; baseline-earned and explicitly reported. | +| Whether package-source doc-lint debt should be fixed | safe to defer | Outside frozen paths; record baseline reds without weakening gates. | +| Whether every mapped package should become symbol-complete now | safe to defer | This leaf makes non-complete status explicit/reasoned; unrelated prose expansion is separate scope. | +| Whether Fresh browser proof must run | coordinator decision required | See `fresh-browser` classification below. The implementation lane may not execute it. | + +No unresolved decision besides the coordinator-owned browser classification would force source +rework. Browser classification affects evidence only, not implementation design. + +## Ordered implementation slices + +### S1 — make reference coverage explicit and reconcile the live surfaces + +- Files: `.llm/tools/docs/check-exports-drift.ts`, `docs/site/reference/fresh-ui/index.md`, + `packages/contracts/src/application/paginated-query.ts`, and slice run artifacts. +- Introduces: + - the discriminated reason-bearing coverage policy and fail-closed validation; + - table-aware symbol parsing and generic normalization; + - Fresh UI complete-mode enforcement, documented non-export classification, and exact omission + groups; + - repaired Fresh UI reference sections and the maintainer derivation/update runbook; + - the `/query` import in shipped Contracts JSDoc. +- Proves: direct drift command raw exit 0 only after all six Fresh UI entrypoints and the curated + symbol boundary reconcile; the existing negative-fixture test still proves an added entrypoint is + red. One-off negative policy probes must report nonzero for empty reasons/unknown modes; they are + recorded as diagnostic evidence because the frozen surface forbids editing the test file. +- Slice review: confirm exclusions classify real exported symbols only, each reason is substantive, + Dropzone remains visibly non-exported, and no Contracts runtime/export changes entered the diff. + +### S2 — expose and execute the gate through the documentation path + +- Files: `deno.json`, `.llm/tools/docs/check-accuracy-and-discoverability.ts`, + `.github/workflows/pages.yml`, and slice run artifacts. +- Introduces: named least-permission `docs:exports-drift` task, aggregate invocation from + `docs:accuracy`, and a named Pages verification step. +- Proves: + - direct search now finds explicit task/workflow wiring; + - `deno task docs:exports-drift` and `deno task docs:accuracy` each return raw exit 0; + - Pages workflow tests and source-format gates remain green; + - a controlled drift diagnostic makes the named task nonzero and therefore would fail both + aggregate and workflow edges. No product file is left modified after the diagnostic. +- Slice review: ensure the task executes once per path, child stdout/stderr remain visible on + failure, permissions are no broader than required, and workflow triggers were not widened. + +### S3 — history-bound contract and publication evidence + +- Files: slice run artifacts only; no implementation path edits. +- Proves at the exact committed head: `check`, `test`, `publish-dry-run`, `quality-job`, + `arch-check`, `docs-source-format`, and `docs-accuracy` through durable receipts; focused direct + drift and JSR evidence; exact nine-path diff audit; no lock churn. +- Handoff: coordinator performs Tier-A substantive review and grants/dispatches PLAN-EVAL and later + IMPL-EVAL according to the recorded gates. The author neither self-certifies nor advances the PR + to ready. + +## Validation plan + +Durable merge evidence must use `.llm/tools/gates/run-gate.ts` at committed heads. Structured +wrapper selections must be nonempty. Raw exit codes are captured unpiped; a command that never fires +is `NOT FIRED`. + +| Order | Gate | Classification and evidence | +| ----- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Focused checker test | Run `.llm/tools/docs/check-exports-drift_test.ts` unchanged; existing negative export fixture must pass. Add recorded one-off negative probes for invalid coverage policy and invented/omitted Fresh symbols; no scratch under measured roots. | +| 2 | Direct export drift | `deno task docs:exports-drift`; must enumerate/compare the configured surfaces and exit 0 only after reconciliation. | +| 3 | `check` | Frozen contract gate via durable receipt; wrapper-backed type selection must be nonempty. | +| 4 | `test` | Frozen full behavior gate via durable receipt, including docs/tool/workflow tests selected by the repository task. | +| 5 | `quality-job` | Frozen CI-quality composite; records wrapper-backed lint/fmt/dependency evidence. | +| 6 | `arch-check` | Required because published Contracts JSDoc is touched; no doctrine/debt regression. | +| 7 | `docs-source-format` | Run from the required docs-site context through the cataloged gate; proves source/Vento formatting. Also run its existing test if the coordinator's receipt set requires it, but do not substitute that extra test for the contracted gate. | +| 8 | `docs-accuracy` | Must fire the named drift child and propagate its real exit; terminal PASS alone is accepted only with the source/task binding reviewed. | +| 9 | `publish-dry-run` | Canonical workspace simulation at the exact head; proves the shipped Contracts JSDoc and isolated declarations package statically. Review member/file output; do not infer real-publish success. | +| 10 | JSR audit | Re-run package audit for Contracts and reference-subject audit for Fresh UI; preserve/report sanctioned or pre-existing reds exactly. Verify exact NetScript pins from member config. | +| 11 | Git/path/lock audit | Direct raw Git commands prove only frozen implementation paths plus run artifacts changed; `docs/exports`, `deno.lock`, package export maps, and MySQL paths remain untouched. | + +No Aspire, Docker, browser, `e2e:cli`, scaffold runtime, service runtime, publish, release cut, or +resource cleanup is planned. + +## `fresh-browser` classification and request + +**Status: NOT FIRED — this lane is not authorized to execute it.** + +If granted, `fresh-browser` would prove only that the edited reference page builds/renders with +usable headings, anchors, tables, code blocks, and responsive presentation in the real Fresh docs +site. It would not prove that a symbol exists, that an omission policy is complete, or that the +Contracts import resolves; the checker, snippet/static gates, and `deno doc` own those facts. + +This plan judges `fresh-browser` **not genuinely required** for the frozen surface because no route, +component, CSS, island, interaction, loading/error state, or application workflow changes. The +frontend overlay is present because Fresh UI is the documented package, not because browser behavior +is modified. The author asks the coordinator to record an explicit waiver/N/A. If Tier-A instead +requires rendered-reference assurance, the coordinator must grant and execute the gate in an +authorized lane; that changes evidence, not scope or implementation. + +## JSR audit plan + +| JSR concern | Contracts | Fresh UI reference subject | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Publish delta | Shipped `paginated-query.ts` JSDoc changes; call this a publish delta even though runtime/types/exports do not. | No member file changes, but inspect all six exports before authoring the reference. | +| Export audit | `deno doc` on `.`, `./crud`, `./query`, `./transform`; assert `paginatedQuery` only from `/query` and preserve root symbols verified in research. | `deno doc --json` on all six entrypoints; 168-symbol union is checker input, not a remembered count baked into docs tooling. | +| Exact `@netscript/*` pins | None; explicitly zero rows, not "not examined." | Preserve `sdk/auto-update` and `sdk/desktop` exact at `@netscript/sdk@0.0.6`; no source/config change. | +| Documentation | Correct copyable module import. Baseline `doc:lint` has nine private-type-ref reds; report as baseline and do not claim zero. | Reference corrected. Baseline package `doc:lint` has 123 `/interactive` reds; source fix is out of scope and remains honest red. | +| Slow types / isolated declarations | `audit-jsr-package` sanctioned oRPC slow-type INFO; final canonical `publish:dry-run` required under root `isolatedDeclarations:true`. | Audit currently reports slow types plus structural warnings; no package change, no waiver invention. | +| Publish set / assets | Confirm edited JSDoc source is included by `src/**/*.ts`; no new asset/import/read. | No package file or runtime asset delta. | + +If implementation changes a public export, type signature, member dependency, version, publish +filter, or any other publishable member, stop and rescope before continuing. A green dry-run is a +static prerequisite, never permission to publish. + +## Anti-patterns and fitness gates + +| AP/F | Plan | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| A1/A2/A14, F-5 | Live export maps and `deno doc` lead; the doc/checker follows. Coverage policy prevents boolean false-green claims. | +| A7/AP-2/AP-9 | Reuse Deno, existing mapping, existing task/gate/workflow. No generator or second inventory. | +| AP-18 | Negative checks assert semantic omitted/invented names and exit behavior, not giant full-page snapshots. | +| F-6 | Canonical workspace publish dry-run plus per-member JSR inspection; preserve sanctioned/pre-existing findings. | +| F-7 | Reference accuracy improves, but package-source doc-lint baselines remain red and are not mislabeled PASS. | +| F-19 | Contracted check/test/quality evidence comes from repository wrappers/receipts; empty selection refuses. | +| F-CLI-1..31 | No product CLI package shape changes. Manual review applies the relevant tooling concerns: one focused checker, edge-owned subprocess, explicit failure exit, no new barrel/adapter/command surface. | + +## Risk register + +| Risk | Mitigation | +| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Exclusion list becomes a hiding place | Require complete mode, exact exported names, sorted reason-bearing groups, reject unknown names/empty reasons, and Tier-A review every Fresh omission. | +| Markdown parser mistakes prose tables for exports | D5 exact header boundary plus negative field/prop table probe; never quiet false positives with exclusions. | +| Duplicate symbol re-exports across root/subpaths inflate or conflict | Preserve Set de-duplication while checking every entrypoint derived from `deno.json.exports`. | +| Page truth changes while hardcoded count stays green | Do not encode 168 as a permanent expected constant; derive it every run and report the measured count. | +| Hidden wiring is mistaken for absent wiring | PR/research state baseline indirect edge explicitly; S2 improves discoverability/workflow coverage without claiming prior work as leaf-earned. | +| Pages CI duplicates or bypasses local gate | Both edges call the same named task; `docs:accuracy` remains the local aggregate and Pages gets one direct step. | +| Workflow edit requires an unauthorized test edit | Run existing workflow tests unchanged. If they fail and require source changes outside the nine paths, stop for rescope rather than editing tests. | +| Existing package JSR/doc-lint debt is mistaken for regression or silently waived | Record baseline raw reds in research/JSR table and compare final results; do not weaken checker/audit settings or enter package source. | +| Large Fresh reference edit renders poorly | Docs format/build/links are required; browser remains coordinator-classified and may be granted externally. | +| Lock or package surface churn appears during validation | Direct diff audit; do not stage `deno.lock`; stop if exports, pins, versions, or unrelated publishable source changes. | + +## Explicit deferrals and non-scope + +- `docs/exports` creation or any generated inventory artifact. +- The already-correct Contracts root exports and `contract-primitives.ts` JSDoc. +- Contracts reference-page prose outside the frozen surface. +- Fresh UI package source, namespace/type exports, doc-lint/slow-type/structure remediation, visual + design, component behavior, CSS, or registry contents. +- MySQL/#1293/#1112 paths and acceptance. +- Symbol-complete prose expansion for unrelated entrypoint-only package mappings; their policy must + become explicit in this leaf, but their pages do not enter scope. +- New/edited tests outside the frozen paths, dependency/version/catalog/lock changes, doctrine/debt, + central milestone state, issue checkbox mutation, merge, publish, ready flip, or release work. +- Aspire, Docker, browser execution, `e2e:cli`, scaffold/static/runtime smokes. + +## PLAN-EVAL judgement + +**Fresh PLAN-EVAL: REQUIRED, but not granted or performed by this author.** + +The implementation volume is bounded, but the plan is decision-heavy: it changes what a green +cross-package documentation gate means, introduces a reason-bearing omission contract, must separate +parser errors from real omissions, and reconciles a materially false carried-in wiring claim. +Deferring any of those decisions would force checker/doc rework. Harness policy therefore requires a +fresh separate-session opposite-family PLAN-EVAL before implementation. + +The coordinator owns the grant/dispatch and must run Tier-A on this exact pushed planning head. This +author does not assume a verdict, does not create `plan-eval.md`, and must not begin implementation +until the coordinator records `PASS`. A failure is reported as `FAIL_PLAN`, not worked around. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md new file mode 100644 index 0000000000..9d145e8c34 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md @@ -0,0 +1,240 @@ +# Research — reference-export-drift-gate + +## Re-baseline + +- Carried-in sources: issue [#1296](https://github.com/rickylabs/netscript/issues/1296), its one + milestone-rollover comment, issues #1110/#1108/#1293, PR #1292, and the coordinator's frozen leaf + contract. +- Re-derived on 2026-08-15 from branch bootstrap head `1b6d6d5c289a7b3065ce75e985db5179f89a9b99`, + whose merge-base with `origin/main` is the frozen baseline + `baf1cdf67a4e931af17b4772ddf6101f36152184`. +- The branch contains only the coordinator's bootstrap commit beyond baseline. The runtime-created + untracked `codex-thread-ids.md` is not author-owned and will not be staged. +- Issue #1296 is open on milestone 27, now titled `0.0.7`. Issue #1293 remains open at + `status:impl`; its MySQL paths are outside this leaf. + +The carried-in measurements are partly stale. A1's direct-search observation is reproducible, but +its conclusion that the drift checker is "wired to nothing" is false at the frozen baseline. A3's +Contracts-root conclusion is correct, while a different source JSDoc import remains wrong. + +## Live acceptance contract + +Issue #1296 has five close-gated boxes. Independent re-baselining classifies them as follows: + +| Issue row | Baseline state | Leaf treatment | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Contracts examples import from the real exporting path | already satisfied for the specifically named `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, and `OffsetPaginationQuerySchema` examples | Preserve and state as baseline-earned, not leaf-earned. A separate `paginatedQuery` module example is still wrong and belongs to the live inventory repair. | +| Contracts reference inventory advertises no non-exports | reference page/checker pass, but `paginated-query.ts` advertises `paginatedQuery` from the root where it is not exported | Correct the shipped module JSDoc to `@netscript/contracts/query`; do not edit the already-green reference page outside the frozen surface. | +| Fresh UI reference matches published exports | not satisfied | Repair against all six entrypoints and enable an explicit symbol-coverage policy. | +| Intentional omissions are machine-readable | not satisfied | Replace boolean/silent symbol coverage with a discriminated, reason-bearing policy consumed by the checker. | +| Maintainer regeneration runbook and verification wiring | partially satisfied | Preserve the existing fail-closed `docs:accuracy` edge, make it directly addressable/discoverable, add Pages CI execution, and document the update procedure. | + +The four live rows in the frozen brief therefore remain meaningful, but row 4 begins from partial, +not zero, implementation. + +## Findings + +### F1 — direct task/workflow discovery is empty, but runtime wiring already exists + +The exact unpiped baseline checks were: + +```text +deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts +Exports & Symbols drift check: PASS +EXPORT_DRIFT_RAW_EXIT=0 + +grep -rnE 'check-exports-drift|exports-drift' deno.json .github/workflows/ +WIRING_SEARCH_RAW_EXIT=1 +``` + +That search cannot establish "wired to nothing" because it excludes the aggregator source. +`.llm/tools/docs/check-accuracy-and-discoverability.ts:291-301` creates a `Deno.Command('deno')` +whose argv directly runs `check-exports-drift.ts`, checks the real child exit code, and throws on +nonzero. `git blame` attributes that edge to PR #1292's merge commit `6c3b534fc`. + +`deno task docs:accuracy` also completed with raw exit 0 and printed its terminal PASS after the +awaited child edge. `docs:maintenance` invokes `docs:accuracy`, and the durable gate catalog maps +`docs-accuracy` to that task. Therefore the checker already guards local documentation accuracy and +maintenance. What is missing is: + +1. a named `docs:exports-drift` task that maintainers and automation can discover and invoke; +2. a direct workflow execution path — Pages currently runs snippets/build/links/caveats, not export + drift or `docs:accuracy`; +3. a runbook that tells maintainers how to derive and reconcile the surface. + +### F2 — `docs/exports` is a stale frozen-contract entry, not a generated target + +- `test -e docs/exports` returned exit 1. +- `git ls-tree -r --name-only baf1cdf67 -- docs/exports` returned no paths. +- Repository and all-history searches find no producer, consumer, task, checker, or historical + commit for `docs/exports`; only the frozen briefing names it. +- The live authority already has the correct dependency direction: package `deno.json.exports` plus + `deno doc --json` are derived in memory and compared directly with + `docs/site/reference//index.md`. + +Creating `docs/exports` would introduce a third inventory that can itself drift and would violate +the issue requirement not to maintain a second handwritten entrypoint list. The path will remain +absent and will be named as a deliberate non-touch in the plan. + +### F3 — the specifically briefed Contracts root surface is already correct + +`packages/contracts/src/public/mod.ts` re-exports: + +- `baseContract` and `BaseContract` at lines 2-3; +- `BaseContractOutputRoute` and `BaseContractRoute` at lines 4-7; +- `OffsetPaginationQuerySchema` in the schema export block. + +Four independent `deno doc --filter` commands against `packages/contracts/mod.ts` returned raw exit +0 and rendered each of `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, and +`OffsetPaginationQuerySchema`. The examples in `contract-primitives.ts` import the first three from +`@netscript/contracts`, and the root module example imports the pagination schema from the same +root. Those are valid, copyable imports at baseline. + +No edit to `contract-primitives.ts` or `src/public/mod.ts` is earned by this leaf. The PR must say +that row was already satisfied rather than claiming it as implementation. + +### F4 — a different shipped Contracts JSDoc import is still wrong + +`packages/contracts/src/application/paginated-query.ts` begins its published `@module` example with: + +```ts +import { paginatedQuery } from '@netscript/contracts'; +``` + +The root `deno doc --json packages/contracts/mod.ts` surface has 70 symbols and does not contain +`paginatedQuery`; the `./query` entrypoint does. The manual Contracts page already lists +`paginatedQuery`, `offsetPaginatedQuery`, and `cursorPaginatedQuery` under +`@netscript/contracts/query`, and the current exports/symbol drift checker passes that manual page. + +This reconciles issue #1110's wording ("correct the source JSDoc import that currently points at the +wrong root entrypoint") with the current tree. The live source fix is in `paginated-query.ts`, not +in the already-correct `contract-primitives.ts` examples named by #1296. + +### F5 — Fresh UI entrypoints are complete, but symbol coverage is disabled + +`packages/fresh-ui/deno.json` publishes exactly six entrypoints: + +| Entrypoint | Target | Symbols reported by the checker's current `deno doc` rule | +| --------------------- | ------------------------ | --------------------------------------------------------: | +| `@netscript/fresh-ui` | `./mod.ts` | 28 | +| `/ai/render-ui` | `./src/ai/render-ui.tsx` | 11 | +| `/desktop` | `./desktop.ts` | 35 | +| `/interactive` | `./interactive.ts` | 82 | +| `/primitives` | `./primitives.tsx` | 16 | +| `/registry` | `./registry.ts` | 7 | + +There are 168 unique symbols after cross-entrypoint de-duplication. All six `deno doc --json` +commands returned raw exit 0. The Fresh UI page now lists all six entrypoints, so the original "3 of +6" entrypoint defect has already been repaired by later work. The remaining defect is symbol truth: +its mapping still says `checkSymbols: false`. + +Current prose meaningfully documents root helpers, icons, DataGrid, toast helpers, seven older +interactive namespaces, primitives, and render UI. It omits or contradicts newer public surface: + +- `ActionMenu` and `Combobox` plus their public namespace/contracts; +- the complete `/desktop` capability/result/menu/window surface; +- the `/registry` manifest/content types; +- several render-UI node/category types and root DataGrid context types; +- the page says interactive `*Namespace` types are package-internal, but they are exported now. + +The page also intentionally documents `Dropzone` as a copy-source registry component and explicitly +says it is not a package export. That is valid documentation, but a symbol parser must not confuse +copy-source tables or prop/field tables with a claimed published-symbol inventory. + +### F6 — enabling the current symbol checker directly is a false-red trap + +An in-memory run using the checker's current algorithms, but forcing Fresh UI symbol checking, +produced: + +```text +EXPECTED=168 DOCUMENTED_PARSE=78 ERRORS=162 +``` + +The 162 errors mix real omissions with parser artifacts. `parseDocContent()` currently treats the +first backticked cell of every Markdown table as a symbol, so `columns`, `label`, `class`, +`[attribute: string]`, `layout`, and `viz` become invented exports. Generic display names such as +`DataGridColumn` do not normalize to the real `DataGridColumn`. Copy-source Dropzone types become +invented package exports even though the prose labels them as non-exports. + +The checker must first distinguish symbol tables from prop/field/example tables and normalize +display-only generic suffixes. Tuning exclusions until the current 162-error output is quiet would +hide checker defects and is forbidden by the evidence contract. + +### F7 — boolean coverage is the silent-incompleteness defect + +`PackageMapping` currently exposes independent `checkSymbols?: boolean` and +`excludedSymbols?: string[]` fields. `false` carries no reason and makes every omission invisible. +The checker only builds an exclusion `Set` when the boolean is true. This is precisely the state +that leaves Fresh UI, Plugin, Queue, SDK, and Service silently entrypoint-only. + +A discriminated coverage object fits the existing consumer: + +- `mode: 'complete'` — run `deno doc` for every derived entrypoint, and flatten explicit + reason-bearing omission groups into the exclusion set; +- `mode: 'entrypoints-only'` — skip symbol comparison only when a nonempty reason is present; +- a reason-bearing allow-list for doc-only copy-source symbols where a page explicitly labels them + as non-package exports. + +This retains the current `Set`-based comparison, makes invalid/empty policy a hard refusal, and +avoids a new inventory directory or handwritten export map. + +### F8 — workflow trigger coverage already fits the leaf + +`.github/workflows/pages.yml` already triggers on `docs/site/**`, `packages/**`, `plugins/**`, +`.llm/tools/docs/**`, and `deno.json` for pull requests and main pushes. Adding a named export-drift +step to its existing build job therefore covers every implementation path that can change either the +reference or its live authority. No trigger expansion, new workflow, browser, service, Docker, or +Aspire resource is necessary. + +### F9 — MySQL is independently owned and must not block this leaf + +Issue #1293 is open with `status:impl` and owns the Prisma MySQL exported adapter and remaining +executable-example work. The frozen nine-path surface contains no MySQL package or reference path. +This leaf neither reads that work as a prerequisite nor changes it. + +## JSR/publication surface scan + +JSR audit is applicable because one shipped JSDoc file inside published `@netscript/contracts` will +change and the Fresh UI reference is derived from a published member. + +| Member | Planned publish delta | Export map | Exact `@netscript/*` pins | Baseline evidence / risk | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@netscript/contracts@0.0.6` | Yes: `src/application/paginated-query.ts` JSDoc ships under `src/**/*.ts`; no runtime/type/export change. | Four entrypoints: `.`, `./crud`, `./query`, `./transform`; unchanged. | None in member imports. `@orpc/contract@^1.14.6` and root-catalog `zod` are non-NetScript dependencies. | `audit-jsr-package` raw exit 0; dry-run OK with one sanctioned oRPC slow-type INFO. Full-export `doc:lint` raw exit 1 with nine pre-existing private-type-ref diagnostics (eight contract primitives, one CRUD), not caused or fixed by this prose-only source edit. | +| `@netscript/fresh-ui@0.0.6` | No package file changes; reference/checker only. The plan still audits its real published surface rather than claiming "no publish delta" without inspection. | Six entrypoints listed in F5; unchanged. | `@netscript/sdk/auto-update` and `@netscript/sdk/desktop` are both exact `jsr:@netscript/sdk@0.0.6/...`; `deps:why @netscript/sdk` raw exit 0 confirms live source use. | `audit-jsr-package` raw exit 0 and dry-run OK, while reporting existing folder/cardinality and slow-type warnings. Full-export `doc:lint` raw exit 1 with 123 existing `/interactive` diagnostics. Source repair is outside the frozen surface. | + +Root `compilerOptions.isolatedDeclarations` is `true`. The final canonical workspace +`publish:dry-run` remains required because the Contracts JSDoc is part of the publish set. A green +dry-run will prove static packaging/isolated-declaration compatibility, not resolve the separately +reported baseline doc-lint debt or prove a real publish. + +## Doctrine and debt state + +- Frozen leaf archetype: `6 — CLI / Tooling`, because the changed executable surface is a + repository-run checker/task/workflow with structured failure semantics. +- Overlays: `frontend` because the reference subject is `@netscript/fresh-ui`, and `docs` because + the shipped artifact is a manual reference/runbook. +- Package doctrine remains explicit: Contracts is Archetype 1 / Keep; Fresh UI is Archetype 4 / + Keep. This leaf does not re-archetype either member. +- Axioms: A1/A2 (published truth first), A7 (reuse `deno doc`, `Deno.Command`, and the existing + checker), A8 (one checker concern), A14 (a green must prove coverage as well as compliance). +- Fitness focus: F-5 public surface, F-6 publishability, F-7 documentation, F-19 scoped verdict + sources. The relevant existing Contracts root-layout debt is preserved; no debt entry is opened or + closed by a JSDoc/docs/tooling repair. +- The existing Fresh UI doc-lint and structural findings are baseline observations, not authority to + enter package source. An honest red remains red in the JSR table. + +## Open questions resolved for planning + +- **Must resolve now:** Create `docs/exports`? No. It is stale contract scope and duplicative. +- **Must resolve now:** Is the drift checker currently unwired? No. It is indirectly fail-closed; + the plan makes the edge named and adds workflow execution without claiming a new gate from zero. +- **Must resolve now:** How are omissions represented? A reason-bearing discriminated policy in + `AUTHORITATIVE_MAPPING`, consumed directly by the existing checker. +- **Must resolve now:** Is Fresh UI browser execution necessary? No for export truth; only the + coordinator may require it as rendered-reference assurance. The implementation lane is forbidden + from firing it. +- **Safe to defer:** Existing Fresh UI public-source doc-lint/slow-type remediation and Contracts + oRPC private-type-ref debt; neither can be fixed within the frozen nine paths. +- **Safe to defer:** Broadening symbol-complete coverage for every reference page. This leaf makes + entrypoints-only policy explicit rather than silently claiming completeness; later leaves can + promote packages one at a time. From a3f6b87b599e778db950daf6ccaecd847c088d19 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 18:42:09 +0200 Subject: [PATCH 03/23] plan(docs): coordinator scope amendment SA-1 Control-plane amendment recorded by topic-internals-0.0.7 under coordinator authority. Changes authorized scope and gate classification only; no implementation decision (D1-D11) is modified and no implementation path is edited by this commit. A1 - authorizes a tenth implementation path, test-only: .llm/tools/docs/check-exports-drift_test.ts S1 lands fail-closed coverage-policy semantics whose refusal paths are load-bearing. The plan routed those to one-off probes explicitly because the frozen surface forbade editing the test file; a probe run once in a terminal leaves no artifact that can fail a future CI run. This leaf exists to remove gates that report green over code they never examined, so proving its own refusal paths with non-persistent evidence would reproduce the defect inside the fix. Minimum coverage: empty/malformed reason, unknown coverage mode, invented symbol, omitted symbol - each asserted nonzero. A2 - classifies fresh-browser N/A / waived. No route, component, island, CSS, or interaction behavior changes. NOT_RUN evidence is preserved and reported as NOT_RUN; no runtime lease is acquired. A3 - grants exactly one PLAN-EVAL cycle 1 over the amended immutable head after a fresh Tier-A: separate session, native Fable 5 / medium / Remote Control, artifact-only. A4 - sequences #1666 before #1533 so the example-compiler gate does not land red on the paginated-query JSDoc this leaf corrects. A5 - central leaf-contracts.json still freezes nine fileSurfaces and is coordinator-owned; this lane does not edit it. The reconciliation is reported upstream. plan.md is annotated inline rather than rewritten, so the author's original reasoning stays readable in git history. Refs #1296 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HqFtKQtyJcHBEn1MghQdFX --- .../reference-export-drift-gate/plan.md | 64 +++++++++-- .../scope-amendment.md | 106 ++++++++++++++++++ 2 files changed, 158 insertions(+), 12 deletions(-) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md index 33769d83c3..9dde172af1 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md @@ -1,5 +1,12 @@ # Plan: reference-export-drift-gate +> **AMENDED — coordinator scope amendment SA-1, 2026-08-15T16:40:42Z.** The authoritative amendment +> record is `scope-amendment.md` in this slice directory. SA-1 authorizes exactly one additional +> **test-only** implementation path and classifies `fresh-browser` as **N/A / waived**. Where this +> plan and SA-1 conflict, **SA-1 governs**. The author's original text is preserved verbatim below +> and annotated inline as `**AMENDED (SA-1)**`; nothing is deleted, so the original reasoning stays +> readable in git history. + ## Run metadata | Field | Value | @@ -42,10 +49,22 @@ tenth implementation path. | `packages/contracts/src/application/paginated-query.ts` | Edit JSDoc only. | Change the shipped module example from the non-exporting root to `@netscript/contracts/query`. No runtime/type semantics. | | `packages/contracts/src/public/mod.ts` | **Do not edit.** | The briefed contract symbols already resolve from the root. No export addition/removal is warranted. | -No tenth implementation path is authorized. In particular, do not touch -`.llm/tools/docs/check-exports-drift_test.ts`, the Contracts reference page, any Fresh UI package -source/config, MySQL package/reference paths, `deno.lock`, doctrine/debt, central cluster state, or -another lane's worktree. If implementation needs one, stop and request rescope from the coordinator. +**AMENDED (SA-1).** A **tenth** implementation path is now authorized, **test-only**: + +| Amended path | Planned action | Per-path justification | +| --------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.llm/tools/docs/check-exports-drift_test.ts` | **Edit — test assertions only.** | S1 lands fail-closed coverage-policy semantics (D2-D5) whose refusal paths are load-bearing: empty/malformed reasons, unknown coverage modes, invented symbols, and omitted symbols must each exit nonzero. Proving that with one-off probes leaves no artifact that can fail a future CI run. Persistent test cases are the only durable proof. No product, config, or generated file may be edited under this path. | + +The original prohibition stands for **everything else**: do not touch the Contracts reference page, +any Fresh UI package source/config, MySQL package/reference paths, `deno.lock`, doctrine/debt, +central cluster state, or another lane's worktree. An **eleventh** path is rescope — stop and +request it from the coordinator. + +~~No tenth implementation path is authorized. In particular, do not touch +`.llm/tools/docs/check-exports-drift_test.ts`~~ (superseded by SA-1) ~~, the Contracts reference +page, any Fresh UI package source/config, MySQL package/reference paths, `deno.lock`, +doctrine/debt, central cluster state, or another lane's worktree. If implementation needs one, stop +and request rescope from the coordinator.~~ ## Locked decisions @@ -74,7 +93,7 @@ another lane's worktree. If implementation needs one, stop and request rescope f | Whether the briefed Contracts root exports need edits | resolved now | No; baseline-earned and explicitly reported. | | Whether package-source doc-lint debt should be fixed | safe to defer | Outside frozen paths; record baseline reds without weakening gates. | | Whether every mapped package should become symbol-complete now | safe to defer | This leaf makes non-complete status explicit/reasoned; unrelated prose expansion is separate scope. | -| Whether Fresh browser proof must run | coordinator decision required | See `fresh-browser` classification below. The implementation lane may not execute it. | +| Whether Fresh browser proof must run | **resolved by SA-1** | **N/A / waived.** No route/component/island/interaction behavior changes. `NOT_RUN` preserved; no runtime lease. | No unresolved decision besides the coordinator-owned browser classification would force source rework. Browser classification affects evidence only, not implementation design. @@ -94,8 +113,12 @@ rework. Browser classification affects evidence only, not implementation design. - the `/query` import in shipped Contracts JSDoc. - Proves: direct drift command raw exit 0 only after all six Fresh UI entrypoints and the curated symbol boundary reconcile; the existing negative-fixture test still proves an added entrypoint is - red. One-off negative policy probes must report nonzero for empty reasons/unknown modes; they are - recorded as diagnostic evidence because the frozen surface forbids editing the test file. + red. ~~One-off negative policy probes must report nonzero for empty reasons/unknown modes; they are + recorded as diagnostic evidence because the frozen surface forbids editing the test file.~~ + **AMENDED (SA-1):** those negative policy cases become **persistent test cases** in + `.llm/tools/docs/check-exports-drift_test.ts` — empty/malformed reason, unknown coverage mode, + invented symbol, and omitted symbol must each be asserted nonzero by the committed test, so the + refusal paths can fail a future CI run rather than only this author's terminal. - Slice review: confirm exclusions classify real exported symbols only, each reason is substantive, Dropzone remains visibly non-exported, and no Contracts runtime/export changes entered the diff. @@ -132,7 +155,7 @@ is `NOT FIRED`. | Order | Gate | Classification and evidence | | ----- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | Focused checker test | Run `.llm/tools/docs/check-exports-drift_test.ts` unchanged; existing negative export fixture must pass. Add recorded one-off negative probes for invalid coverage policy and invented/omitted Fresh symbols; no scratch under measured roots. | +| 1 | Focused checker test | **AMENDED (SA-1):** the existing negative export fixture must still pass, and the invalid-coverage-policy and invented/omitted-symbol cases are added as **committed test cases** in `.llm/tools/docs/check-exports-drift_test.ts` rather than one-off probes. Assertions only — no product/config/generated edit under this path; no scratch under measured roots. | | 2 | Direct export drift | `deno task docs:exports-drift`; must enumerate/compare the configured surfaces and exit 0 only after reconciliation. | | 3 | `check` | Frozen contract gate via durable receipt; wrapper-backed type selection must be nonempty. | | 4 | `test` | Frozen full behavior gate via durable receipt, including docs/tool/workflow tests selected by the repository task. | @@ -149,7 +172,14 @@ resource cleanup is planned. ## `fresh-browser` classification and request -**Status: NOT FIRED — this lane is not authorized to execute it.** +**AMENDED (SA-1) — RESOLVED: `fresh-browser` is classified N/A / WAIVED for this leaf.** The +coordinator accepted the author's argument below: the verified plan changes checker, docs, shipped +JSDoc, task, and workflow wiring only, and no route, component, island, CSS, or interaction +behavior. **`NOT_RUN` evidence is preserved and reported as `NOT_RUN`** — it is never restated as a +pass — and **no runtime lease is acquired**. Aspire, Docker, browsers, and `e2e:cli` remain +prohibited in this lane. + +**Original author status: NOT FIRED — this lane is not authorized to execute it.** If granted, `fresh-browser` would prove only that the edited reference page builds/renders with usable headings, anchors, tables, code blocks, and responsive presentation in the real Fresh docs @@ -215,13 +245,23 @@ static prerequisite, never permission to publish. - MySQL/#1293/#1112 paths and acceptance. - Symbol-complete prose expansion for unrelated entrypoint-only package mappings; their policy must become explicit in this leaf, but their pages do not enter scope. -- New/edited tests outside the frozen paths, dependency/version/catalog/lock changes, doctrine/debt, - central milestone state, issue checkbox mutation, merge, publish, ready flip, or release work. +- New/edited tests outside the frozen paths **except** the single path authorized by SA-1, + `.llm/tools/docs/check-exports-drift_test.ts` (test assertions only); dependency/version/catalog/ + lock changes, doctrine/debt, central milestone state, issue checkbox mutation, merge, publish, + ready flip, or release work. - Aspire, Docker, browser execution, `e2e:cli`, scaffold/static/runtime smokes. ## PLAN-EVAL judgement -**Fresh PLAN-EVAL: REQUIRED, but not granted or performed by this author.** +**AMENDED (SA-1) — GRANTED.** The coordinator accepted the author's judgement and granted **exactly +one** fresh PLAN-EVAL cycle 1, run in a **separate session** over the **amended immutable head** +after this amendment passes a fresh Tier-A. Route: native **Fable 5 / medium / Remote Control**, +**artifact-only** — the evaluator writes `plan-eval.md` and nothing else. On `PASS` the preserved +original Codex author resumes through the serial slices, each followed by a fresh Tier-A gate. A +`FAIL_PLAN` is reported as `FAIL_PLAN`. + +**Original author judgement: Fresh PLAN-EVAL: REQUIRED, but not granted or performed by this +author.** The implementation volume is bounded, but the plan is decision-heavy: it changes what a green cross-package documentation gate means, introduces a reason-bearing omission contract, must separate diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md new file mode 100644 index 0000000000..7f10955c2e --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md @@ -0,0 +1,106 @@ +# Scope amendment SA-1 — `reference-export-drift-gate` (#1666 / closes #1296) + +| Field | Value | +| -------------------- | ------------------------------------------------------------------------------------ | +| Amendment ID | `SA-1` | +| Recorded (UTC) | `2026-08-15T16:40:42Z` | +| Authority | coordinator `codex-root-0.0.7`, relayed through the owner | +| Recorded by | `topic-internals-0.0.7`, Claude session `f7691917-0be2-4bcd-8839-43d3fc809c34` | +| Amends | `plan.md` (inline `AMENDED (SA-1)` annotations) at planning head `9d0b4bf12` | +| Leaf / lane | `reference-export-drift-gate`, wave 2 internals | +| Branch / base | `fix/reference-export-drift-gate` / `baf1cdf67a4e931af17b4772ddf6101f36152184` | +| Status | in force; governs wherever it conflicts with `plan.md` | + +This is a **control-plane** record. It changes authorized scope and gate classification. It changes +no implementation decision in `plan.md` (D1-D11 stand unmodified), and it does **not** grant merge, +publish, ready-flip, relabel, issue-closure, milestone, or release-writer authority. + +## A1 — Tenth implementation path AUTHORIZED (test-only) + +``` +.llm/tools/docs/check-exports-drift_test.ts +``` + +The frozen contract in central `leaf-contracts.json` lists **nine** `fileSurfaces`. This tenth path +is authorized in addition to them, under these bounds: + +- **Test assertions only.** No product, config, or generated file may be edited under this path. It + is not a licence to reach any other unfrozen file. +- The **existing** negative export fixture (`drift checker negative fixture validation`) must keep + passing; SA-1 adds cases, it does not license rewriting or weakening what is already there. +- An **eleventh** path remains rescope: stop and request it. + +**Why.** S1 lands fail-closed coverage-policy semantics (D2-D5) whose refusal paths are the +load-bearing part of the change — empty or malformed reasons, unknown coverage modes, invented +symbols, and omitted symbols must each exit nonzero. `plan.md` originally routed those to one-off +negative probes recorded as diagnostic evidence, explicitly "because the frozen surface forbids +editing the test file." A probe run once in an author's terminal leaves no artifact that can fail a +future CI run. This leaf exists to remove exactly that defect — a gate reporting green over code it +never examined — so proving its own refusal paths with non-persistent evidence would reproduce the +defect inside the fix. Persistent test cases are the only durable proof. + +**Minimum coverage this path must carry:** empty/malformed reason, unknown coverage mode, invented +symbol, omitted symbol — each asserted nonzero by the committed test. + +## A2 — `fresh-browser` classified N/A / WAIVED + +The frozen contract lists `fresh-browser` among `provingGates`. It is now classified **N/A / +waived** for this leaf. + +**Why.** The verified plan changes checker logic, documentation prose, shipped JSDoc, task wiring, +and workflow wiring only. No route, component, island, CSS, interaction, loading/error state, or +application workflow changes. The `frontend` overlay is present because Fresh UI is the *documented +package*, not because browser behavior is modified. + +**Obligations that survive the waiver:** + +- `NOT_RUN` evidence is **preserved and reported as `NOT_RUN`**. A waiver is not a pass, and the + gate must never be restated as green. +- **No runtime lease is acquired.** Aspire, Docker, browsers, `e2e:cli`, scaffold runtime, service + runtime, publish, release cut, and resource cleanup remain prohibited in this lane. + +## A3 — PLAN-EVAL cycle 1 GRANTED (one cycle, after fresh Tier-A) + +| Field | Value | +| ------------- | ---------------------------------------------------------------------------- | +| Cycles | exactly **one** (cycle 1 of 2) | +| Precondition | this amendment passes a **fresh Tier-A** supervisor review | +| Target | the **amended immutable head** produced by the commit carrying SA-1 | +| Session | **fresh and separate** from the author session | +| Route | native **Fable 5**, effort **medium**, Remote Control attached | +| Output | **artifact-only** — writes `plan-eval.md` in this slice directory and nothing else | +| On `PASS` | the **preserved original Codex author** resumes through the plan's serial slices, each followed by a fresh Tier-A gate | +| On `FAIL_PLAN`| reported as `FAIL_PLAN`; not worked around, not re-run without a grant | + +The evaluator does not merge, relabel, flip the PR to ready, close issues, mutate central cluster +state, or edit any implementation path. + +## A4 — Sequencing + +`#1666` sequences **before** `#1533 jsdoc-example-compile-gate`. #1533 introduces an example-compiler +gate that would go red on `packages/contracts/src/application/paginated-query.ts:6` — the very JSDoc +import this leaf corrects. Landing #1533 first would knowingly ship a red gate against an +already-identified defect. + +## A5 — Central-state reconciliation is owed upstream + +Central `leaf-contracts.json` is **coordinator-owned** and still freezes nine `fileSurfaces` for this +leaf. This lane does not edit it. SA-1 is the leaf-local record of the authorized tenth path and the +gate classification, committed and pushed on the leaf branch so it forms part of the immutable head +the evaluator reads. The reconciliation of central state against SA-1 is reported upstream and +remains the coordinator's to perform. Topic-side record: `drift.md` in the topic orchestration run +directory. + +## What SA-1 does not change + +- Every locked decision D1-D11 in `plan.md`, including D5 ("exclusions must never compensate for + parser defects") and D11 ("do not tune the checker to baseline green — a real red after wiring is + reported red"). +- The nine frozen paths and their per-path actions, including `docs/exports` (**do not create**), + `contract-primitives.ts` (**do not edit**), and `src/public/mod.ts` (**do not edit**). +- The remaining proving gates: `check`, `test`, `publish-dry-run`, `quality-job`, `arch-check`, + `docs-source-format`, `docs-accuracy`, and the JSR audit obligations. +- Evidence discipline: raw exit codes read unpiped, an empty selection is a refusal rather than a + pass, a command that did not fire is `NOT FIRED`, and scratch stays out of measured roots. +- The prohibition on merge, publish, ready flip, relabel beyond the leaf's own `status:`, issue + closure, milestone change, central-state mutation, and touching another lane's worktree. From 5d229e0f399fdafa4e9b8194d0ce8e57c158e5e2 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 18:52:23 +0200 Subject: [PATCH 04/23] eval(plan): PLAN-EVAL cycle 1 FAIL_PLAN for reference-export-drift-gate Verdict over immutable head a3f6b87b599e778db950daf6ccaecd847c088d19: FAIL_PLAN. Blocking B1: three more shipped Contracts JSDoc examples import from a non-exporting root (transform-helpers.ts:6, schemas/filters.ts:6, schemas/pagination.ts:6), all outside the frozen surface; row 1 of #1296 is not baseline-earned as stated and Closes #1296 cannot stand without a coordinator scope/closure decision. All other load-bearing claims re-derived and hold; fresh-browser stays NOT_RUN. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01DcmCJnvESF3a4nVDvUR8u8 --- .../reference-export-drift-gate/plan-eval.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md new file mode 100644 index 0000000000..c85da2ac01 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md @@ -0,0 +1,197 @@ +# PLAN-EVAL — release-0.0.7-internals--orchestration/slices/reference-export-drift-gate + +## Verdict block + +| Field | Value | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Evaluated head | `a3f6b87b599e778db950daf6ccaecd847c088d19` (asserted via `git rev-parse HEAD`, match) | +| Base | `baf1cdf67a4e931af17b4772ddf6101f36152184` | +| PR / issue | #1666 (draft) / closes #1296 | +| Cycle | **1 of 2** | +| Evaluator session | Claude Code session `68c31fcc-f93b-496f-8c0b-10e6736dded7` (background job `68c31fcc`) | +| Route | native Claude **Fable 5** / effort **medium** (`formal_plan_evaluation`, opposite family) | +| Artifacts evaluated | `plan.md` (as amended), `scope-amendment.md` (SA-1, governs on conflict), `research.md`, `implement.md`, frozen `leaf-contracts.json` entry (read-only) | +| Surface / archetype | frozen `6 — CLI / Tooling`; overlays `frontend`, `docs` | +| **Verdict** | **`FAIL_PLAN`** | + +One blocking finding (B1). Everything else re-derived below holds. Nothing outside this file was +written; no gate other than the read-only checks listed here was fired; `fresh-browser` stays +`NOT_RUN`. + +## Blocking finding + +### B1 — acceptance row 1 is materially less satisfied than research/plan/SA-1 state; three more shipped Contracts JSDoc examples import from a non-exporting root, all outside the frozen surface + +The plan (F3/F4, D8, "Explicit deferrals") and PR body assert that #1296 row 1 +(_"`packages/contracts` JSDoc examples import from the subpath that actually exports the symbols; a +reader copying them gets code that compiles"_) is baseline-earned except for `paginated-query.ts:6`. +I enumerated **every** `from '@netscript/contracts…'` line in shipped Contracts sources and checked +each imported symbol against the root with `deno doc --filter` (exit 1 = `Node … was not found!`): + +```text +grep -rnoE "from '@netscript/contracts[^']*'" packages/contracts --include=*.ts --include=*.tsx | grep -v _test + packages/contracts/crud/create-crud-contract.ts:6,250 -> '@netscript/contracts/crud' (correct) + packages/contracts/src/application/contract-primitives.ts:72,112,144 -> '@netscript/contracts' (correct; baseContract/BaseContractRoute/BaseContractOutputRoute all root EXIT=0) + packages/contracts/src/application/paginated-query.ts:6 -> '@netscript/contracts' (WRONG — plan already covers) + packages/contracts/src/application/transform-helpers.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + packages/contracts/schemas/filters.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + packages/contracts/schemas/pagination.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + +deno doc --no-lock --filter createTransformer packages/contracts/mod.ts -> EXIT=1 ; on transform.ts -> EXIT=0 +deno doc --no-lock --filter FilterConditionSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter buildPrismaWhere packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter PaginationInputSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter createPaginatedOutput packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter paginatedQuery packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +``` + +All three additional files are in the publish set (`packages/contracts/deno.json` `publish.include` +has `src/**/*.ts` and `schemas/**/*.ts`), so they ship JSDoc a reader cannot copy — the same class +of defect as `paginated-query.ts:6`, in three more places. + +Why this blocks the plan rather than the implementation: + +1. `research.md` F3/F4 and `plan.md` D8 / "Explicit deferrals and non-scope" record row 1 as + already-correct apart from one file. That statement is false, so the "reconcile row 1 honestly + and visibly" obligation from the brief cannot be met by the plan as written. +2. `plan.md` locks `Closes #1296`. Merging under this plan would auto-close an issue whose row 1 is + still unmet in three shipped files. +3. The three files are **outside the frozen nine (+1) paths**. Fixing them needs a coordinator + rescope; declining to fix them needs a coordinator decision on closure. Either way this is not a + decision the author may take alone, and it is not "safe to defer" — it changes what the PR may + honestly claim to close. That is an unflagged open decision under `gates/plan-gate.md` + ("Open-decision sweep" / "Deferred scope explicit"). +4. SA-1 A4's sequencing rationale ("#1533's example-compile gate would go red on + `paginated-query.ts:6` — the very JSDoc import this leaf corrects") is incomplete: #1533 would go + red on the three files above as well, so landing #1666 first does not prevent that red. + +**Required fix (author, then coordinator decision):** + +- Update `research.md` (F3/F4) with the full nine-line import inventory above and its `deno doc` + evidence; correct `plan.md` D8, the row-1 statement in the "Live acceptance contract" table, and + the deferrals section so that row 1 is recorded as **partially** satisfied at baseline with the + residual named file-by-file. +- Resolve, in `plan.md`, one of: + - (a) request from the coordinator a **JSDoc-only** scope amendment for + `packages/contracts/src/application/transform-helpers.ts`, + `packages/contracts/schemas/filters.ts`, `packages/contracts/schemas/pagination.ts` (edit + surface: the `@example` import line only; same publish-delta treatment as `paginated-query.ts` + in the JSR table), and add them to S1 and to validation row 11's path audit; **or** + - (b) keep the frozen surface, state explicitly that row 1 remains **unmet** for those three files + after this leaf, and have the coordinator decide whether `Closes #1296` stands (it should not + without (a) or a follow-up issue that the PR references without a closing keyword). +- Update the SA-1 A4 rationale (or add an SA-2 note) so the #1533 sequencing argument reflects all + four affected files, not one. + +I did not perform any of this. It is a coordinator scope decision. + +## Verified claims (re-derived, not trusted) + +| # | Claim | Result | Evidence | +| -------- | ------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| A1 | Checker real and passing | **holds** | `deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts` → `DRIFT_RAW_EXIT=0`, `Exports & Symbols drift check: PASS` | +| A1 | "wired to nothing" | **false, as research says** | `grep -rnE 'check-exports-drift\|exports-drift' deno.json .github/workflows/` → `EXIT=1` (no hits). But `.llm/tools/docs/check-accuracy-and-discoverability.ts:292-301` spawns `deno run --allow-all .llm/tools/docs/check-exports-drift.ts`, throws on nonzero child code; `deno.json:85` `docs:accuracy` runs that script (`--allow-run=deno`), `deno.json:90` `docs:maintenance` includes `docs:accuracy`; `.llm/tools/gates/catalog.ts:59` maps `docs-accuracy` → `deno task docs:accuracy`. `deno task docs:accuracy` → `ACCURACY_RAW_EXIT=0`, terminal `docs accuracy: PASS`. No workflow runs `docs:accuracy`/`docs:maintenance`/`docs-accuracy` (`grep … .github/workflows/` → `EXIT=1`). Research F1 is accurate; the missing pieces (named task, workflow step, runbook) are correctly identified. | +| A3 | Row 1 baseline-satisfied for the four Step-0 symbols | **holds for those four**, but see B1 | `deno doc --filter` on `packages/contracts/mod.ts`: `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, `OffsetPaginationQuerySchema` all `EXIT=0`; `contract-primitives.ts:72,112,144` import from root. | +| F4 | `paginatedQuery` absent from root, present on `/query` | **holds** | root filter `EXIT=1` (`Node paginatedQuery was not found!`); `query.ts` filter `EXIT=0`, its own JSDoc uses `@netscript/contracts/query`. `paginated-query.ts:6` still imports from root at head. | +| F5 | Six Fresh UI entrypoints, 28/11/35/82/16/7 symbols, 168 union | **holds exactly** | scratch `.llm/tmp/pe-count.ts` (outside measured roots) using `deno doc --no-lock --json` per `deno.json.exports` entry → `{".":28,"./ai/render-ui":11,"./desktop":35,"./interactive":82,"./primitives":16,"./registry":7} UNION 168`, zero `declarationKind: 'private'` nodes. | +| F6 | Forcing symbol checking today: 168 / 78 / 162 | **holds exactly** | scratch `.llm/tmp/pe-f6.ts` importing the checker's own `parseDocContent`/`checkSymbolsDrift` → `EXPECTED 168 DOCUMENTED_PARSE 78 ERRORS 162` = 126 OMITS + 36 INVENTS. The 36 invented names are the prop/field/generic artifacts research lists (`columns, rows, label, class, [attribute: string], key, header, width, cell, render, DataGridColumn, DataGridProps, DataGridRow, hint, icon, active, accept, multiple, onFile, onFiles, onReject, onDrop, onDragOver, onPaste, children, DROPZONE_*, Dropzone*, ShowProps, layout, viz, data`). Parser at `check-exports-drift.ts:270-283` does take the first backticked cell of every table row. | +| D5 | `Symbol`-header boundary safe for already-complete pages | **holds** | Header cells in `docs/site/reference/{config,contracts,telemetry,fresh-ui}/index.md`: config 13×`Symbol`+1×`Export`; contracts 12×`Symbol`+1×`Export`; telemetry 9×`Symbol` (padded, trims to `Symbol`)+1×`Export`; fresh-ui 10×`Symbol` plus `Prop`/`Shape`/`Field`/`Category`/… tables (the false-positive sources). Restricting to `Symbol`-headed tables will not create false reds on Config/Contracts/Telemetry — provided the header match is applied after `trim()`. | +| D4 | Dropzone types are in a `Symbol`-headed table | **holds** | `fresh-ui/index.md:153-161`; prose at 125-126 labels Dropzone copy-source / not a package export. | +| F2 | `docs/exports` absent, no history | **holds** | `test -e docs/exports` → `EXIT=1`; `git ls-tree -r --name-only baf1cdf67 -- docs/exports` → 0 paths. | +| F8 | Pages triggers already cover the edit surface | **holds** | `pages.yml:6-22,25-41` include `docs/site/**`, `packages/**`, `plugins/**`, `.llm/tools/docs/**`, `deno.json`. Note the `classify` job can skip the build by policy (`ci-classify-changes.ts`); root `deno.json` **tasks-only** changes → `pages:false`, package source/`packages/*/deno.json` changes → `pages:true`, `.llm/tools/docs/**` → `pages:true`. So a drift step in the build job fires for every input that can change export truth. | +| SA-1 T4 | Existing test passes | **holds** | `deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts` → `TEST_RAW_EXIT=0`, `1 passed \| 0 failed`. The single test exercises pure functions (`deriveExpectedExports`/`parseDocContent`/`checkExportsDrift`), not process exit. | +| Contract | Nine `fileSurfaces`, `fresh-browser` in `provingGates` | **holds** | `leaf-contracts.json` entry `reference-export-drift-gate` lines 1129-1149. Divergence from SA-1 is real and is upstream's. | +| Head | Branch diff vs base | **plan-only** | `git diff --name-status baf1cdf67 a3f6b87b5` → four added `.llm/runs/...` files only. | + +## Judgement on the eight questions + +1. **A1** — see table. Not "wired to nothing"; wired indirectly and fail-closed via `docs:accuracy`. + Nothing missed beyond what research F1 records; no workflow runs it. Plan's S2 is the right + remediation and does not claim prior work. +2. **A3** — the four Step-0 symbols hold; `paginatedQuery` is real; **three further files were + missed** (B1). +3. **`paginated-query.ts:6`** — confirmed with `deno doc`. +4. **D5 / D2-D4** — false positives are real and reproduced to the digit. The discriminated policy + makes a skipped symbol gate a config-level machine-readable fact (mode + mandatory nonempty + reason, refusal on empty/unknown). D5 fixes the parser first; D4's `documentedNonExports` is a + reason-bearing allow-list for a table the page itself labels non-export — it does not compensate + for a parser defect and does not weaken invented-symbol detection globally. Acceptable. Two + non-blocking gaps: N2 (report), N3 (test seam). +5. **D11** — executable. Real reds surface as `OMITS`/`INVENTS`; the legitimate outlets are + documenting the symbol or an audited reason-bearing omission group, and Tier-A reviews every + group. But S1's proof line reads "direct drift command raw exit 0 only after … reconcile", which + pressures toward green; N1 asks the plan to state that an honest residual red at S1 is reported + red, not tuned away. +6. **SA-1 justification** — a persistent test is required: the refusal paths are the load-bearing + semantics and a one-off probe cannot fail CI. The path is bounded to assertions. It is sufficient + for the four named refusal cases only if the checker exposes a seam the test can drive without + editing product code (N3). +7. **`fresh-browser` waiver** — correct. `catalog.ts:55` maps it to `deno task test:browser` = + `packages/fresh/deno.json:26` → `packages/fresh/tests/form-navigation_browser.ts`, a browser test + of `@netscript/fresh` form navigation. Nothing in the ten paths touches `packages/fresh`, any + route/island/component/CSS. Tier-A's caveat (the rewritten page is Lume-rendered) is about the + docs build, which Pages already covers via `deno task build` (`check:source-format` → lume → + `check:rendered-output`), not about `fresh-browser`. Not run; remains `NOT_RUN`. +8. **Four live rows** — rows 2, 3, 4 (Fresh UI repair, machine-readable omissions, runbook + wiring) + are closed by S1/S2 as designed. Row "Contracts inventory advertises no non-exports" (issue row + 2) is closed by the JSDoc fix plus the already-green reference page. Issue row 1 is **not** + honestly reconciled — B1. + +## Plan-Gate checklist + +| Plan-Gate item | Result | Evidence / location | +| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Research present and current | FAIL | `research.md` re-baselined at head, load-bearing findings F1/F4/F5/F6 reproduce; but F3/F4's row-1 inventory is incomplete (B1). | +| Decisions locked | PASS | D1-D11 with rationale; SA-1 leaves them intact. | +| Open-decision sweep | FAIL | The three out-of-surface JSDoc files (B1) are an unflagged decision that changes what the PR may close; not safe to defer. | +| Commit slices (< 30, gate + files each) | PASS | S1-S3 ordered, files and proofs named. | +| Risk register | PASS | present; "exclusion list becomes a hiding place" mitigated by review. | +| Gate set selected | PASS | frozen gates minus waived `fresh-browser` (SA-1 A2), plus JSR audit; validation table rows 1-11. | +| Deferred scope explicit | FAIL | "The already-correct Contracts root exports and `contract-primitives.ts` JSDoc" is explicit, but the deferral list silently omits three shipped Contracts JSDoc defects that row 1 requires (B1). | +| jsr-audit surface scan (pkg/plugin) | PASS | Contracts publish delta named honestly; Fresh UI no member delta; baseline doc-lint reds recorded as red; pins verified. Under fix (a) the JSR table gains three more prose-only files in the same publish set. | + +## Open-decision sweep (evaluator-run) + +- **B1** (blocking) — fix path (a) or (b) above; coordinator's call. +- No other decision would force checker/doc rework if deferred. + +## Non-blocking findings (address in the same cycle; not required for PASS) + +- **N1 — S1 proof wording vs D11.** State in S1 that if honest reconciliation leaves a residual red, + S1 commits with the residual reported red (per implement.md "wiring a gate that then fails on + baseline is a legitimate outcome") rather than requiring exit 0 as its commit condition. +- **N2 — visible coverage report.** The policy is machine-readable in config, but the checker's + terminal `PASS` line would still be silent about which packages ran in `entrypoints-only` mode. + Have the checker print, per package, the coverage mode, reason, and omission-group counts on every + run so a green never hides five entrypoint-only packages. +- **N3 — test seam.** Name how `check-exports-drift_test.ts` will assert the four refusal cases: + export a policy validator (or make `checkDrift(mapping)` injectable) and bind `Deno.exit(1)` to it + in `main`. `AUTHORITATIVE_MAPPING` is a hardcoded const, so a subprocess test cannot inject a + malformed policy without a seam; SA-1's "asserted nonzero" needs this to be satisfiable without + touching product code beyond the in-scope checker. +- **N4 — Pages step cwd.** The checker uses `Deno.cwd()` and repo-relative paths; the + build/links/caveats steps use `working-directory: docs/site` (`docs:snippets` runs from root). The + new step must run from repo root (`deno task docs:exports-drift` with no `working-directory`), and + it must sit behind the same `if: env.RUN == 'true'` guard as the other build steps. +- **N5 — `docs:accuracy` calling the named task.** With `--allow-run=deno` the child + `deno task docs:exports-drift` is permitted; keep the child's stdout/stderr surfaced on failure as + today (`check-accuracy-and-discoverability.ts:296-300`). + +## Commands fired (all read-only; raw exits unpiped) + +```text +git rev-parse HEAD -> a3f6b87b599e778db950daf6ccaecd847c088d19 +deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts -> 0 (PASS) +grep -rnE 'check-exports-drift|exports-drift' deno.json .github/workflows/ -> 1 +grep -rn 'docs-accuracy\|docs:maintenance\|docs:accuracy' .github/workflows/ -> 1 +deno task docs:accuracy -> 0 (PASS) +deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts -> 0 (1 passed) +deno doc --no-lock --filter packages/contracts/{mod,query,transform}.ts (see B1 / A3) -> as tabulated +deno run --no-lock --allow-read --allow-run .llm/tmp/pe-count.ts -> 0 (168) +deno run --no-lock --allow-read --allow-run .llm/tmp/pe-f6.ts -> 0 (168/78/162) +test -e docs/exports -> 1 +fresh-browser -> NOT_RUN (waived, not restated) +``` + +Scratch: `.llm/tmp/pe-*.{ts,out,json}` only. No implementation, product, config, generated, plan, +research, amendment, lock, doctrine, debt, or central-state file was modified. From cb91b225d721cb7a978b5c0f450c7bcbb239cbbb Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 18:56:15 +0200 Subject: [PATCH 05/23] plan(docs): SA-1a - bind the diff audit to ten paths, not nine SA-1 authorized a tenth test-only path but left four path-count statements in plan.md reading "nine". Validation row 11 and the S3 evidence line defined the diff audit as an exact nine-path audit, so the audit gate as written would have refused the path SA-1 authorized, or pushed the author to drop the test file to keep the gate quiet -- the same coverage-versus-compliance failure this leaf exists to remove, introduced by the amendment meant to prevent it. Corrected at plan.md lines 36, 148, 171, 236, each annotated AMENDED (SA-1a). plan.md:206 ("nine private-type-ref reds") is an unrelated doc:lint baseline count and is left alone. Found by an independent Tier-A pass; the Tier-A that admitted SA-1 grepped for the authorized filename and never grepped for the count. Refs #1296 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01HqFtKQtyJcHBEn1MghQdFX --- .../codex-thread-ids.md | 16 ++++++++++++++++ .../slices/reference-export-drift-gate/plan.md | 11 +++++++---- .../scope-amendment.md | 18 ++++++++++++++++++ 3 files changed, 41 insertions(+), 4 deletions(-) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/codex-thread-ids.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/codex-thread-ids.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/codex-thread-ids.md new file mode 100644 index 0000000000..ff3381fbe6 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/codex-thread-ids.md @@ -0,0 +1,16 @@ +# refexport-1296 — Codex implementation thread +- **Thread / session id:** `01a005d2-7c9d-7dd1-b6fc-531b72dc14e4` +- **Rollout:** `/home/codex/.codex/sessions/2026/08/15/rollout-2026-08-15T16-27-55-01a005d2-7c9d-7dd1-b6fc-531b72dc14e4.jsonl` +- **Worktree:** `/home/codex/repos/netscript-007-reference-export` +- **Branch:** `fix/reference-export-drift-gate` @ `1b6d6d5c2` (NO upstream by design). +- **Push rule:** explicit refspec only — `git push origin HEAD:refs/heads/fix/reference-export-drift-gate`. +- **Requested route:** provider=openai · model=gpt-5.6-sol · effort=medium +- **Observed route:** provider=openai · model=gpt-5.6-sol · effort=medium +- **Route verdict:** matched +- **Runtime:** approval=never · sandbox=dangerFullAccess +- **Brief (staged):** `/home/codex/refexport-1296-brief.md` +## Steering (same thread — never a second send-message-v2 at this worktree) +```bash +codex exec resume 01a005d2-7c9d-7dd1-b6fc-531b72dc14e4 -- "" +``` +_Written by `.llm/tools/agentic/codex/launch-codex-slice.ts`._ \ No newline at end of file diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md index 9dde172af1..36987ef2a9 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md @@ -33,7 +33,9 @@ The leaf preserves the already-correct Contracts root exports/examples and does ## Exact narrowed edit surface (locked) -The nine frozen implementation paths are narrowed as follows. Run artifacts requested by the +The nine frozen implementation paths are narrowed as follows. **AMENDED (SA-1a):** SA-1 adds a +tenth, test-only path; the authorized surface is **nine frozen + the SA-1 tenth**, and every +path-count statement in this plan is to be read that way. Run artifacts requested by the coordinator (`research.md`, `plan.md`, and later harness evidence) are control-plane records, not a tenth implementation path. @@ -142,7 +144,8 @@ rework. Browser classification affects evidence only, not implementation design. - Files: slice run artifacts only; no implementation path edits. - Proves at the exact committed head: `check`, `test`, `publish-dry-run`, `quality-job`, `arch-check`, `docs-source-format`, and `docs-accuracy` through durable receipts; focused direct - drift and JSR evidence; exact nine-path diff audit; no lock churn. + drift and JSR evidence; exact authorized-path diff audit — **AMENDED (SA-1a):** the audit bound is + the **ten** authorized paths (nine frozen + the SA-1 test-only tenth), not nine; no lock churn. - Handoff: coordinator performs Tier-A substantive review and grants/dispatches PLAN-EVAL and later IMPL-EVAL according to the recorded gates. The author neither self-certifies nor advances the PR to ready. @@ -165,7 +168,7 @@ is `NOT FIRED`. | 8 | `docs-accuracy` | Must fire the named drift child and propagate its real exit; terminal PASS alone is accepted only with the source/task binding reviewed. | | 9 | `publish-dry-run` | Canonical workspace simulation at the exact head; proves the shipped Contracts JSDoc and isolated declarations package statically. Review member/file output; do not infer real-publish success. | | 10 | JSR audit | Re-run package audit for Contracts and reference-subject audit for Fresh UI; preserve/report sanctioned or pre-existing reds exactly. Verify exact NetScript pins from member config. | -| 11 | Git/path/lock audit | Direct raw Git commands prove only frozen implementation paths plus run artifacts changed; `docs/exports`, `deno.lock`, package export maps, and MySQL paths remain untouched. | +| 11 | Git/path/lock audit | **AMENDED (SA-1a):** direct raw Git commands prove only the **ten authorized** implementation paths (nine frozen + the SA-1 test-only tenth) plus run artifacts changed; `docs/exports`, `deno.lock`, package export maps, and MySQL paths remain untouched. | No Aspire, Docker, browser, `e2e:cli`, scaffold runtime, service runtime, publish, release cut, or resource cleanup is planned. @@ -230,7 +233,7 @@ static prerequisite, never permission to publish. | Page truth changes while hardcoded count stays green | Do not encode 168 as a permanent expected constant; derive it every run and report the measured count. | | Hidden wiring is mistaken for absent wiring | PR/research state baseline indirect edge explicitly; S2 improves discoverability/workflow coverage without claiming prior work as leaf-earned. | | Pages CI duplicates or bypasses local gate | Both edges call the same named task; `docs:accuracy` remains the local aggregate and Pages gets one direct step. | -| Workflow edit requires an unauthorized test edit | Run existing workflow tests unchanged. If they fail and require source changes outside the nine paths, stop for rescope rather than editing tests. | +| Workflow edit requires an unauthorized test edit | Run existing workflow tests unchanged. If they fail and require source changes outside the **ten authorized** paths, stop for rescope rather than editing tests. Note the SA-1 tenth path is test-assertions-only and is not a licence to edit workflow source. | | Existing package JSR/doc-lint debt is mistaken for regression or silently waived | Record baseline raw reds in research/JSR table and compare final results; do not weaken checker/audit settings or enter package source. | | Large Fresh reference edit renders poorly | Docs format/build/links are required; browser remains coordinator-classified and may be granted externally. | | Lock or package surface churn appears during validation | Direct diff audit; do not stage `deno.lock`; stop if exports, pins, versions, or unrelated publishable source changes. | diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md index 7f10955c2e..ed02e208b4 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md @@ -104,3 +104,21 @@ directory. pass, a command that did not fire is `NOT FIRED`, and scratch stays out of measured roots. - The prohibition on merge, publish, ready flip, relabel beyond the leaf's own `status:`, issue closure, milestone change, central-state mutation, and touching another lane's worktree. + +## SA-1a — correction to SA-1 (2026-08-15T16:57Z) + +SA-1 authorized the tenth path but left four path-count statements in `plan.md` reading "nine". +One of them was load-bearing: validation row 11 and the S3 evidence line defined the diff audit as +an **exact nine-path** audit, so the audit gate as written would have refused the very path SA-1 +authorized — or pushed the author to drop the test file to make the gate quiet. That is the same +coverage-versus-compliance failure this leaf exists to remove, introduced by the amendment meant to +prevent it. + +Corrected in `plan.md` at lines 36, 148, 171, and 236, each annotated `AMENDED (SA-1a)`: the +authorized surface is **ten** paths — nine frozen plus the SA-1 test-only tenth — and the diff audit +is bound to ten. The risk-register row additionally restates that the tenth path is +test-assertions-only and is not a licence to edit workflow source. `plan.md:206` ("nine +private-type-ref reds") is an unrelated `doc:lint` baseline count and is deliberately unchanged. + +Found by an independent Tier-A pass, not by the Tier-A that admitted SA-1 — that pass grepped for +the authorized filename and never grepped for the count. Recorded in the topic drift log. From 80046696e6b192c5448aba6b3b0b619faeabac21 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 19:10:57 +0200 Subject: [PATCH 06/23] plan(docs): SA-2 reconcile export drift evaluation --- .../reference-export-drift-gate/plan.md | 277 ++++++++++-------- .../reference-export-drift-gate/research.md | 175 ++++++----- .../scope-amendment.md | 179 +++++++---- 3 files changed, 376 insertions(+), 255 deletions(-) diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md index 36987ef2a9..7f4e431674 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md @@ -1,11 +1,11 @@ # Plan: reference-export-drift-gate -> **AMENDED — coordinator scope amendment SA-1, 2026-08-15T16:40:42Z.** The authoritative amendment -> record is `scope-amendment.md` in this slice directory. SA-1 authorizes exactly one additional -> **test-only** implementation path and classifies `fresh-browser` as **N/A / waived**. Where this -> plan and SA-1 conflict, **SA-1 governs**. The author's original text is preserved verbatim below -> and annotated inline as `**AMENDED (SA-1)**`; nothing is deleted, so the original reasoning stays -> readable in git history. +> **AMENDED — coordinator scope amendments SA-1/SA-1a/SA-2, 2026-08-15.** The authoritative +> amendment record is `scope-amendment.md` in this slice directory. SA-1 adds one test-only path and +> waives `fresh-browser`; SA-1a corrected that path audit; SA-2 grants exactly three +> JSDoc-import-line paths, corrects the inherited CI premise, and resolves PLAN-EVAL cycle-1 +> findings N1-N5. The live authorized implementation surface is **thirteen paths**. Where older text +> conflicts, SA-2 governs. ## Run metadata @@ -22,22 +22,30 @@ ## Goal -Make the claimed reference boundary falsifiable: correct the remaining shipped Contracts query -import, reconcile Fresh UI's reference with its six-entrypoint/168-symbol published surface, make -every symbol-coverage omission an explicit machine-readable policy decision, document the maintainer -update path, and expose/run the already-existing drift gate through named local and Pages -verification edges. +Make the claimed reference boundary falsifiable: correct all four remaining shipped Contracts +example import lines, reconcile Fresh UI's reference with its six-entrypoint/168-symbol published +surface, make every symbol-coverage omission an explicit machine-readable policy decision, document +the maintainer update path, and make the already-enforced drift gate directly discoverable through +named local and Pages verification edges. The leaf preserves the already-correct Contracts root exports/examples and does not manufacture a `docs/exports` inventory. +## Live acceptance contract + +| Live row | Baseline truth | Planned closure | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Contracts reference inventory advertises no non-exports | **Partially satisfied.** Five of nine implementation-example lines are baseline-correct (two CRUD plus three root); all four specifically briefed root symbols resolve, but four implementation examples import six symbols from a root that does not export them. | S1 changes only those four `@example` import subpaths. `Closes #1296` is honest because SA-2 covers the full measured residual, not because the baseline row was complete. | +| Fresh UI reference matches published exports | Unsatisfied: six entrypoints exist, 168 unique symbols derive live, and symbol checking is disabled. | S1 repairs the page and enables complete-mode enforcement after fixing parser false positives. | +| Intentional omissions are machine-readable | Unsatisfied: boolean `checkSymbols: false` can silently skip coverage. | S1 adds reason-bearing discriminated coverage, refusal semantics, and N2's always-visible coverage report. | +| Maintainer runbook and drift verification | Enforcement already exists fail-closed in non-draft CI through quality -> gate catalog -> `docs:accuracy` -> checker; no named direct task/Pages identity/runbook exists. | S1 documents the runbook; S2 adds named local and Pages identities while preserving, not claiming, the existing enforcement chain. | + ## Exact narrowed edit surface (locked) -The nine frozen implementation paths are narrowed as follows. **AMENDED (SA-1a):** SA-1 adds a -tenth, test-only path; the authorized surface is **nine frozen + the SA-1 tenth**, and every -path-count statement in this plan is to be read that way. Run artifacts requested by the -coordinator (`research.md`, `plan.md`, and later harness evidence) are control-plane records, not a -tenth implementation path. +The frozen contract's nine implementation paths are narrowed below. SA-1 adds one test-only path; +SA-2 adds three JSDoc-import-line-only paths. The live authorized surface is therefore **thirteen +paths**. Run artifacts requested by the coordinator are control-plane records, not implementation +paths. | Frozen path | Planned action | Per-path justification | | ----------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -51,76 +59,91 @@ tenth implementation path. | `packages/contracts/src/application/paginated-query.ts` | Edit JSDoc only. | Change the shipped module example from the non-exporting root to `@netscript/contracts/query`. No runtime/type semantics. | | `packages/contracts/src/public/mod.ts` | **Do not edit.** | The briefed contract symbols already resolve from the root. No export addition/removal is warranted. | -**AMENDED (SA-1).** A **tenth** implementation path is now authorized, **test-only**: +**SA-1.** One additional implementation path is authorized, **test-only**: -| Amended path | Planned action | Per-path justification | -| --------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Amended path | Planned action | Per-path justification | +| --------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `.llm/tools/docs/check-exports-drift_test.ts` | **Edit — test assertions only.** | S1 lands fail-closed coverage-policy semantics (D2-D5) whose refusal paths are load-bearing: empty/malformed reasons, unknown coverage modes, invented symbols, and omitted symbols must each exit nonzero. Proving that with one-off probes leaves no artifact that can fail a future CI run. Persistent test cases are the only durable proof. No product, config, or generated file may be edited under this path. | -The original prohibition stands for **everything else**: do not touch the Contracts reference page, -any Fresh UI package source/config, MySQL package/reference paths, `deno.lock`, doctrine/debt, -central cluster state, or another lane's worktree. An **eleventh** path is rescope — stop and -request it from the coordinator. +**SA-2.** Exactly three additional implementation paths are authorized, and only the published JSDoc +example import line may change: + +| Amended path | Planned action | Per-path justification | +| --------------------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `packages/contracts/src/application/transform-helpers.ts` | Edit the `@example` import subpath only. | `createTransformer` is absent from root (`EXIT=1`) and present on `/transform` (`EXIT=0`). | +| `packages/contracts/schemas/filters.ts` | Edit the `@example` import subpath only. | `FilterConditionSchema` and `buildPrismaWhere` are absent from root (`EXIT=1` each) and present on `/query` (`EXIT=0` each). | +| `packages/contracts/schemas/pagination.ts` | Edit the `@example` import subpath only. | `PaginationInputSchema` and `createPaginatedOutput` are absent from root (`EXIT=1` each) and present on `/query` (`EXIT=0` each). | -~~No tenth implementation path is authorized. In particular, do not touch -`.llm/tools/docs/check-exports-drift_test.ts`~~ (superseded by SA-1) ~~, the Contracts reference -page, any Fresh UI package source/config, MySQL package/reference paths, `deno.lock`, -doctrine/debt, central cluster state, or another lane's worktree. If implementation needs one, stop -and request rescope from the coordinator.~~ +The prohibition stands for **everything else**: do not touch the Contracts reference page, any Fresh +UI package source/config, MySQL package/reference paths, `deno.lock`, doctrine/debt, central cluster +state, or another lane's worktree. A **fourteenth** implementation path is rescope: stop and request +it from the coordinator. ## Locked decisions -| ID | Decision | Rationale | -| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| D1 | Keep package `deno.json.exports` and per-entrypoint `deno doc --json` as the sole export/symbol authority; never materialize `docs/exports`. | Avoids a second generated/handwritten inventory and preserves A1/A14 dependency direction. | -| D2 | Replace `checkSymbols` + free-standing `excludedSymbols` with a discriminated `symbolCoverage` policy. | A boolean `false` silently disables proof. A discriminant makes completeness versus deliberate entrypoint-only coverage machine-readable and exhaustively consumable. | -| D3 | `symbolCoverage` has two modes: `complete` with reason-bearing omission groups, and `entrypoints-only` with one required nonempty reason. | A skipped symbol gate is a policy fact, not absence of configuration. Empty/malformed reasons are refusal, never pass. | -| D4 | Complete-mode mappings may name reason-bearing `documentedNonExports` groups for copy-source/API-adjacent symbols that the page explicitly labels as non-package exports. | Fresh UI's Dropzone section is useful and honest. The checker must distinguish explicit copy-source docs from invented package exports without globally weakening invented-symbol detection. | -| D5 | Parse symbol inventories only from Markdown tables whose first header cell is exactly `Symbol`; ignore prop/field/shape tables, strip display generic suffixes such as ``, and retain grouped symbol-cell support. | Eliminates the measured false positives (`columns`, `label`, `layout`, generic display names) before enabling enforcement. Exclusions must never compensate for parser defects. | -| D6 | Fresh UI uses `complete` mode. Document user-facing components/functions/constants/namespaces and their public contract families; every intentionally omitted low-level member type is enumerated in sorted reason-bearing groups. | Repairs the reproduced Fresh UI surface and makes remaining curation auditable. A newly exported symbol must be documented or explicitly classified before the gate returns green. | -| D7 | Existing currently entrypoint-only mappings remain entrypoint-only only with explicit reasons; Config, Contracts, Fresh UI, and Telemetry remain/enter complete mode. | Satisfies machine-readable omission policy without pretending this leaf authored complete prose for unrelated packages. Promotion of other packages can occur independently. | -| D8 | Correct only `paginated-query.ts` to `/query`; preserve `contract-primitives.ts` and `src/public/mod.ts`. | Independent `deno doc` proves the briefed root symbols are already valid, while `paginatedQuery` is absent from root and present on `/query`. | -| D9 | Add `docs:exports-drift`; make `docs:accuracy` call it; add the same named task as a Pages build step. | Gives maintainers a fast direct command, retains the existing aggregate local/maintenance gate, and makes workflow execution explicit on already-correct triggers. No duplicate execution occurs within either path. | -| D10 | The Fresh UI runbook documents derivation, not file generation: inspect every `deno.json.exports` entry with `deno doc --json`, update the page and coverage policy, run the direct drift task, then the aggregate accuracy task. | There is no generator today. Calling a manual derived update "regeneration" is honest only when the source of truth and verification steps are explicit. | -| D11 | Do not tune the checker to baseline green. First land semantics that refuse malformed coverage, then reconcile the page/policy until the unchanged live export authority passes. | Coverage and compliance remain distinct. A real red after wiring is reported red. | +| ID | Decision | Rationale | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| D1 | Keep package `deno.json.exports` and per-entrypoint `deno doc --json` as the sole export/symbol authority; never materialize `docs/exports`. | Avoids a second generated/handwritten inventory and preserves A1/A14 dependency direction. | +| D2 | Replace `checkSymbols` + free-standing `excludedSymbols` with a discriminated `symbolCoverage` policy. | A boolean `false` silently disables proof. A discriminant makes completeness versus deliberate entrypoint-only coverage machine-readable and exhaustively consumable. | +| D3 | `symbolCoverage` has two modes, both with a required nonempty coverage reason: `complete` additionally has reason-bearing omission groups; `entrypoints-only` records why symbol comparison is deferred. | Every package can print mode + reason on every run. A skipped gate is a policy fact, not missing configuration; empty/malformed reasons refuse. | +| D4 | Complete-mode mappings may name reason-bearing `documentedNonExports` groups for copy-source/API-adjacent symbols that the page explicitly labels as non-package exports. | Fresh UI's Dropzone section is useful and honest. The checker must distinguish explicit copy-source docs from invented package exports without globally weakening invented-symbol detection. | +| D5 | Parse symbol inventories only from Markdown tables whose first header cell is exactly `Symbol`; ignore prop/field/shape tables, strip display generic suffixes such as ``, and retain grouped symbol-cell support. | Eliminates the measured false positives (`columns`, `label`, `layout`, generic display names) before enabling enforcement. Exclusions must never compensate for parser defects. | +| D6 | Fresh UI uses `complete` mode. Document user-facing components/functions/constants/namespaces and their public contract families; every intentionally omitted low-level member type is enumerated in sorted reason-bearing groups. | Repairs the reproduced Fresh UI surface and makes remaining curation auditable. A newly exported symbol must be documented or explicitly classified before the gate returns green. | +| D7 | Existing currently entrypoint-only mappings remain entrypoint-only only with explicit reasons; Config, Contracts, Fresh UI, and Telemetry remain/enter complete mode. | Satisfies machine-readable omission policy without pretending this leaf authored complete prose for unrelated packages. Promotion of other packages can occur independently. | +| D8 | Correct the example import line in `paginated-query.ts` to `/query`, `transform-helpers.ts` to `/transform`, and `schemas/filters.ts` plus `schemas/pagination.ts` to `/query`; preserve `contract-primitives.ts` and `src/public/mod.ts`. | Independent `deno doc` proves the briefed root symbols are valid and all six residual symbols are absent from root but present on the ruled subpaths. All changes are shipped JSDoc prose only. | +| D9 | Add `docs:exports-drift`; make `docs:accuracy` call it; add the same named task as an explicit Pages build step. | Improves the direct discoverability of a gate already enforced fail-closed through non-draft CI quality, while retaining the aggregate and avoiding duplicate execution within either path. | +| D10 | The Fresh UI runbook documents derivation, not file generation: inspect every `deno.json.exports` entry with `deno doc --json`, update the page and coverage policy, run the direct drift task, then the aggregate accuracy task. | There is no generator today. Calling a manual derived update "regeneration" is honest only when the source of truth and verification steps are explicit. | +| D11 | Do not tune the checker to baseline green. First land semantics that refuse malformed coverage, then reconcile the page/policy until the unchanged live export authority passes. | Coverage and compliance remain distinct. A real red after wiring is reported red. | ## Open-decision sweep -| Decision | Status | Resolution | -| -------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------- | -| Whether `docs/exports` should be created | resolved now | No; stale frozen entry, explicitly non-touched. | -| Machine-readable omission format | resolved now | D2-D4 discriminated, reason-bearing mapping policy. | -| Symbol-table parser boundary | resolved now | D5 exact `Symbol` header plus display-name normalization. | -| Direct task versus aggregate versus workflow wiring | resolved now | D9 combination: named task, existing accuracy/maintenance aggregate, Pages step. | -| Whether the briefed Contracts root exports need edits | resolved now | No; baseline-earned and explicitly reported. | -| Whether package-source doc-lint debt should be fixed | safe to defer | Outside frozen paths; record baseline reds without weakening gates. | -| Whether every mapped package should become symbol-complete now | safe to defer | This leaf makes non-complete status explicit/reasoned; unrelated prose expansion is separate scope. | -| Whether Fresh browser proof must run | **resolved by SA-1** | **N/A / waived.** No route/component/island/interaction behavior changes. `NOT_RUN` preserved; no runtime lease. | - -No unresolved decision besides the coordinator-owned browser classification would force source -rework. Browser classification affects evidence only, not implementation design. +| Decision | Status | Resolution | +| -------------------------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------- | +| Whether `docs/exports` should be created | resolved now | No; stale frozen entry, explicitly non-touched. | +| Machine-readable omission format | resolved now | D2-D4 discriminated, reason-bearing mapping policy. | +| Symbol-table parser boundary | resolved now | D5 exact `Symbol` header plus display-name normalization. | +| Direct task versus aggregate versus workflow discoverability | resolved now | D9 combination: named task, already-enforced accuracy/maintenance aggregate, explicit Pages step. | +| Whether the briefed Contracts root exports need edits | resolved now | No; baseline-earned. Four other shipped import lines are repaired under SA-2. | +| Whether the three PLAN-EVAL-discovered files may change | resolved by SA-2 | Yes, exactly the `@example` import subpath; no runtime/type/export/schema edits. | +| Whether package-source doc-lint debt should be fixed | safe to defer | Outside frozen paths; record baseline reds without weakening gates. | +| Whether every mapped package should become symbol-complete now | safe to defer | This leaf makes non-complete status explicit/reasoned; unrelated prose expansion is separate scope. | +| Whether Fresh browser proof must run | **resolved by SA-1** | **N/A / waived.** No route/component/island/interaction behavior changes. `NOT_RUN` preserved; no runtime lease. | + +No unresolved implementation decision remains. `fresh-browser` is already N/A/waived; PLAN-EVAL +cycle 2 remains a coordinator-owned gate, not an author assumption. ## Ordered implementation slices ### S1 — make reference coverage explicit and reconcile the live surfaces - Files: `.llm/tools/docs/check-exports-drift.ts`, `docs/site/reference/fresh-ui/index.md`, - `packages/contracts/src/application/paginated-query.ts`, and slice run artifacts. + `.llm/tools/docs/check-exports-drift_test.ts`, + `packages/contracts/src/application/paginated-query.ts`, + `packages/contracts/src/application/transform-helpers.ts`, + `packages/contracts/schemas/filters.ts`, `packages/contracts/schemas/pagination.ts`, and slice run + artifacts. - Introduces: - the discriminated reason-bearing coverage policy and fail-closed validation; + - **N2:** an unconditional per-package coverage report on every run containing coverage mode, the + reason (including complete-mode rationale), and omission-group counts, before the terminal + verdict, so `PASS` cannot hide entrypoint-only packages; + - **N3:** an injectable, exported `checkDrift(mapping: AuthoritativeMapping): Promise` + seam. It validates the supplied mapping and returns nonzero for malformed policy or drift; the + `if (import.meta.main)` guard passes `AUTHORITATIVE_MAPPING` and binds process status with + `Deno.exit(await checkDrift(AUTHORITATIVE_MAPPING))`. Tests import `checkDrift` and pass invalid + fixture mappings directly without triggering `main`, so the hardcoded production constant does + not make the four refusal cases untestable; - table-aware symbol parsing and generic normalization; - Fresh UI complete-mode enforcement, documented non-export classification, and exact omission groups; - repaired Fresh UI reference sections and the maintainer derivation/update runbook; - - the `/query` import in shipped Contracts JSDoc. -- Proves: direct drift command raw exit 0 only after all six Fresh UI entrypoints and the curated - symbol boundary reconcile; the existing negative-fixture test still proves an added entrypoint is - red. ~~One-off negative policy probes must report nonzero for empty reasons/unknown modes; they are - recorded as diagnostic evidence because the frozen surface forbids editing the test file.~~ - **AMENDED (SA-1):** those negative policy cases become **persistent test cases** in - `.llm/tools/docs/check-exports-drift_test.ts` — empty/malformed reason, unknown coverage mode, - invented symbol, and omitted symbol must each be asserted nonzero by the committed test, so the - refusal paths can fail a future CI run rather than only this author's terminal. + - the corrected import subpaths in all four shipped Contracts JSDoc examples. +- Proves: the existing negative export fixture remains green, while empty/malformed reason, unknown + coverage mode, invented symbol, and omitted symbol fixture mappings each make the injected + `checkDrift` result nonzero. The direct drift command reports the honestly reconciled live state. +- **N1:** raw exit 0 is not an S1 commit condition. If honest reconciliation leaves a residual red, + S1 is committed with that residual reported **red**, including the exact omissions/inventions and + raw exit. It is never tuned away or withheld merely to manufacture green; D11 governs. - Slice review: confirm exclusions classify real exported symbols only, each reason is substantive, Dropzone remains visibly non-exported, and no Contracts runtime/export changes entered the diff. @@ -131,21 +154,29 @@ rework. Browser classification affects evidence only, not implementation design. - Introduces: named least-permission `docs:exports-drift` task, aggregate invocation from `docs:accuracy`, and a named Pages verification step. - Proves: - - direct search now finds explicit task/workflow wiring; + - direct search now finds the task and Pages identity, while the record continues to attribute + pre-existing non-draft CI enforcement to the quality/catalog/accuracy chain; - `deno task docs:exports-drift` and `deno task docs:accuracy` each return raw exit 0; - Pages workflow tests and source-format gates remain green; - a controlled drift diagnostic makes the named task nonzero and therefore would fail both aggregate and workflow edges. No product file is left modified after the diagnostic. -- Slice review: ensure the task executes once per path, child stdout/stderr remain visible on - failure, permissions are no broader than required, and workflow triggers were not widened. +- **N4:** the Pages step is `deno task docs:exports-drift` from repository root (no + `working-directory`) because the checker resolves repo-relative paths from `Deno.cwd()`. It sits + behind the same `if: env.RUN == 'true'` guard as the other build steps. +- **N5:** `docs:accuracy` invokes the named task through the existing `--allow-run=deno` permission. + Its child handling continues to decode and print both stdout and stderr before throwing on + nonzero, exactly preserving the current failure visibility at + `check-accuracy-and-discoverability.ts:296-300`. +- Slice review: ensure the task executes once per path, N4/N5 hold, permissions are no broader than + required, and workflow triggers were not widened. ### S3 — history-bound contract and publication evidence - Files: slice run artifacts only; no implementation path edits. - Proves at the exact committed head: `check`, `test`, `publish-dry-run`, `quality-job`, `arch-check`, `docs-source-format`, and `docs-accuracy` through durable receipts; focused direct - drift and JSR evidence; exact authorized-path diff audit — **AMENDED (SA-1a):** the audit bound is - the **ten** authorized paths (nine frozen + the SA-1 test-only tenth), not nine; no lock churn. + drift and JSR evidence; exact authorized-path diff audit bound to all **thirteen** authorized + paths; no lock churn. A fourteenth implementation path is a hard rescope refusal. - Handoff: coordinator performs Tier-A substantive review and grants/dispatches PLAN-EVAL and later IMPL-EVAL according to the recorded gates. The author neither self-certifies nor advances the PR to ready. @@ -156,19 +187,19 @@ Durable merge evidence must use `.llm/tools/gates/run-gate.ts` at committed head wrapper selections must be nonempty. Raw exit codes are captured unpiped; a command that never fires is `NOT FIRED`. -| Order | Gate | Classification and evidence | -| ----- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | Focused checker test | **AMENDED (SA-1):** the existing negative export fixture must still pass, and the invalid-coverage-policy and invented/omitted-symbol cases are added as **committed test cases** in `.llm/tools/docs/check-exports-drift_test.ts` rather than one-off probes. Assertions only — no product/config/generated edit under this path; no scratch under measured roots. | -| 2 | Direct export drift | `deno task docs:exports-drift`; must enumerate/compare the configured surfaces and exit 0 only after reconciliation. | -| 3 | `check` | Frozen contract gate via durable receipt; wrapper-backed type selection must be nonempty. | -| 4 | `test` | Frozen full behavior gate via durable receipt, including docs/tool/workflow tests selected by the repository task. | -| 5 | `quality-job` | Frozen CI-quality composite; records wrapper-backed lint/fmt/dependency evidence. | -| 6 | `arch-check` | Required because published Contracts JSDoc is touched; no doctrine/debt regression. | -| 7 | `docs-source-format` | Run from the required docs-site context through the cataloged gate; proves source/Vento formatting. Also run its existing test if the coordinator's receipt set requires it, but do not substitute that extra test for the contracted gate. | -| 8 | `docs-accuracy` | Must fire the named drift child and propagate its real exit; terminal PASS alone is accepted only with the source/task binding reviewed. | -| 9 | `publish-dry-run` | Canonical workspace simulation at the exact head; proves the shipped Contracts JSDoc and isolated declarations package statically. Review member/file output; do not infer real-publish success. | -| 10 | JSR audit | Re-run package audit for Contracts and reference-subject audit for Fresh UI; preserve/report sanctioned or pre-existing reds exactly. Verify exact NetScript pins from member config. | -| 11 | Git/path/lock audit | **AMENDED (SA-1a):** direct raw Git commands prove only the **ten authorized** implementation paths (nine frozen + the SA-1 test-only tenth) plus run artifacts changed; `docs/exports`, `deno.lock`, package export maps, and MySQL paths remain untouched. | +| Order | Gate | Classification and evidence | +| ----- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Focused checker test | The existing negative export fixture must still pass. Through N3's injectable `checkDrift(mapping)` seam, committed tests assert nonzero for empty/malformed reason, unknown mode, invented symbol, and omitted symbol. Assertions only under the test path; no scratch under measured roots. | +| 2 | Direct export drift | `deno task docs:exports-drift`; must enumerate/compare configured surfaces, print N2's per-package mode/reason/omission counts every run, and report the honest exit. A residual red is preserved under N1 rather than blocking the S1 commit. | +| 3 | `check` | Frozen contract gate via durable receipt; wrapper-backed type selection must be nonempty. | +| 4 | `test` | Frozen full behavior gate via durable receipt, including docs/tool/workflow tests selected by the repository task. | +| 5 | `quality-job` | Frozen CI-quality composite; records wrapper-backed lint/fmt/dependency evidence. | +| 6 | `arch-check` | Required because published Contracts JSDoc is touched; no doctrine/debt regression. | +| 7 | `docs-source-format` | Run from the required docs-site context through the cataloged gate; proves source/Vento formatting. Also run its existing test if the coordinator's receipt set requires it, but do not substitute that extra test for the contracted gate. | +| 8 | `docs-accuracy` | Must fire the named task under `--allow-run=deno`, propagate its real exit, and surface child stdout/stderr on failure. Terminal PASS alone is accepted only with the source/task binding reviewed. | +| 9 | `publish-dry-run` | Canonical workspace simulation at the exact head; proves the shipped Contracts JSDoc and isolated declarations package statically. Review member/file output; do not infer real-publish success. | +| 10 | JSR audit | Re-run package audit for Contracts and reference-subject audit for Fresh UI; preserve/report sanctioned or pre-existing reds exactly. Verify exact NetScript pins from member config. | +| 11 | Git/path/lock audit | Direct raw Git commands prove only the **thirteen authorized** implementation paths plus run artifacts changed; `docs/exports`, `deno.lock`, package export maps, and MySQL paths remain untouched. A fourteenth implementation path refuses and requires coordinator rescope. | No Aspire, Docker, browser, `e2e:cli`, scaffold runtime, service runtime, publish, release cut, or resource cleanup is planned. @@ -192,20 +223,19 @@ Contracts import resolves; the checker, snippet/static gates, and `deno doc` own This plan judges `fresh-browser` **not genuinely required** for the frozen surface because no route, component, CSS, island, interaction, loading/error state, or application workflow changes. The frontend overlay is present because Fresh UI is the documented package, not because browser behavior -is modified. The author asks the coordinator to record an explicit waiver/N/A. If Tier-A instead -requires rendered-reference assurance, the coordinator must grant and execute the gate in an -authorized lane; that changes evidence, not scope or implementation. +is modified. SA-1 resolved the classification as N/A/waived. The implementation lane will not +request a runtime lease or execute it; the evidence remains `NOT_RUN`. ## JSR audit plan -| JSR concern | Contracts | Fresh UI reference subject | -| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| Publish delta | Shipped `paginated-query.ts` JSDoc changes; call this a publish delta even though runtime/types/exports do not. | No member file changes, but inspect all six exports before authoring the reference. | -| Export audit | `deno doc` on `.`, `./crud`, `./query`, `./transform`; assert `paginatedQuery` only from `/query` and preserve root symbols verified in research. | `deno doc --json` on all six entrypoints; 168-symbol union is checker input, not a remembered count baked into docs tooling. | -| Exact `@netscript/*` pins | None; explicitly zero rows, not "not examined." | Preserve `sdk/auto-update` and `sdk/desktop` exact at `@netscript/sdk@0.0.6`; no source/config change. | -| Documentation | Correct copyable module import. Baseline `doc:lint` has nine private-type-ref reds; report as baseline and do not claim zero. | Reference corrected. Baseline package `doc:lint` has 123 `/interactive` reds; source fix is out of scope and remains honest red. | -| Slow types / isolated declarations | `audit-jsr-package` sanctioned oRPC slow-type INFO; final canonical `publish:dry-run` required under root `isolatedDeclarations:true`. | Audit currently reports slow types plus structural warnings; no package change, no waiver invention. | -| Publish set / assets | Confirm edited JSDoc source is included by `src/**/*.ts`; no new asset/import/read. | No package file or runtime asset delta. | +| JSR concern | Contracts | Fresh UI reference subject | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| Publish delta | Shipped JSDoc text changes in `src/application/paginated-query.ts`, `src/application/transform-helpers.ts`, `schemas/filters.ts`, and `schemas/pagination.ts`; this is a publish delta even though runtime/types/exports/schemas do not change. | No member file changes, but inspect all six exports before authoring the reference. | +| Export audit | `deno doc` on `.`, `./crud`, `./query`, `./transform`; assert all six affected symbols are absent from root and present only on their ruled `/query` or `/transform` entrypoint; preserve baseline-correct root/CRUD symbols. | `deno doc --json` on all six entrypoints; 168-symbol union is checker input, not a remembered count baked into docs tooling. | +| Exact `@netscript/*` pins | None; explicitly zero rows, not "not examined." | Preserve `sdk/auto-update` and `sdk/desktop` exact at `@netscript/sdk@0.0.6`; no source/config change. | +| Documentation | Correct all four copyable implementation example imports. Baseline `doc:lint` has nine private-type-ref reds; report as baseline and do not claim zero. | Reference corrected. Baseline package `doc:lint` has 123 `/interactive` reds; source fix is out of scope and remains honest red. | +| Slow types / isolated declarations | `audit-jsr-package` sanctioned oRPC slow-type INFO; final canonical `publish:dry-run` required under root `isolatedDeclarations:true`. | Audit currently reports slow types plus structural warnings; no package change, no waiver invention. | +| Publish set / assets | Confirm the two `src/**/*.ts` and two `schemas/**/*.ts` JSDoc files are included; no new asset/runtime import/read. | No package file or runtime asset delta. | If implementation changes a public export, type signature, member dependency, version, publish filter, or any other publishable member, stop and rescope before continuing. A green dry-run is a @@ -225,23 +255,25 @@ static prerequisite, never permission to publish. ## Risk register -| Risk | Mitigation | -| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Exclusion list becomes a hiding place | Require complete mode, exact exported names, sorted reason-bearing groups, reject unknown names/empty reasons, and Tier-A review every Fresh omission. | -| Markdown parser mistakes prose tables for exports | D5 exact header boundary plus negative field/prop table probe; never quiet false positives with exclusions. | -| Duplicate symbol re-exports across root/subpaths inflate or conflict | Preserve Set de-duplication while checking every entrypoint derived from `deno.json.exports`. | -| Page truth changes while hardcoded count stays green | Do not encode 168 as a permanent expected constant; derive it every run and report the measured count. | -| Hidden wiring is mistaken for absent wiring | PR/research state baseline indirect edge explicitly; S2 improves discoverability/workflow coverage without claiming prior work as leaf-earned. | -| Pages CI duplicates or bypasses local gate | Both edges call the same named task; `docs:accuracy` remains the local aggregate and Pages gets one direct step. | -| Workflow edit requires an unauthorized test edit | Run existing workflow tests unchanged. If they fail and require source changes outside the **ten authorized** paths, stop for rescope rather than editing tests. Note the SA-1 tenth path is test-assertions-only and is not a licence to edit workflow source. | -| Existing package JSR/doc-lint debt is mistaken for regression or silently waived | Record baseline raw reds in research/JSR table and compare final results; do not weaken checker/audit settings or enter package source. | -| Large Fresh reference edit renders poorly | Docs format/build/links are required; browser remains coordinator-classified and may be granted externally. | -| Lock or package surface churn appears during validation | Direct diff audit; do not stage `deno.lock`; stop if exports, pins, versions, or unrelated publishable source changes. | +| Risk | Mitigation | +| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Exclusion list becomes a hiding place | Require complete mode, exact exported names, sorted reason-bearing groups, reject unknown names/empty reasons, and Tier-A review every Fresh omission. | +| Markdown parser mistakes prose tables for exports | D5 exact header boundary plus negative field/prop table probe; never quiet false positives with exclusions. | +| Duplicate symbol re-exports across root/subpaths inflate or conflict | Preserve Set de-duplication while checking every entrypoint derived from `deno.json.exports`. | +| Page truth changes while hardcoded count stays green | Do not encode 168 as a permanent expected constant; derive it every run and report the measured count. | +| Gate-catalog indirection is mistaken for absent enforcement | PR/research record the complete non-draft CI chain; S2 improves discoverability without claiming enforcement as leaf-earned. | +| Pages CI duplicates or bypasses local gate | Both edges call the same named task; `docs:accuracy` remains the enforced aggregate and Pages gets one root-cwd direct step under `env.RUN`. | +| Workflow edit requires an unauthorized test edit | Run existing workflow tests unchanged. If they require source changes outside the **thirteen authorized** paths, stop for rescope. The authorized checker test path is assertions-only and is not a licence to edit workflow-test source. | +| Existing package JSR/doc-lint debt is mistaken for regression or silently waived | Record baseline raw reds in research/JSR table and compare final results; do not weaken checker/audit settings or enter package source. | +| Large Fresh reference edit renders poorly | Docs format/build/links are required; browser remains coordinator-classified and may be granted externally. | +| Lock or package surface churn appears during validation | Direct diff audit; do not stage `deno.lock`; stop if exports, pins, versions, or unrelated publishable source changes. | ## Explicit deferrals and non-scope - `docs/exports` creation or any generated inventory artifact. -- The already-correct Contracts root exports and `contract-primitives.ts` JSDoc. +- The already-correct Contracts root exports, `contract-primitives.ts` JSDoc, CRUD examples, and + entrypoint self-documentation. The four incorrect implementation imports are explicitly in S1, not + deferred. - Contracts reference-page prose outside the frozen surface. - Fresh UI package source, namespace/type exports, doc-lint/slow-type/structure remediation, visual design, component behavior, CSS, or registry contents. @@ -256,22 +288,17 @@ static prerequisite, never permission to publish. ## PLAN-EVAL judgement -**AMENDED (SA-1) — GRANTED.** The coordinator accepted the author's judgement and granted **exactly -one** fresh PLAN-EVAL cycle 1, run in a **separate session** over the **amended immutable head** -after this amendment passes a fresh Tier-A. Route: native **Fable 5 / medium / Remote Control**, -**artifact-only** — the evaluator writes `plan-eval.md` and nothing else. On `PASS` the preserved -original Codex author resumes through the serial slices, each followed by a fresh Tier-A gate. A -`FAIL_PLAN` is reported as `FAIL_PLAN`. - -**Original author judgement: Fresh PLAN-EVAL: REQUIRED, but not granted or performed by this -author.** - -The implementation volume is bounded, but the plan is decision-heavy: it changes what a green -cross-package documentation gate means, introduces a reason-bearing omission contract, must separate -parser errors from real omissions, and reconciles a materially false carried-in wiring claim. -Deferring any of those decisions would force checker/doc rework. Harness policy therefore requires a -fresh separate-session opposite-family PLAN-EVAL before implementation. - -The coordinator owns the grant/dispatch and must run Tier-A on this exact pushed planning head. This -author does not assume a verdict, does not create `plan-eval.md`, and must not begin implementation -until the coordinator records `PASS`. A failure is reported as `FAIL_PLAN`, not worked around. +PLAN-EVAL cycle 1 returned **`FAIL_PLAN`** at evaluator commit `5d229e0f3`; cycle 1 is spent. The +coordinator then ruled B1 by granting the three JSDoc-only paths and ruled N1-N5 exactly as recorded +above. No implementation followed that failure. + +**Fresh PLAN-EVAL cycle 2 is REQUIRED.** The reason is material, not ceremonial: SA-2 changes the +closure-bearing Contracts scope from one residual example to all four, binds the refusal tests to an +injectable exit-code seam, makes coverage reporting unconditional, and corrects the plan's CI +enforcement premise. Those are load-bearing Plan-Gate decisions and must be evaluated on the exact +amended immutable head before any product/JSDoc edit. + +The requirement is not a grant. The coordinator must first run Tier-A on this exact pushed head and +then grant/dispatch the final separate-session cycle. This author does not assume `PASS`, does not +launch the evaluator, and does not begin implementation until PLAN-EVAL cycle 2 records `PASS`. A +second `FAIL_PLAN` is reported honestly and escalated under the two-cycle limit. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md index 9d145e8c34..642b1d1896 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md @@ -13,28 +13,31 @@ - Issue #1296 is open on milestone 27, now titled `0.0.7`. Issue #1293 remains open at `status:impl`; its MySQL paths are outside this leaf. -The carried-in measurements are partly stale. A1's direct-search observation is reproducible, but -its conclusion that the drift checker is "wired to nothing" is false at the frozen baseline. A3's -Contracts-root conclusion is correct, while a different source JSDoc import remains wrong. +The carried-in measurements are partly stale. A1's narrow name search is reproducible, but it missed +a gate-catalog indirection and a `Deno.Command` child edge: the checker is already enforced +fail-closed in non-draft CI. This was an error in the coordinator's dispatch premise, not an author +finding. A3's four named root exports are correct, but the full shipped-example inventory contains +four other source imports from entrypoints that do not export their symbols. ## Live acceptance contract Issue #1296 has five close-gated boxes. Independent re-baselining classifies them as follows: -| Issue row | Baseline state | Leaf treatment | -| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Contracts examples import from the real exporting path | already satisfied for the specifically named `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, and `OffsetPaginationQuerySchema` examples | Preserve and state as baseline-earned, not leaf-earned. A separate `paginatedQuery` module example is still wrong and belongs to the live inventory repair. | -| Contracts reference inventory advertises no non-exports | reference page/checker pass, but `paginated-query.ts` advertises `paginatedQuery` from the root where it is not exported | Correct the shipped module JSDoc to `@netscript/contracts/query`; do not edit the already-green reference page outside the frozen surface. | -| Fresh UI reference matches published exports | not satisfied | Repair against all six entrypoints and enable an explicit symbol-coverage policy. | -| Intentional omissions are machine-readable | not satisfied | Replace boolean/silent symbol coverage with a discriminated, reason-bearing policy consumed by the checker. | -| Maintainer regeneration runbook and verification wiring | partially satisfied | Preserve the existing fail-closed `docs:accuracy` edge, make it directly addressable/discoverable, add Pages CI execution, and document the update procedure. | +| Issue row | Baseline state | Leaf treatment | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Contracts examples import from the real exporting path | **partially satisfied**: five of the nine implementation-example lines are correct (two CRUD, three root); all four specifically briefed root symbols also resolve, but four implementation examples import six symbols from a root that does not export them | Preserve the baseline-earned examples and repair only the four incorrect `@example` import lines under the coordinator's JSDoc-only rescope. | +| Contracts reference inventory advertises no non-exports | manual reference page/checker pass, but the same four shipped examples advertise six symbols from non-exporting entrypoints | Correct `paginated-query.ts`, `transform-helpers.ts`, `schemas/filters.ts`, and `schemas/pagination.ts`; do not edit the already-green reference page. | +| Fresh UI reference matches published exports | not satisfied | Repair against all six entrypoints and enable an explicit symbol-coverage policy. | +| Intentional omissions are machine-readable | not satisfied | Replace boolean/silent symbol coverage with a discriminated, reason-bearing policy consumed by the checker. | +| Maintainer regeneration runbook and verification wiring | enforcement is already satisfied fail-closed in non-draft CI; direct discoverability and the runbook are absent | Preserve the enforced `docs:accuracy` chain, add a named task and explicit Pages step, and document the update procedure without claiming new enforcement. | -The four live rows in the frozen brief therefore remain meaningful, but row 4 begins from partial, -not zero, implementation. +The four live rows in the frozen brief therefore remain meaningful. Contracts reconciliation is +partly baseline-earned and partly live; the last row is a discoverability/runbook repair over an +already-enforced gate, not new enforcement. ## Findings -### F1 — direct task/workflow discovery is empty, but runtime wiring already exists +### F1 — the checker is already enforced fail-closed; its direct identity is undiscoverable The exact unpiped baseline checks were: @@ -47,19 +50,29 @@ grep -rnE 'check-exports-drift|exports-drift' deno.json .github/workflows/ WIRING_SEARCH_RAW_EXIT=1 ``` -That search cannot establish "wired to nothing" because it excludes the aggregator source. -`.llm/tools/docs/check-accuracy-and-discoverability.ts:291-301` creates a `Deno.Command('deno')` -whose argv directly runs `check-exports-drift.ts`, checks the real child exit code, and throws on -nonzero. `git blame` attributes that edge to PR #1292's merge commit `6c3b534fc`. +That search cannot establish enforcement because the workflow calls a gate id and the checker is a +child spawned from source. The independently followed baseline chain is: -`deno task docs:accuracy` also completed with raw exit 0 and printed its terminal PASS after the -awaited child edge. `docs:maintenance` invokes `docs:accuracy`, and the durable gate catalog maps -`docs-accuracy` to that task. Therefore the checker already guards local documentation accuracy and -maintenance. What is missing is: +```text +.github/workflows/ci.yml:362-367 Docs accuracy check + -> run-gate.ts --gate docs-accuracy --id quality-docs-accuracy + (quality job at :282; non-draft PR guard at :287; step guard env.RUN == 'true') + -> .llm/tools/gates/catalog.ts:59 + 'docs-accuracy' -> ['deno', 'task', 'docs:accuracy'] + -> deno.json:85 + docs:accuracy -> check-accuracy-and-discoverability.ts + -> check-accuracy-and-discoverability.ts:291-301 + spawns check-exports-drift.ts; prints child stdout/stderr and throws on nonzero +``` + +`deno task docs:accuracy` completed with raw exit 0 and printed its terminal PASS after the awaited +child edge. `docs:maintenance` also invokes `docs:accuracy`. The gate is therefore already enforced +fail-closed for qualifying non-draft CI and through the local accuracy/maintenance aggregates. What +is missing is discoverability: 1. a named `docs:exports-drift` task that maintainers and automation can discover and invoke; -2. a direct workflow execution path — Pages currently runs snippets/build/links/caveats, not export - drift or `docs:accuracy`; +2. an explicitly named Pages step — Pages currently runs snippets/build/links/caveats, while CI + quality reaches export drift only as the unnamed child of `docs:accuracy`; 3. a runbook that tells maintainers how to derive and reconcile the surface. ### F2 — `docs/exports` is a stale frozen-contract entry, not a generated target @@ -76,39 +89,49 @@ Creating `docs/exports` would introduce a third inventory that can itself drift the issue requirement not to maintain a second handwritten entrypoint list. The path will remain absent and will be named as a deliberate non-touch in the plan. -### F3 — the specifically briefed Contracts root surface is already correct - -`packages/contracts/src/public/mod.ts` re-exports: - -- `baseContract` and `BaseContract` at lines 2-3; -- `BaseContractOutputRoute` and `BaseContractRoute` at lines 4-7; -- `OffsetPaginationQuerySchema` in the schema export block. - -Four independent `deno doc --filter` commands against `packages/contracts/mod.ts` returned raw exit -0 and rendered each of `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, and -`OffsetPaginationQuerySchema`. The examples in `contract-primitives.ts` import the first three from -`@netscript/contracts`, and the root module example imports the pagination schema from the same -root. Those are valid, copyable imports at baseline. - -No edit to `contract-primitives.ts` or `src/public/mod.ts` is earned by this leaf. The PR must say -that row was already satisfied rather than claiming it as implementation. - -### F4 — a different shipped Contracts JSDoc import is still wrong - -`packages/contracts/src/application/paginated-query.ts` begins its published `@module` example with: - -```ts -import { paginatedQuery } from '@netscript/contracts'; -``` - -The root `deno doc --json packages/contracts/mod.ts` surface has 70 symbols and does not contain -`paginatedQuery`; the `./query` entrypoint does. The manual Contracts page already lists -`paginatedQuery`, `offsetPaginatedQuery`, and `cursorPaginatedQuery` under -`@netscript/contracts/query`, and the current exports/symbol drift checker passes that manual page. - -This reconciles issue #1110's wording ("correct the source JSDoc import that currently points at the -wrong root entrypoint") with the current tree. The live source fix is in `paginated-query.ts`, not -in the already-correct `contract-primitives.ts` examples named by #1296. +### F3 — full nine-line Contracts implementation-example inventory is only partly correct + +The inventory below enumerates every `from '@netscript/contracts…'` line in the shipped +implementation sources under `crud/`, `src/`, and `schemas/` (entrypoint self-documentation in +`mod.ts`, `crud.ts`, `query.ts`, and `transform.ts` is separately correct and is not one of these +nine implementation examples): + +| # | Source line | Imported symbols / entrypoint | Baseline verdict | +| -: | -------------------------------------------- | ---------------------------------------------------------- | --------------------------------- | +| 1 | `crud/create-crud-contract.ts:6` | `createCrudContract` from `/crud` | correct; `/crud` `EXIT=0` | +| 2 | `crud/create-crud-contract.ts:250` | `createCrudContract` from `/crud` | correct; `/crud` `EXIT=0` | +| 3 | `src/application/contract-primitives.ts:72` | `baseContract` from root | correct; root `EXIT=0` | +| 4 | `src/application/contract-primitives.ts:112` | `baseContract`, `BaseContractRoute` from root | correct; root `EXIT=0` per symbol | +| 5 | `src/application/contract-primitives.ts:144` | `baseContract`, `BaseContractOutputRoute` from root | correct; root `EXIT=0` per symbol | +| 6 | `src/application/paginated-query.ts:6` | `paginatedQuery` from root | **wrong**; use `/query` | +| 7 | `src/application/transform-helpers.ts:6` | `createTransformer` from root | **wrong**; use `/transform` | +| 8 | `schemas/filters.ts:6` | `FilterConditionSchema`, `buildPrismaWhere` from root | **wrong**; use `/query` | +| 9 | `schemas/pagination.ts:6` | `PaginationInputSchema`, `createPaginatedOutput` from root | **wrong**; use `/query` | + +Independent unpiped `deno doc --no-lock --filter` commands also confirmed the specifically briefed +`OffsetPaginationQuerySchema` root example: `baseContract`, `BaseContractRoute`, +`BaseContractOutputRoute`, and `OffsetPaginationQuerySchema` each returned root `EXIT=0`. +`createCrudContract` returned `/crud` `EXIT=0`. These are baseline-earned and remain untouched. + +### F4 — six symbols across four shipped examples use the wrong entrypoint + +The raw per-symbol exit evidence is: + +| Symbol | `packages/contracts/mod.ts` | Correct entrypoint | +| ----------------------- | --------------------------: | ----------------------- | +| `paginatedQuery` | `EXIT=1` | `query.ts` `EXIT=0` | +| `createTransformer` | `EXIT=1` | `transform.ts` `EXIT=0` | +| `FilterConditionSchema` | `EXIT=1` | `query.ts` `EXIT=0` | +| `buildPrismaWhere` | `EXIT=1` | `query.ts` `EXIT=0` | +| `PaginationInputSchema` | `EXIT=1` | `query.ts` `EXIT=0` | +| `createPaginatedOutput` | `EXIT=1` | `query.ts` `EXIT=0` | + +All four files are included by the Contracts publish set (`src/**/*.ts` or `schemas/**/*.ts`), so +their JSDoc ships. The coordinator granted a JSDoc-only rescope for exactly those four import-line +repairs (the original `paginated-query.ts` plus three additions). No runtime, type, export, or +schema change is planned. This makes `Closes #1296` honest only because the rescope covers the +entire residual inventory; the already-correct reference page, `contract-primitives.ts`, and public +root remain untouched. ### F5 — Fresh UI entrypoints are complete, but symbol coverage is disabled @@ -169,14 +192,15 @@ that leaves Fresh UI, Plugin, Queue, SDK, and Service silently entrypoint-only. A discriminated coverage object fits the existing consumer: -- `mode: 'complete'` — run `deno doc` for every derived entrypoint, and flatten explicit - reason-bearing omission groups into the exclusion set; +- `mode: 'complete'` — carry a nonempty coverage reason, run `deno doc` for every derived + entrypoint, and flatten explicit reason-bearing omission groups into the exclusion set; - `mode: 'entrypoints-only'` — skip symbol comparison only when a nonempty reason is present; - a reason-bearing allow-list for doc-only copy-source symbols where a page explicitly labels them as non-package exports. -This retains the current `Set`-based comparison, makes invalid/empty policy a hard refusal, and -avoids a new inventory directory or handwritten export map. +This retains the current `Set`-based comparison, makes invalid/empty policy a hard refusal, supports +an every-run mode/reason/omission-count report, and avoids a new inventory directory or handwritten +export map. ### F8 — workflow trigger coverage already fits the leaf @@ -189,18 +213,18 @@ Aspire resource is necessary. ### F9 — MySQL is independently owned and must not block this leaf Issue #1293 is open with `status:impl` and owns the Prisma MySQL exported adapter and remaining -executable-example work. The frozen nine-path surface contains no MySQL package or reference path. -This leaf neither reads that work as a prerequisite nor changes it. +executable-example work. Neither the frozen nine paths nor SA-1/SA-2's four added paths contain a +MySQL package or reference path. This leaf neither reads that work as a prerequisite nor changes it. ## JSR/publication surface scan -JSR audit is applicable because one shipped JSDoc file inside published `@netscript/contracts` will -change and the Fresh UI reference is derived from a published member. +JSR audit is applicable because four shipped JSDoc files inside published `@netscript/contracts` +will change and the Fresh UI reference is derived from a published member. -| Member | Planned publish delta | Export map | Exact `@netscript/*` pins | Baseline evidence / risk | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `@netscript/contracts@0.0.6` | Yes: `src/application/paginated-query.ts` JSDoc ships under `src/**/*.ts`; no runtime/type/export change. | Four entrypoints: `.`, `./crud`, `./query`, `./transform`; unchanged. | None in member imports. `@orpc/contract@^1.14.6` and root-catalog `zod` are non-NetScript dependencies. | `audit-jsr-package` raw exit 0; dry-run OK with one sanctioned oRPC slow-type INFO. Full-export `doc:lint` raw exit 1 with nine pre-existing private-type-ref diagnostics (eight contract primitives, one CRUD), not caused or fixed by this prose-only source edit. | -| `@netscript/fresh-ui@0.0.6` | No package file changes; reference/checker only. The plan still audits its real published surface rather than claiming "no publish delta" without inspection. | Six entrypoints listed in F5; unchanged. | `@netscript/sdk/auto-update` and `@netscript/sdk/desktop` are both exact `jsr:@netscript/sdk@0.0.6/...`; `deps:why @netscript/sdk` raw exit 0 confirms live source use. | `audit-jsr-package` raw exit 0 and dry-run OK, while reporting existing folder/cardinality and slow-type warnings. Full-export `doc:lint` raw exit 1 with 123 existing `/interactive` diagnostics. Source repair is outside the frozen surface. | +| Member | Planned publish delta | Export map | Exact `@netscript/*` pins | Baseline evidence / risk | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `@netscript/contracts@0.0.6` | Yes: JSDoc import text changes in `src/application/paginated-query.ts`, `src/application/transform-helpers.ts`, `schemas/filters.ts`, and `schemas/pagination.ts`; no runtime/type/export/schema change. | Four entrypoints: `.`, `./crud`, `./query`, `./transform`; unchanged. | None in member imports. `@orpc/contract@^1.14.6` and root-catalog `zod` are non-NetScript dependencies. | `audit-jsr-package` raw exit 0; dry-run OK with one sanctioned oRPC slow-type INFO. Full-export `doc:lint` raw exit 1 with nine pre-existing private-type-ref diagnostics (eight contract primitives, one CRUD), not caused or fixed by these prose-only source edits. | +| `@netscript/fresh-ui@0.0.6` | No package file changes; reference/checker only. The plan still audits its real published surface rather than claiming "no publish delta" without inspection. | Six entrypoints listed in F5; unchanged. | `@netscript/sdk/auto-update` and `@netscript/sdk/desktop` are both exact `jsr:@netscript/sdk@0.0.6/...`; `deps:why @netscript/sdk` raw exit 0 confirms live source use. | `audit-jsr-package` raw exit 0 and dry-run OK, while reporting existing folder/cardinality and slow-type warnings. Full-export `doc:lint` raw exit 1 with 123 existing `/interactive` diagnostics. Source repair is outside the frozen surface. | Root `compilerOptions.isolatedDeclarations` is `true`. The final canonical workspace `publish:dry-run` remains required because the Contracts JSDoc is part of the publish set. A green @@ -226,15 +250,18 @@ reported baseline doc-lint debt or prove a real publish. ## Open questions resolved for planning - **Must resolve now:** Create `docs/exports`? No. It is stale contract scope and duplicative. -- **Must resolve now:** Is the drift checker currently unwired? No. It is indirectly fail-closed; - the plan makes the edge named and adds workflow execution without claiming a new gate from zero. +- **Must resolve now:** Is export drift enforced? Yes. Non-draft CI already reaches it fail-closed + through `quality` -> gate catalog -> `docs:accuracy` -> the spawned checker. The plan improves + direct discoverability and adds an explicit Pages identity without claiming new enforcement. - **Must resolve now:** How are omissions represented? A reason-bearing discriminated policy in `AUTHORITATIVE_MAPPING`, consumed directly by the existing checker. -- **Must resolve now:** Is Fresh UI browser execution necessary? No for export truth; only the - coordinator may require it as rendered-reference assurance. The implementation lane is forbidden - from firing it. +- **Resolved by SA-1:** Fresh UI browser execution is N/A/waived for this surface. It remains + `NOT_RUN`; the implementation lane must not request a runtime lease or fire it. +- **Must resolve now:** Are the three additional Contracts examples deferred? No. The coordinator + granted import-line-only scope for all three, bringing the authorized implementation surface to + thirteen paths and making closure of #1296 honest once all four residual lines are repaired. - **Safe to defer:** Existing Fresh UI public-source doc-lint/slow-type remediation and Contracts - oRPC private-type-ref debt; neither can be fixed within the frozen nine paths. + oRPC private-type-ref debt; neither is part of the thirteen authorized paths. - **Safe to defer:** Broadening symbol-complete coverage for every reference page. This leaf makes entrypoints-only policy explicit rather than silently claiming completeness; later leaves can promote packages one at a time. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md index ed02e208b4..9621aa8413 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/scope-amendment.md @@ -1,19 +1,20 @@ -# Scope amendment SA-1 — `reference-export-drift-gate` (#1666 / closes #1296) - -| Field | Value | -| -------------------- | ------------------------------------------------------------------------------------ | -| Amendment ID | `SA-1` | -| Recorded (UTC) | `2026-08-15T16:40:42Z` | -| Authority | coordinator `codex-root-0.0.7`, relayed through the owner | -| Recorded by | `topic-internals-0.0.7`, Claude session `f7691917-0be2-4bcd-8839-43d3fc809c34` | -| Amends | `plan.md` (inline `AMENDED (SA-1)` annotations) at planning head `9d0b4bf12` | -| Leaf / lane | `reference-export-drift-gate`, wave 2 internals | -| Branch / base | `fix/reference-export-drift-gate` / `baf1cdf67a4e931af17b4772ddf6101f36152184` | -| Status | in force; governs wherever it conflicts with `plan.md` | - -This is a **control-plane** record. It changes authorized scope and gate classification. It changes -no implementation decision in `plan.md` (D1-D11 stand unmodified), and it does **not** grant merge, -publish, ready-flip, relabel, issue-closure, milestone, or release-writer authority. +# Scope amendments SA-1 / SA-1a / SA-2 — `reference-export-drift-gate` (#1666 / closes #1296) + +| Field | Value | +| -------------- | ------------------------------------------------------------------------------ | +| Amendment IDs | `SA-1`, `SA-1a`, `SA-2` | +| Recorded (UTC) | SA-1 `2026-08-15T16:40:42Z`; SA-1a `2026-08-15T16:57Z`; SA-2 `2026-08-15` | +| Authority | coordinator `codex-root-0.0.7`, relayed through the owner | +| Recorded by | `topic-internals-0.0.7`, Claude session `f7691917-0be2-4bcd-8839-43d3fc809c34` | +| Amends | `plan.md`; SA-2 builds on evaluator `5d229e0f3` and SA-1a head `cb91b225d` | +| Leaf / lane | `reference-export-drift-gate`, wave 2 internals | +| Branch / base | `fix/reference-export-drift-gate` / `baf1cdf67a4e931af17b4772ddf6101f36152184` | +| Status | SA-2 in force; latest ruling governs wherever amendments or `plan.md` conflict | + +This is a **control-plane** record. It changes authorized scope and gate classification. SA-1 left +D1-D11 intact; SA-2 narrows D8's JSDoc-only reconciliation to all four measured residual examples +and binds N1-N5. It does **not** grant merge, publish, ready-flip, relabel, issue-closure, +milestone, or release-writer authority. ## A1 — Tenth implementation path AUTHORIZED (test-only) @@ -21,14 +22,15 @@ publish, ready-flip, relabel, issue-closure, milestone, or release-writer author .llm/tools/docs/check-exports-drift_test.ts ``` -The frozen contract in central `leaf-contracts.json` lists **nine** `fileSurfaces`. This tenth path -is authorized in addition to them, under these bounds: +The frozen contract in central `leaf-contracts.json` lists **nine** `fileSurfaces`. SA-1 authorized +this test path in addition to them. SA-2 later added three JSDoc-only paths, so the live total is +**thirteen** under these bounds: - **Test assertions only.** No product, config, or generated file may be edited under this path. It is not a licence to reach any other unfrozen file. - The **existing** negative export fixture (`drift checker negative fixture validation`) must keep passing; SA-1 adds cases, it does not license rewriting or weakening what is already there. -- An **eleventh** path remains rescope: stop and request it. +- A **fourteenth** implementation path is rescope: stop and request it. **Why.** S1 lands fail-closed coverage-policy semantics (D2-D5) whose refusal paths are the load-bearing part of the change — empty or malformed reasons, unknown coverage modes, invented @@ -49,8 +51,8 @@ waived** for this leaf. **Why.** The verified plan changes checker logic, documentation prose, shipped JSDoc, task wiring, and workflow wiring only. No route, component, island, CSS, interaction, loading/error state, or -application workflow changes. The `frontend` overlay is present because Fresh UI is the *documented -package*, not because browser behavior is modified. +application workflow changes. The `frontend` overlay is present because Fresh UI is the _documented +package_, not because browser behavior is modified. **Obligations that survive the waiver:** @@ -61,43 +63,50 @@ package*, not because browser behavior is modified. ## A3 — PLAN-EVAL cycle 1 GRANTED (one cycle, after fresh Tier-A) -| Field | Value | -| ------------- | ---------------------------------------------------------------------------- | -| Cycles | exactly **one** (cycle 1 of 2) | -| Precondition | this amendment passes a **fresh Tier-A** supervisor review | -| Target | the **amended immutable head** produced by the commit carrying SA-1 | -| Session | **fresh and separate** from the author session | -| Route | native **Fable 5**, effort **medium**, Remote Control attached | -| Output | **artifact-only** — writes `plan-eval.md` in this slice directory and nothing else | -| On `PASS` | the **preserved original Codex author** resumes through the plan's serial slices, each followed by a fresh Tier-A gate | -| On `FAIL_PLAN`| reported as `FAIL_PLAN`; not worked around, not re-run without a grant | +| Field | Value | +| -------------- | ---------------------------------------------------------------------------------------------------------------------- | +| Cycles | exactly **one** (cycle 1 of 2) | +| Precondition | this amendment passes a **fresh Tier-A** supervisor review | +| Target | the **amended immutable head** produced by the commit carrying SA-1 | +| Session | **fresh and separate** from the author session | +| Route | native **Fable 5**, effort **medium**, Remote Control attached | +| Output | **artifact-only** — writes `plan-eval.md` in this slice directory and nothing else | +| On `PASS` | the **preserved original Codex author** resumes through the plan's serial slices, each followed by a fresh Tier-A gate | +| On `FAIL_PLAN` | reported as `FAIL_PLAN`; not worked around, not re-run without a grant | The evaluator does not merge, relabel, flip the PR to ready, close issues, mutate central cluster state, or edit any implementation path. ## A4 — Sequencing -`#1666` sequences **before** `#1533 jsdoc-example-compile-gate`. #1533 introduces an example-compiler -gate that would go red on `packages/contracts/src/application/paginated-query.ts:6` — the very JSDoc -import this leaf corrects. Landing #1533 first would knowingly ship a red gate against an -already-identified defect. +`#1666` sequences **before** `#1533 jsdoc-example-compile-gate`. #1533 introduces an +example-compiler gate that would go red on all four affected files: + +- `packages/contracts/src/application/paginated-query.ts`; +- `packages/contracts/src/application/transform-helpers.ts`; +- `packages/contracts/schemas/filters.ts`; +- `packages/contracts/schemas/pagination.ts`. + +Landing #1666 first clears all four known example-compile failures; landing #1533 first would +knowingly ship a red gate against those already-identified defects. ## A5 — Central-state reconciliation is owed upstream -Central `leaf-contracts.json` is **coordinator-owned** and still freezes nine `fileSurfaces` for this -leaf. This lane does not edit it. SA-1 is the leaf-local record of the authorized tenth path and the -gate classification, committed and pushed on the leaf branch so it forms part of the immutable head -the evaluator reads. The reconciliation of central state against SA-1 is reported upstream and -remains the coordinator's to perform. Topic-side record: `drift.md` in the topic orchestration run -directory. +Central `leaf-contracts.json` is **coordinator-owned** and still freezes nine `fileSurfaces` for +this leaf. This lane does not edit it. SA-1 and SA-2 are the leaf-local record of the authorized +test path, three JSDoc-only paths, and gate classification, committed and pushed on the leaf branch +so they form part of the immutable head the evaluator reads. Reconciliation of central state against +the live **thirteen-path** leaf contract remains the coordinator's responsibility. Topic-side +record: `drift.md` in the topic orchestration run directory. ## What SA-1 does not change -- Every locked decision D1-D11 in `plan.md`, including D5 ("exclusions must never compensate for - parser defects") and D11 ("do not tune the checker to baseline green — a real red after wiring is - reported red"). -- The nine frozen paths and their per-path actions, including `docs/exports` (**do not create**), - `contract-primitives.ts` (**do not edit**), and `src/public/mod.ts` (**do not edit**). +- Locked decisions D1-D7 and D9-D11 in `plan.md`, including D5 ("exclusions must never compensate + for parser defects") and D11 ("do not tune the checker to baseline green — a real red is reported + red"). D8 is superseded only to include the three coordinator-granted JSDoc lines. +- The nine frozen paths and their per-path actions, plus the SA-1 test path and SA-2's three + JSDoc-only paths. `docs/exports` remains **do not create**; `contract-primitives.ts` and + `src/public/mod.ts` remain **do not edit**. - The remaining proving gates: `check`, `test`, `publish-dry-run`, `quality-job`, `arch-check`, `docs-source-format`, `docs-accuracy`, and the JSR audit obligations. - Evidence discipline: raw exit codes read unpiped, an empty selection is a refusal rather than a @@ -105,20 +114,78 @@ directory. - The prohibition on merge, publish, ready flip, relabel beyond the leaf's own `status:`, issue closure, milestone change, central-state mutation, and touching another lane's worktree. -## SA-1a — correction to SA-1 (2026-08-15T16:57Z) +## SA-1a — historical correction to SA-1 (2026-08-15T16:57Z; count superseded by SA-2) -SA-1 authorized the tenth path but left four path-count statements in `plan.md` reading "nine". -One of them was load-bearing: validation row 11 and the S3 evidence line defined the diff audit as -an **exact nine-path** audit, so the audit gate as written would have refused the very path SA-1 -authorized — or pushed the author to drop the test file to make the gate quiet. That is the same +SA-1 authorized the tenth path but left four path-count statements in `plan.md` reading "nine". One +of them was load-bearing: validation row 11 and the S3 evidence line historically bound the audit to +the frozen count, so the audit gate as written would have refused the very path SA-1 authorized — or +pushed the author to drop the test file to make the gate quiet. That is the same coverage-versus-compliance failure this leaf exists to remove, introduced by the amendment meant to prevent it. -Corrected in `plan.md` at lines 36, 148, 171, and 236, each annotated `AMENDED (SA-1a)`: the -authorized surface is **ten** paths — nine frozen plus the SA-1 test-only tenth — and the diff audit -is bound to ten. The risk-register row additionally restates that the tenth path is -test-assertions-only and is not a licence to edit workflow source. `plan.md:206` ("nine -private-type-ref reds") is an unrelated `doc:lint` baseline count and is deliberately unchanged. +At the SA-1a head, the correction bound the audit to the then-current ten paths. SA-2 supersedes +that count everywhere operational: S3, validation row 11, and the risk guard are now bound to +**thirteen**, and a fourteenth implementation path is rescope. The unrelated Contracts `doc:lint` +baseline remains nine private-type-ref diagnostics and is deliberately unchanged. Found by an independent Tier-A pass, not by the Tier-A that admitted SA-1 — that pass grepped for the authorized filename and never grepped for the count. Recorded in the topic drift log. + +## SA-2 — PLAN-EVAL cycle-1 remediation (2026-08-15) + +PLAN-EVAL cycle 1 returned `FAIL_PLAN` at evaluator commit `5d229e0f3`. The coordinator ruled every +open point; this section records those rulings and does not delegate them to implementation +judgement. + +### B1 — three JSDoc-only paths GRANTED + +Exactly these paths are added, and only the `@example` import subpath may change: + +| Path | Symbols | Ruled entrypoint | +| --------------------------------------------------------- | ------------------------------------------------ | -------------------------------- | +| `packages/contracts/src/application/transform-helpers.ts` | `createTransformer` | `@netscript/contracts/transform` | +| `packages/contracts/schemas/filters.ts` | `FilterConditionSchema`, `buildPrismaWhere` | `@netscript/contracts/query` | +| `packages/contracts/schemas/pagination.ts` | `PaginationInputSchema`, `createPaginatedOutput` | `@netscript/contracts/query` | + +No runtime, type, export, or schema change is authorized. Together with the frozen nine and SA-1's +test path, the surface is **thirteen**. `Closes #1296` remains honest because the plan now repairs +all four measured residual examples; without this rescope it would not be honest. + +### Corrected enforcement premise + +The coordinator's original dispatch premise was wrong, and the research inherited that error. The +checker is already enforced fail-closed in qualifying non-draft CI: + +```text +ci.yml:366 run-gate.ts --gate docs-accuracy --id quality-docs-accuracy + (quality job at :282; non-draft guard at :287) + -> catalog.ts:59 docs-accuracy -> deno task docs:accuracy + -> deno.json:85 docs:accuracy -> check-accuracy-and-discoverability.ts + -> :291-301 spawn check-exports-drift.ts; print child output and throw on nonzero +``` + +The remaining acceptance gap is discoverability and maintainer procedure: no named +`docs:exports-drift` task, no explicit Pages step bearing that name, and no runbook. S2 preserves +existing enforcement and makes it visible; it does not claim to create enforcement. + +### N1-N5 — binding implementation details + +- **N1:** S1 commits an honest residual red with its raw exit and findings; green is not its commit + condition and D11 forbids tuning the checker quiet. +- **N2:** every checker run prints each package's coverage mode, reason, and omission-group counts + before its terminal verdict. +- **N3:** export injectable `checkDrift(mapping)` returning a process code; the + `if (import.meta.main)` guard calls `Deno.exit(await checkDrift(AUTHORITATIVE_MAPPING))`. Tests + pass malformed mappings directly without triggering `main` and assert nonzero without trying to + mutate the hardcoded constant in a subprocess. +- **N4:** the Pages step runs `deno task docs:exports-drift` from repository root, has no + `working-directory`, and uses `if: env.RUN == 'true'`. +- **N5:** `docs:accuracy` invokes the named task under its existing `--allow-run=deno` permission + and preserves the current child stdout/stderr surfacing before throwing on nonzero. + +### PLAN-EVAL cycle 2 + +A fresh PLAN-EVAL is **required** because SA-2 materially changes closure scope, the test seam, +coverage reporting, and the CI premise. It is not author-granted. After this run-artifact-only head +is pushed, the coordinator must run fresh Tier-A and then grant/dispatch the final separate-session +cycle. No JSDoc or product edit may begin without both Tier-A PASS and PLAN-EVAL cycle-2 PASS. From 45c249b9c16ee075435d11b827c94beca1f87ce2 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 19:29:12 +0200 Subject: [PATCH 07/23] eval(plan): PLAN-EVAL cycle 2 PASS for reference-export-drift-gate Evaluated head 80046696e; cycle-1 verdict preserved as plan-eval-cycle-1.md. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01K6SbsotG5MyjyjTd11SrfK --- .../plan-eval-cycle-1.md | 197 +++++++++++ .../reference-export-drift-gate/plan-eval.md | 332 ++++++++---------- 2 files changed, 346 insertions(+), 183 deletions(-) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval-cycle-1.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval-cycle-1.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval-cycle-1.md new file mode 100644 index 0000000000..c85da2ac01 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval-cycle-1.md @@ -0,0 +1,197 @@ +# PLAN-EVAL — release-0.0.7-internals--orchestration/slices/reference-export-drift-gate + +## Verdict block + +| Field | Value | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Evaluated head | `a3f6b87b599e778db950daf6ccaecd847c088d19` (asserted via `git rev-parse HEAD`, match) | +| Base | `baf1cdf67a4e931af17b4772ddf6101f36152184` | +| PR / issue | #1666 (draft) / closes #1296 | +| Cycle | **1 of 2** | +| Evaluator session | Claude Code session `68c31fcc-f93b-496f-8c0b-10e6736dded7` (background job `68c31fcc`) | +| Route | native Claude **Fable 5** / effort **medium** (`formal_plan_evaluation`, opposite family) | +| Artifacts evaluated | `plan.md` (as amended), `scope-amendment.md` (SA-1, governs on conflict), `research.md`, `implement.md`, frozen `leaf-contracts.json` entry (read-only) | +| Surface / archetype | frozen `6 — CLI / Tooling`; overlays `frontend`, `docs` | +| **Verdict** | **`FAIL_PLAN`** | + +One blocking finding (B1). Everything else re-derived below holds. Nothing outside this file was +written; no gate other than the read-only checks listed here was fired; `fresh-browser` stays +`NOT_RUN`. + +## Blocking finding + +### B1 — acceptance row 1 is materially less satisfied than research/plan/SA-1 state; three more shipped Contracts JSDoc examples import from a non-exporting root, all outside the frozen surface + +The plan (F3/F4, D8, "Explicit deferrals") and PR body assert that #1296 row 1 +(_"`packages/contracts` JSDoc examples import from the subpath that actually exports the symbols; a +reader copying them gets code that compiles"_) is baseline-earned except for `paginated-query.ts:6`. +I enumerated **every** `from '@netscript/contracts…'` line in shipped Contracts sources and checked +each imported symbol against the root with `deno doc --filter` (exit 1 = `Node … was not found!`): + +```text +grep -rnoE "from '@netscript/contracts[^']*'" packages/contracts --include=*.ts --include=*.tsx | grep -v _test + packages/contracts/crud/create-crud-contract.ts:6,250 -> '@netscript/contracts/crud' (correct) + packages/contracts/src/application/contract-primitives.ts:72,112,144 -> '@netscript/contracts' (correct; baseContract/BaseContractRoute/BaseContractOutputRoute all root EXIT=0) + packages/contracts/src/application/paginated-query.ts:6 -> '@netscript/contracts' (WRONG — plan already covers) + packages/contracts/src/application/transform-helpers.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + packages/contracts/schemas/filters.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + packages/contracts/schemas/pagination.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) + +deno doc --no-lock --filter createTransformer packages/contracts/mod.ts -> EXIT=1 ; on transform.ts -> EXIT=0 +deno doc --no-lock --filter FilterConditionSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter buildPrismaWhere packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter PaginationInputSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter createPaginatedOutput packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +deno doc --no-lock --filter paginatedQuery packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 +``` + +All three additional files are in the publish set (`packages/contracts/deno.json` `publish.include` +has `src/**/*.ts` and `schemas/**/*.ts`), so they ship JSDoc a reader cannot copy — the same class +of defect as `paginated-query.ts:6`, in three more places. + +Why this blocks the plan rather than the implementation: + +1. `research.md` F3/F4 and `plan.md` D8 / "Explicit deferrals and non-scope" record row 1 as + already-correct apart from one file. That statement is false, so the "reconcile row 1 honestly + and visibly" obligation from the brief cannot be met by the plan as written. +2. `plan.md` locks `Closes #1296`. Merging under this plan would auto-close an issue whose row 1 is + still unmet in three shipped files. +3. The three files are **outside the frozen nine (+1) paths**. Fixing them needs a coordinator + rescope; declining to fix them needs a coordinator decision on closure. Either way this is not a + decision the author may take alone, and it is not "safe to defer" — it changes what the PR may + honestly claim to close. That is an unflagged open decision under `gates/plan-gate.md` + ("Open-decision sweep" / "Deferred scope explicit"). +4. SA-1 A4's sequencing rationale ("#1533's example-compile gate would go red on + `paginated-query.ts:6` — the very JSDoc import this leaf corrects") is incomplete: #1533 would go + red on the three files above as well, so landing #1666 first does not prevent that red. + +**Required fix (author, then coordinator decision):** + +- Update `research.md` (F3/F4) with the full nine-line import inventory above and its `deno doc` + evidence; correct `plan.md` D8, the row-1 statement in the "Live acceptance contract" table, and + the deferrals section so that row 1 is recorded as **partially** satisfied at baseline with the + residual named file-by-file. +- Resolve, in `plan.md`, one of: + - (a) request from the coordinator a **JSDoc-only** scope amendment for + `packages/contracts/src/application/transform-helpers.ts`, + `packages/contracts/schemas/filters.ts`, `packages/contracts/schemas/pagination.ts` (edit + surface: the `@example` import line only; same publish-delta treatment as `paginated-query.ts` + in the JSR table), and add them to S1 and to validation row 11's path audit; **or** + - (b) keep the frozen surface, state explicitly that row 1 remains **unmet** for those three files + after this leaf, and have the coordinator decide whether `Closes #1296` stands (it should not + without (a) or a follow-up issue that the PR references without a closing keyword). +- Update the SA-1 A4 rationale (or add an SA-2 note) so the #1533 sequencing argument reflects all + four affected files, not one. + +I did not perform any of this. It is a coordinator scope decision. + +## Verified claims (re-derived, not trusted) + +| # | Claim | Result | Evidence | +| -------- | ------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| A1 | Checker real and passing | **holds** | `deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts` → `DRIFT_RAW_EXIT=0`, `Exports & Symbols drift check: PASS` | +| A1 | "wired to nothing" | **false, as research says** | `grep -rnE 'check-exports-drift\|exports-drift' deno.json .github/workflows/` → `EXIT=1` (no hits). But `.llm/tools/docs/check-accuracy-and-discoverability.ts:292-301` spawns `deno run --allow-all .llm/tools/docs/check-exports-drift.ts`, throws on nonzero child code; `deno.json:85` `docs:accuracy` runs that script (`--allow-run=deno`), `deno.json:90` `docs:maintenance` includes `docs:accuracy`; `.llm/tools/gates/catalog.ts:59` maps `docs-accuracy` → `deno task docs:accuracy`. `deno task docs:accuracy` → `ACCURACY_RAW_EXIT=0`, terminal `docs accuracy: PASS`. No workflow runs `docs:accuracy`/`docs:maintenance`/`docs-accuracy` (`grep … .github/workflows/` → `EXIT=1`). Research F1 is accurate; the missing pieces (named task, workflow step, runbook) are correctly identified. | +| A3 | Row 1 baseline-satisfied for the four Step-0 symbols | **holds for those four**, but see B1 | `deno doc --filter` on `packages/contracts/mod.ts`: `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, `OffsetPaginationQuerySchema` all `EXIT=0`; `contract-primitives.ts:72,112,144` import from root. | +| F4 | `paginatedQuery` absent from root, present on `/query` | **holds** | root filter `EXIT=1` (`Node paginatedQuery was not found!`); `query.ts` filter `EXIT=0`, its own JSDoc uses `@netscript/contracts/query`. `paginated-query.ts:6` still imports from root at head. | +| F5 | Six Fresh UI entrypoints, 28/11/35/82/16/7 symbols, 168 union | **holds exactly** | scratch `.llm/tmp/pe-count.ts` (outside measured roots) using `deno doc --no-lock --json` per `deno.json.exports` entry → `{".":28,"./ai/render-ui":11,"./desktop":35,"./interactive":82,"./primitives":16,"./registry":7} UNION 168`, zero `declarationKind: 'private'` nodes. | +| F6 | Forcing symbol checking today: 168 / 78 / 162 | **holds exactly** | scratch `.llm/tmp/pe-f6.ts` importing the checker's own `parseDocContent`/`checkSymbolsDrift` → `EXPECTED 168 DOCUMENTED_PARSE 78 ERRORS 162` = 126 OMITS + 36 INVENTS. The 36 invented names are the prop/field/generic artifacts research lists (`columns, rows, label, class, [attribute: string], key, header, width, cell, render, DataGridColumn, DataGridProps, DataGridRow, hint, icon, active, accept, multiple, onFile, onFiles, onReject, onDrop, onDragOver, onPaste, children, DROPZONE_*, Dropzone*, ShowProps, layout, viz, data`). Parser at `check-exports-drift.ts:270-283` does take the first backticked cell of every table row. | +| D5 | `Symbol`-header boundary safe for already-complete pages | **holds** | Header cells in `docs/site/reference/{config,contracts,telemetry,fresh-ui}/index.md`: config 13×`Symbol`+1×`Export`; contracts 12×`Symbol`+1×`Export`; telemetry 9×`Symbol` (padded, trims to `Symbol`)+1×`Export`; fresh-ui 10×`Symbol` plus `Prop`/`Shape`/`Field`/`Category`/… tables (the false-positive sources). Restricting to `Symbol`-headed tables will not create false reds on Config/Contracts/Telemetry — provided the header match is applied after `trim()`. | +| D4 | Dropzone types are in a `Symbol`-headed table | **holds** | `fresh-ui/index.md:153-161`; prose at 125-126 labels Dropzone copy-source / not a package export. | +| F2 | `docs/exports` absent, no history | **holds** | `test -e docs/exports` → `EXIT=1`; `git ls-tree -r --name-only baf1cdf67 -- docs/exports` → 0 paths. | +| F8 | Pages triggers already cover the edit surface | **holds** | `pages.yml:6-22,25-41` include `docs/site/**`, `packages/**`, `plugins/**`, `.llm/tools/docs/**`, `deno.json`. Note the `classify` job can skip the build by policy (`ci-classify-changes.ts`); root `deno.json` **tasks-only** changes → `pages:false`, package source/`packages/*/deno.json` changes → `pages:true`, `.llm/tools/docs/**` → `pages:true`. So a drift step in the build job fires for every input that can change export truth. | +| SA-1 T4 | Existing test passes | **holds** | `deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts` → `TEST_RAW_EXIT=0`, `1 passed \| 0 failed`. The single test exercises pure functions (`deriveExpectedExports`/`parseDocContent`/`checkExportsDrift`), not process exit. | +| Contract | Nine `fileSurfaces`, `fresh-browser` in `provingGates` | **holds** | `leaf-contracts.json` entry `reference-export-drift-gate` lines 1129-1149. Divergence from SA-1 is real and is upstream's. | +| Head | Branch diff vs base | **plan-only** | `git diff --name-status baf1cdf67 a3f6b87b5` → four added `.llm/runs/...` files only. | + +## Judgement on the eight questions + +1. **A1** — see table. Not "wired to nothing"; wired indirectly and fail-closed via `docs:accuracy`. + Nothing missed beyond what research F1 records; no workflow runs it. Plan's S2 is the right + remediation and does not claim prior work. +2. **A3** — the four Step-0 symbols hold; `paginatedQuery` is real; **three further files were + missed** (B1). +3. **`paginated-query.ts:6`** — confirmed with `deno doc`. +4. **D5 / D2-D4** — false positives are real and reproduced to the digit. The discriminated policy + makes a skipped symbol gate a config-level machine-readable fact (mode + mandatory nonempty + reason, refusal on empty/unknown). D5 fixes the parser first; D4's `documentedNonExports` is a + reason-bearing allow-list for a table the page itself labels non-export — it does not compensate + for a parser defect and does not weaken invented-symbol detection globally. Acceptable. Two + non-blocking gaps: N2 (report), N3 (test seam). +5. **D11** — executable. Real reds surface as `OMITS`/`INVENTS`; the legitimate outlets are + documenting the symbol or an audited reason-bearing omission group, and Tier-A reviews every + group. But S1's proof line reads "direct drift command raw exit 0 only after … reconcile", which + pressures toward green; N1 asks the plan to state that an honest residual red at S1 is reported + red, not tuned away. +6. **SA-1 justification** — a persistent test is required: the refusal paths are the load-bearing + semantics and a one-off probe cannot fail CI. The path is bounded to assertions. It is sufficient + for the four named refusal cases only if the checker exposes a seam the test can drive without + editing product code (N3). +7. **`fresh-browser` waiver** — correct. `catalog.ts:55` maps it to `deno task test:browser` = + `packages/fresh/deno.json:26` → `packages/fresh/tests/form-navigation_browser.ts`, a browser test + of `@netscript/fresh` form navigation. Nothing in the ten paths touches `packages/fresh`, any + route/island/component/CSS. Tier-A's caveat (the rewritten page is Lume-rendered) is about the + docs build, which Pages already covers via `deno task build` (`check:source-format` → lume → + `check:rendered-output`), not about `fresh-browser`. Not run; remains `NOT_RUN`. +8. **Four live rows** — rows 2, 3, 4 (Fresh UI repair, machine-readable omissions, runbook + wiring) + are closed by S1/S2 as designed. Row "Contracts inventory advertises no non-exports" (issue row + 2) is closed by the JSDoc fix plus the already-green reference page. Issue row 1 is **not** + honestly reconciled — B1. + +## Plan-Gate checklist + +| Plan-Gate item | Result | Evidence / location | +| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Research present and current | FAIL | `research.md` re-baselined at head, load-bearing findings F1/F4/F5/F6 reproduce; but F3/F4's row-1 inventory is incomplete (B1). | +| Decisions locked | PASS | D1-D11 with rationale; SA-1 leaves them intact. | +| Open-decision sweep | FAIL | The three out-of-surface JSDoc files (B1) are an unflagged decision that changes what the PR may close; not safe to defer. | +| Commit slices (< 30, gate + files each) | PASS | S1-S3 ordered, files and proofs named. | +| Risk register | PASS | present; "exclusion list becomes a hiding place" mitigated by review. | +| Gate set selected | PASS | frozen gates minus waived `fresh-browser` (SA-1 A2), plus JSR audit; validation table rows 1-11. | +| Deferred scope explicit | FAIL | "The already-correct Contracts root exports and `contract-primitives.ts` JSDoc" is explicit, but the deferral list silently omits three shipped Contracts JSDoc defects that row 1 requires (B1). | +| jsr-audit surface scan (pkg/plugin) | PASS | Contracts publish delta named honestly; Fresh UI no member delta; baseline doc-lint reds recorded as red; pins verified. Under fix (a) the JSR table gains three more prose-only files in the same publish set. | + +## Open-decision sweep (evaluator-run) + +- **B1** (blocking) — fix path (a) or (b) above; coordinator's call. +- No other decision would force checker/doc rework if deferred. + +## Non-blocking findings (address in the same cycle; not required for PASS) + +- **N1 — S1 proof wording vs D11.** State in S1 that if honest reconciliation leaves a residual red, + S1 commits with the residual reported red (per implement.md "wiring a gate that then fails on + baseline is a legitimate outcome") rather than requiring exit 0 as its commit condition. +- **N2 — visible coverage report.** The policy is machine-readable in config, but the checker's + terminal `PASS` line would still be silent about which packages ran in `entrypoints-only` mode. + Have the checker print, per package, the coverage mode, reason, and omission-group counts on every + run so a green never hides five entrypoint-only packages. +- **N3 — test seam.** Name how `check-exports-drift_test.ts` will assert the four refusal cases: + export a policy validator (or make `checkDrift(mapping)` injectable) and bind `Deno.exit(1)` to it + in `main`. `AUTHORITATIVE_MAPPING` is a hardcoded const, so a subprocess test cannot inject a + malformed policy without a seam; SA-1's "asserted nonzero" needs this to be satisfiable without + touching product code beyond the in-scope checker. +- **N4 — Pages step cwd.** The checker uses `Deno.cwd()` and repo-relative paths; the + build/links/caveats steps use `working-directory: docs/site` (`docs:snippets` runs from root). The + new step must run from repo root (`deno task docs:exports-drift` with no `working-directory`), and + it must sit behind the same `if: env.RUN == 'true'` guard as the other build steps. +- **N5 — `docs:accuracy` calling the named task.** With `--allow-run=deno` the child + `deno task docs:exports-drift` is permitted; keep the child's stdout/stderr surfaced on failure as + today (`check-accuracy-and-discoverability.ts:296-300`). + +## Commands fired (all read-only; raw exits unpiped) + +```text +git rev-parse HEAD -> a3f6b87b599e778db950daf6ccaecd847c088d19 +deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts -> 0 (PASS) +grep -rnE 'check-exports-drift|exports-drift' deno.json .github/workflows/ -> 1 +grep -rn 'docs-accuracy\|docs:maintenance\|docs:accuracy' .github/workflows/ -> 1 +deno task docs:accuracy -> 0 (PASS) +deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts -> 0 (1 passed) +deno doc --no-lock --filter packages/contracts/{mod,query,transform}.ts (see B1 / A3) -> as tabulated +deno run --no-lock --allow-read --allow-run .llm/tmp/pe-count.ts -> 0 (168) +deno run --no-lock --allow-read --allow-run .llm/tmp/pe-f6.ts -> 0 (168/78/162) +test -e docs/exports -> 1 +fresh-browser -> NOT_RUN (waived, not restated) +``` + +Scratch: `.llm/tmp/pe-*.{ts,out,json}` only. No implementation, product, config, generated, plan, +research, amendment, lock, doctrine, debt, or central-state file was modified. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md index c85da2ac01..5204638bd8 100644 --- a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md @@ -2,196 +2,162 @@ ## Verdict block -| Field | Value | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Evaluated head | `a3f6b87b599e778db950daf6ccaecd847c088d19` (asserted via `git rev-parse HEAD`, match) | -| Base | `baf1cdf67a4e931af17b4772ddf6101f36152184` | -| PR / issue | #1666 (draft) / closes #1296 | -| Cycle | **1 of 2** | -| Evaluator session | Claude Code session `68c31fcc-f93b-496f-8c0b-10e6736dded7` (background job `68c31fcc`) | -| Route | native Claude **Fable 5** / effort **medium** (`formal_plan_evaluation`, opposite family) | -| Artifacts evaluated | `plan.md` (as amended), `scope-amendment.md` (SA-1, governs on conflict), `research.md`, `implement.md`, frozen `leaf-contracts.json` entry (read-only) | -| Surface / archetype | frozen `6 — CLI / Tooling`; overlays `frontend`, `docs` | -| **Verdict** | **`FAIL_PLAN`** | - -One blocking finding (B1). Everything else re-derived below holds. Nothing outside this file was -written; no gate other than the read-only checks listed here was fired; `fresh-browser` stays -`NOT_RUN`. - -## Blocking finding - -### B1 — acceptance row 1 is materially less satisfied than research/plan/SA-1 state; three more shipped Contracts JSDoc examples import from a non-exporting root, all outside the frozen surface - -The plan (F3/F4, D8, "Explicit deferrals") and PR body assert that #1296 row 1 -(_"`packages/contracts` JSDoc examples import from the subpath that actually exports the symbols; a -reader copying them gets code that compiles"_) is baseline-earned except for `paginated-query.ts:6`. -I enumerated **every** `from '@netscript/contracts…'` line in shipped Contracts sources and checked -each imported symbol against the root with `deno doc --filter` (exit 1 = `Node … was not found!`): - -```text -grep -rnoE "from '@netscript/contracts[^']*'" packages/contracts --include=*.ts --include=*.tsx | grep -v _test - packages/contracts/crud/create-crud-contract.ts:6,250 -> '@netscript/contracts/crud' (correct) - packages/contracts/src/application/contract-primitives.ts:72,112,144 -> '@netscript/contracts' (correct; baseContract/BaseContractRoute/BaseContractOutputRoute all root EXIT=0) - packages/contracts/src/application/paginated-query.ts:6 -> '@netscript/contracts' (WRONG — plan already covers) - packages/contracts/src/application/transform-helpers.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) - packages/contracts/schemas/filters.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) - packages/contracts/schemas/pagination.ts:6 -> '@netscript/contracts' (WRONG — NOT in plan) - -deno doc --no-lock --filter createTransformer packages/contracts/mod.ts -> EXIT=1 ; on transform.ts -> EXIT=0 -deno doc --no-lock --filter FilterConditionSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 -deno doc --no-lock --filter buildPrismaWhere packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 -deno doc --no-lock --filter PaginationInputSchema packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 -deno doc --no-lock --filter createPaginatedOutput packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 -deno doc --no-lock --filter paginatedQuery packages/contracts/mod.ts -> EXIT=1 ; on query.ts -> EXIT=0 -``` - -All three additional files are in the publish set (`packages/contracts/deno.json` `publish.include` -has `src/**/*.ts` and `schemas/**/*.ts`), so they ship JSDoc a reader cannot copy — the same class -of defect as `paginated-query.ts:6`, in three more places. - -Why this blocks the plan rather than the implementation: - -1. `research.md` F3/F4 and `plan.md` D8 / "Explicit deferrals and non-scope" record row 1 as - already-correct apart from one file. That statement is false, so the "reconcile row 1 honestly - and visibly" obligation from the brief cannot be met by the plan as written. -2. `plan.md` locks `Closes #1296`. Merging under this plan would auto-close an issue whose row 1 is - still unmet in three shipped files. -3. The three files are **outside the frozen nine (+1) paths**. Fixing them needs a coordinator - rescope; declining to fix them needs a coordinator decision on closure. Either way this is not a - decision the author may take alone, and it is not "safe to defer" — it changes what the PR may - honestly claim to close. That is an unflagged open decision under `gates/plan-gate.md` - ("Open-decision sweep" / "Deferred scope explicit"). -4. SA-1 A4's sequencing rationale ("#1533's example-compile gate would go red on - `paginated-query.ts:6` — the very JSDoc import this leaf corrects") is incomplete: #1533 would go - red on the three files above as well, so landing #1666 first does not prevent that red. - -**Required fix (author, then coordinator decision):** - -- Update `research.md` (F3/F4) with the full nine-line import inventory above and its `deno doc` - evidence; correct `plan.md` D8, the row-1 statement in the "Live acceptance contract" table, and - the deferrals section so that row 1 is recorded as **partially** satisfied at baseline with the - residual named file-by-file. -- Resolve, in `plan.md`, one of: - - (a) request from the coordinator a **JSDoc-only** scope amendment for - `packages/contracts/src/application/transform-helpers.ts`, - `packages/contracts/schemas/filters.ts`, `packages/contracts/schemas/pagination.ts` (edit - surface: the `@example` import line only; same publish-delta treatment as `paginated-query.ts` - in the JSR table), and add them to S1 and to validation row 11's path audit; **or** - - (b) keep the frozen surface, state explicitly that row 1 remains **unmet** for those three files - after this leaf, and have the coordinator decide whether `Closes #1296` stands (it should not - without (a) or a follow-up issue that the PR references without a closing keyword). -- Update the SA-1 A4 rationale (or add an SA-2 note) so the #1533 sequencing argument reflects all - four affected files, not one. - -I did not perform any of this. It is a coordinator scope decision. - -## Verified claims (re-derived, not trusted) - -| # | Claim | Result | Evidence | -| -------- | ------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| A1 | Checker real and passing | **holds** | `deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts` → `DRIFT_RAW_EXIT=0`, `Exports & Symbols drift check: PASS` | -| A1 | "wired to nothing" | **false, as research says** | `grep -rnE 'check-exports-drift\|exports-drift' deno.json .github/workflows/` → `EXIT=1` (no hits). But `.llm/tools/docs/check-accuracy-and-discoverability.ts:292-301` spawns `deno run --allow-all .llm/tools/docs/check-exports-drift.ts`, throws on nonzero child code; `deno.json:85` `docs:accuracy` runs that script (`--allow-run=deno`), `deno.json:90` `docs:maintenance` includes `docs:accuracy`; `.llm/tools/gates/catalog.ts:59` maps `docs-accuracy` → `deno task docs:accuracy`. `deno task docs:accuracy` → `ACCURACY_RAW_EXIT=0`, terminal `docs accuracy: PASS`. No workflow runs `docs:accuracy`/`docs:maintenance`/`docs-accuracy` (`grep … .github/workflows/` → `EXIT=1`). Research F1 is accurate; the missing pieces (named task, workflow step, runbook) are correctly identified. | -| A3 | Row 1 baseline-satisfied for the four Step-0 symbols | **holds for those four**, but see B1 | `deno doc --filter` on `packages/contracts/mod.ts`: `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute`, `OffsetPaginationQuerySchema` all `EXIT=0`; `contract-primitives.ts:72,112,144` import from root. | -| F4 | `paginatedQuery` absent from root, present on `/query` | **holds** | root filter `EXIT=1` (`Node paginatedQuery was not found!`); `query.ts` filter `EXIT=0`, its own JSDoc uses `@netscript/contracts/query`. `paginated-query.ts:6` still imports from root at head. | -| F5 | Six Fresh UI entrypoints, 28/11/35/82/16/7 symbols, 168 union | **holds exactly** | scratch `.llm/tmp/pe-count.ts` (outside measured roots) using `deno doc --no-lock --json` per `deno.json.exports` entry → `{".":28,"./ai/render-ui":11,"./desktop":35,"./interactive":82,"./primitives":16,"./registry":7} UNION 168`, zero `declarationKind: 'private'` nodes. | -| F6 | Forcing symbol checking today: 168 / 78 / 162 | **holds exactly** | scratch `.llm/tmp/pe-f6.ts` importing the checker's own `parseDocContent`/`checkSymbolsDrift` → `EXPECTED 168 DOCUMENTED_PARSE 78 ERRORS 162` = 126 OMITS + 36 INVENTS. The 36 invented names are the prop/field/generic artifacts research lists (`columns, rows, label, class, [attribute: string], key, header, width, cell, render, DataGridColumn, DataGridProps, DataGridRow, hint, icon, active, accept, multiple, onFile, onFiles, onReject, onDrop, onDragOver, onPaste, children, DROPZONE_*, Dropzone*, ShowProps, layout, viz, data`). Parser at `check-exports-drift.ts:270-283` does take the first backticked cell of every table row. | -| D5 | `Symbol`-header boundary safe for already-complete pages | **holds** | Header cells in `docs/site/reference/{config,contracts,telemetry,fresh-ui}/index.md`: config 13×`Symbol`+1×`Export`; contracts 12×`Symbol`+1×`Export`; telemetry 9×`Symbol` (padded, trims to `Symbol`)+1×`Export`; fresh-ui 10×`Symbol` plus `Prop`/`Shape`/`Field`/`Category`/… tables (the false-positive sources). Restricting to `Symbol`-headed tables will not create false reds on Config/Contracts/Telemetry — provided the header match is applied after `trim()`. | -| D4 | Dropzone types are in a `Symbol`-headed table | **holds** | `fresh-ui/index.md:153-161`; prose at 125-126 labels Dropzone copy-source / not a package export. | -| F2 | `docs/exports` absent, no history | **holds** | `test -e docs/exports` → `EXIT=1`; `git ls-tree -r --name-only baf1cdf67 -- docs/exports` → 0 paths. | -| F8 | Pages triggers already cover the edit surface | **holds** | `pages.yml:6-22,25-41` include `docs/site/**`, `packages/**`, `plugins/**`, `.llm/tools/docs/**`, `deno.json`. Note the `classify` job can skip the build by policy (`ci-classify-changes.ts`); root `deno.json` **tasks-only** changes → `pages:false`, package source/`packages/*/deno.json` changes → `pages:true`, `.llm/tools/docs/**` → `pages:true`. So a drift step in the build job fires for every input that can change export truth. | -| SA-1 T4 | Existing test passes | **holds** | `deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts` → `TEST_RAW_EXIT=0`, `1 passed \| 0 failed`. The single test exercises pure functions (`deriveExpectedExports`/`parseDocContent`/`checkExportsDrift`), not process exit. | -| Contract | Nine `fileSurfaces`, `fresh-browser` in `provingGates` | **holds** | `leaf-contracts.json` entry `reference-export-drift-gate` lines 1129-1149. Divergence from SA-1 is real and is upstream's. | -| Head | Branch diff vs base | **plan-only** | `git diff --name-status baf1cdf67 a3f6b87b5` → four added `.llm/runs/...` files only. | - -## Judgement on the eight questions - -1. **A1** — see table. Not "wired to nothing"; wired indirectly and fail-closed via `docs:accuracy`. - Nothing missed beyond what research F1 records; no workflow runs it. Plan's S2 is the right - remediation and does not claim prior work. -2. **A3** — the four Step-0 symbols hold; `paginatedQuery` is real; **three further files were - missed** (B1). -3. **`paginated-query.ts:6`** — confirmed with `deno doc`. -4. **D5 / D2-D4** — false positives are real and reproduced to the digit. The discriminated policy - makes a skipped symbol gate a config-level machine-readable fact (mode + mandatory nonempty - reason, refusal on empty/unknown). D5 fixes the parser first; D4's `documentedNonExports` is a - reason-bearing allow-list for a table the page itself labels non-export — it does not compensate - for a parser defect and does not weaken invented-symbol detection globally. Acceptable. Two - non-blocking gaps: N2 (report), N3 (test seam). -5. **D11** — executable. Real reds surface as `OMITS`/`INVENTS`; the legitimate outlets are - documenting the symbol or an audited reason-bearing omission group, and Tier-A reviews every - group. But S1's proof line reads "direct drift command raw exit 0 only after … reconcile", which - pressures toward green; N1 asks the plan to state that an honest residual red at S1 is reported - red, not tuned away. -6. **SA-1 justification** — a persistent test is required: the refusal paths are the load-bearing - semantics and a one-off probe cannot fail CI. The path is bounded to assertions. It is sufficient - for the four named refusal cases only if the checker exposes a seam the test can drive without - editing product code (N3). -7. **`fresh-browser` waiver** — correct. `catalog.ts:55` maps it to `deno task test:browser` = - `packages/fresh/deno.json:26` → `packages/fresh/tests/form-navigation_browser.ts`, a browser test - of `@netscript/fresh` form navigation. Nothing in the ten paths touches `packages/fresh`, any - route/island/component/CSS. Tier-A's caveat (the rewritten page is Lume-rendered) is about the - docs build, which Pages already covers via `deno task build` (`check:source-format` → lume → - `check:rendered-output`), not about `fresh-browser`. Not run; remains `NOT_RUN`. -8. **Four live rows** — rows 2, 3, 4 (Fresh UI repair, machine-readable omissions, runbook + wiring) - are closed by S1/S2 as designed. Row "Contracts inventory advertises no non-exports" (issue row - 2) is closed by the JSDoc fix plus the already-green reference page. Issue row 1 is **not** - honestly reconciled — B1. +| Field | Value | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Evaluated head | `80046696e6b192c5448aba6b3b0b619faeabac21` — local `git rev-parse HEAD`, `git ls-remote origin`, and `gh pr view 1666 headRefOid` all equal; no mismatch | +| Base | `baf1cdf67a4e931af17b4772ddf6101f36152184` (`git merge-base HEAD origin/main`) | +| PR / issue | #1666 (draft, base `main`) / `Closes #1296` | +| Cycle | **2 of 2** (cycle 1 = `FAIL_PLAN` at `5d229e0f3`, preserved as `plan-eval-cycle-1.md`) | +| Prior heads | plan `9d0b4bf12`, SA-1 `a3f6b87b5`, cycle-1 verdict `5d229e0f3`, SA-1a `cb91b225d`, SA-2 `80046696e` | +| Evaluator session | Claude Code session `580832d7-53e8-4828-ad41-e2f9219c9340` (background job `0e2d1e57`), fresh and separate from Codex author thread `01a005d2-7c9d-7dd1-b6fc-531b72dc14e4` | +| Route | native Claude **Fable 5**, formal PLAN-EVAL, opposite family to the GPT-5.6 Sol author | +| Artifacts evaluated | `plan.md` (SA-2 amended), `scope-amendment.md` (SA-1/SA-1a/SA-2), `research.md`, `implement.md` (historical, unedited), issue #1296, frozen `leaf-contracts.json` entry | +| Surface / archetype | frozen `6 — CLI / Tooling`; overlays `frontend`, `docs` | +| **Verdict** | **`PASS`** | + +Artifact-only. No product, config, generated, lock, doctrine, debt, or central-state file was +modified. `fresh-browser` stays `NOT_RUN` (N/A / waived, SA-1 A2); no Aspire/Docker/browser/`e2e:cli` +was fired. At exit the four Contracts JSDoc examples are **still unfixed** in the tree +(`grep -c "from '@netscript/contracts';"` → 1 each in `paginated-query.ts`, `transform-helpers.ts`, +`schemas/filters.ts`, `schemas/pagination.ts`); `git status` is clean apart from this artifact. + +## Premise corrections — verified, not inherited + +- `implement.md:43,47` ("wired to nothing" / "guards nothing") is a **known-stale supervisor + premise**, deliberately left unedited as history. It is not reported as a contradiction. +- Cycle 1's claim "No workflow runs `docs:accuracy`/`docs:maintenance`/`docs-accuracy`" was + **false**. Re-derived chain at head: + `ci.yml:364-367` step *Docs accuracy check* (`if: env.RUN == 'true'`, quality job `:282`, guard + `:287` `draft == false`, `RUN = classify-failed || needs_deno || needs_docs` at `:291`) → + `run-gate.ts --gate docs-accuracy` → `catalog.ts:59` `'docs-accuracy' → ['deno','task','docs:accuracy']` + → `deno.json:85` → `check-accuracy-and-discoverability.ts:292-301` spawns + `deno run --allow-all .llm/tools/docs/check-exports-drift.ts`, prints child stdout/stderr and + throws on nonzero. **Enforcement already exists fail-closed for qualifying non-draft CI; the row-5 + residual is discoverability** (no `docs:exports-drift` task, no named workflow step, no runbook). + `research.md` F1 and `plan.md` (goal, live-acceptance row 4, D9, S2, risk "gate-catalog + indirection") state exactly this — neither overstated nor understated. `grep -rn docs-accuracy + .github/workflows/` → `ci.yml:285,366,367`, `EXIT=0`. + +## Judgement on the eight questions (re-derived) + +1. **B1 closure — full inventory.** Every `from '@netscript/contracts…'` in the package (`*.ts`, + `*.tsx`, `*.md`, tests excluded): 14 lines. Publish set (`deno.json` `publish.include`): + `README.md`, `mod.ts`, `crud.ts`, `query.ts`, `transform.ts`, `src/**`, `crud/**`, `schemas/**`. + + | Line | Symbols → entrypoint | `deno doc --no-lock --filter` | + | --------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------- | + | `README.md:52` | `baseContract`, `OffsetPaginationMetaSchema`, `OffsetPaginationQuerySchema` → root | root `0/0/0` — correct | + | `mod.ts:10` | `baseContract`, `OffsetPaginationQuerySchema` → root | root `0/0` — correct | + | `query.ts:6` | `paginatedQuery` → `/query` | query `0` — correct | + | `crud.ts:6`, `crud/create-crud-contract.ts:6,250` | `createCrudContract` → `/crud` | crud `0` — correct | + | `transform.ts:6` | `createTransformer` → `/transform` | transform `0` — correct | + | `src/application/contract-primitives.ts:72,112,144` | `baseContract`, `BaseContractRoute`, `BaseContractOutputRoute` → root | root `0/0/0` — correct | + | `src/application/paginated-query.ts:6` | `paginatedQuery` → root | root `1`, query `0` — **wrong (in plan)** | + | `src/application/transform-helpers.ts:6` | `createTransformer` → root | root `1`, transform `0` — **wrong (SA-2)** | + | `schemas/filters.ts:6` | `FilterConditionSchema`, `buildPrismaWhere` → root | root `1/1`, query `0/0` — **wrong (SA-2)** | + | `schemas/pagination.ts:6` | `PaginationInputSchema`, `createPaginatedOutput` → root | root `1/1`, query `0/0` — **wrong (SA-2)** | + + Exactly four wrong-root lines, all covered by D8/SA-2 with the correct ruled entrypoints. **No + fifth wrong-root example exists in the publish set.** Cross-package check: no `packages/**` or + `plugins/**` file outside `packages/contracts` imports any of the six symbols from the root + (`grep … EXIT=1`). F3/F4 are complete and accurate. +2. **`Closes #1296` honesty.** Row 1: all four residual lines in S1 → met at merge. Row 2: + `contracts` mapping is `checkSymbols: true`, checker `PASS` (`DRIFT_RAW_EXIT=0`) → baseline-met, + preserved. Row 3/4: S1 (six-entrypoint page repair, discriminated reason-bearing coverage, D2-D7). + Row 5: runbook (S1, D10) + named task/Pages step (S2, D9) over the already-enforced chain. The + closing keyword is earned by the plan as amended; no row is left unmet at merge. The plan and PR + body both say honesty comes from SA-2's rescope, not from the baseline — correct. +3. **Thirteen-path discipline.** Enumerated: frozen nine (six edit + `docs/exports`, + `contract-primitives.ts`, `src/public/mod.ts` do-not-touch) + SA-1 test path + SA-2 three JSDoc + paths = 13. S1 lists 7 implementation paths, S2 lists 3, do-not-touch 3 → 13, one-for-one. Every + operational count in `plan.md` reads **thirteen** (`:7,46,178,202,266`) and every refusal reads + **fourteenth** (`:79,179,202`); S3, validation row 11, and the risk guard are all bound to 13. + The remaining "nine" mentions are the frozen-contract count and the unrelated `doc:lint` + baseline, both correctly labelled. `leaf-contracts.json` still freezes nine — SA-1 A5 records that + as coordinator-owed upstream reconciliation. +4. **N3 seam.** At head `checkDrift()` takes no argument, iterates the hardcoded + `AUTHORITATIVE_MAPPING`, and calls `Deno.exit(1)` internally (`check-exports-drift.ts:376-467`); + the only test exercises the pure functions. SA-2's `checkDrift(mapping): Promise` + + `if (import.meta.main) Deno.exit(await checkDrift(AUTHORITATIVE_MAPPING))` makes the four refusal + cases assertable inside the authorized surface: empty/malformed reason and unknown mode are + mapping-validation refusals that need no files; invented and omitted symbol need a mapping whose + `packagePath`/`docPath` resolve under `Deno.cwd()` — achievable from the test file alone via + `Deno.makeTempDir()` fixtures with cwd-relative paths (or `Deno.chdir`), because the test task + runs `--allow-all`. Moving the exit out of `checkDrift` is what makes this testable at all; the + plan does exactly that. Validation row 1 is bound to this seam. SA-1's persistence promise is + satisfiable. +5. **N1 vs D11.** S1 "Proves" no longer requires raw exit 0; the N1 bullet states an honest + residual red is committed red with omissions/inventions and raw exit; validation row 2 says "A + residual red is preserved under N1 rather than blocking the S1 commit". D11 forbids tuning quiet. + The plan cannot be satisfied by silencing the checker. +6. **N2.** S1 introduces an unconditional per-package mode/reason/omission-count report before the + terminal verdict; validation row 2 requires it every run. A terminal `PASS` cannot hide + `entrypoints-only` packages (`plugin`, `queue`, `sdk`, `service` today; `fresh-ui` promoted to + complete). +7. **N4/N5.** `pages.yml:143-157`: build steps carry `if: env.RUN == 'true'`; snippets runs from + root, build/links/caveats use `working-directory: docs/site`. Plan S2/N4 puts the new step at + repo root with no `working-directory` behind the same guard — correct for a checker that joins + `Deno.cwd()`. `pages-workflow_test.ts` asserts snippets < lume order and lume cwd only; a new + step does not break it (risk row covers refusal if it did). N5: `deno.json:85` already grants + `--allow-run=deno`, so `deno task docs:exports-drift` is spawnable; the plan keeps the existing + decode-print-throw at `:296-300`. +8. **JSR proportionality.** Contracts is published; publish set includes all four files (`src/**`, + `schemas/**`); the JSR table names the delta as shipped JSDoc prose only, no export/API/schema + change; export map `. ./crud ./query ./transform` unchanged; zero `@netscript/*` pins (verified); + Fresh UI pins `jsr:@netscript/sdk@0.0.6/{auto-update,desktop}` exact (`fresh-ui/deno.json:16-17`); + root `isolatedDeclarations: true` (`deno.json:174`) → canonical `publish:dry-run` required and + planned; baseline doc-lint reds recorded as red. Proportionate. ## Plan-Gate checklist -| Plan-Gate item | Result | Evidence / location | -| --------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Research present and current | FAIL | `research.md` re-baselined at head, load-bearing findings F1/F4/F5/F6 reproduce; but F3/F4's row-1 inventory is incomplete (B1). | -| Decisions locked | PASS | D1-D11 with rationale; SA-1 leaves them intact. | -| Open-decision sweep | FAIL | The three out-of-surface JSDoc files (B1) are an unflagged decision that changes what the PR may close; not safe to defer. | -| Commit slices (< 30, gate + files each) | PASS | S1-S3 ordered, files and proofs named. | -| Risk register | PASS | present; "exclusion list becomes a hiding place" mitigated by review. | -| Gate set selected | PASS | frozen gates minus waived `fresh-browser` (SA-1 A2), plus JSR audit; validation table rows 1-11. | -| Deferred scope explicit | FAIL | "The already-correct Contracts root exports and `contract-primitives.ts` JSDoc" is explicit, but the deferral list silently omits three shipped Contracts JSDoc defects that row 1 requires (B1). | -| jsr-audit surface scan (pkg/plugin) | PASS | Contracts publish delta named honestly; Fresh UI no member delta; baseline doc-lint reds recorded as red; pins verified. Under fix (a) the JSR table gains three more prose-only files in the same publish set. | +| Plan-Gate item | Result | Evidence / location | +| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Research present and current | PASS | `research.md` re-baselined at `baf1cdf67`; F1 chain, F3/F4 nine-line inventory + six-symbol table, F5 six entrypoints, F8 triggers all reproduce at head. | +| Decisions locked | PASS | D1-D11 with rationale; D8 widened to four files by SA-2; SA-2 governs on conflict. | +| Open-decision sweep | PASS | Sweep table resolves the three PLAN-EVAL-discovered files (SA-2), `docs/exports`, policy format, parser boundary, wiring, `fresh-browser`; evaluator sweep found none. | +| Commit slices (< 30, gate + files each) | PASS | S1-S3 ordered, 13 paths accounted for one-for-one, each names files and proof. | +| Risk register | PASS | Present; guards bound to thirteen; exclusion-as-hiding-place, parser, duplicate-execution, lock churn covered. | +| Gate set selected | PASS | Frozen gates minus waived `fresh-browser` (`NOT_RUN` preserved), plus JSR audit; validation rows 1-11. | +| Deferred scope explicit | PASS | Explicit deferrals list; four incorrect imports now in S1, not deferred; doc-lint debt, MySQL, Fresh UI source, other packages' prose deferred with reasons. | +| jsr-audit surface scan (pkg/plugin) | PASS | Contracts prose-only publish delta named honestly; pins/exports/isolated-declarations verified; baseline reds reported red. | ## Open-decision sweep (evaluator-run) -- **B1** (blocking) — fix path (a) or (b) above; coordinator's call. -- No other decision would force checker/doc rework if deferred. - -## Non-blocking findings (address in the same cycle; not required for PASS) - -- **N1 — S1 proof wording vs D11.** State in S1 that if honest reconciliation leaves a residual red, - S1 commits with the residual reported red (per implement.md "wiring a gate that then fails on - baseline is a legitimate outcome") rather than requiring exit 0 as its commit condition. -- **N2 — visible coverage report.** The policy is machine-readable in config, but the checker's - terminal `PASS` line would still be silent about which packages ran in `entrypoints-only` mode. - Have the checker print, per package, the coverage mode, reason, and omission-group counts on every - run so a green never hides five entrypoint-only packages. -- **N3 — test seam.** Name how `check-exports-drift_test.ts` will assert the four refusal cases: - export a policy validator (or make `checkDrift(mapping)` injectable) and bind `Deno.exit(1)` to it - in `main`. `AUTHORITATIVE_MAPPING` is a hardcoded const, so a subprocess test cannot inject a - malformed policy without a seam; SA-1's "asserted nonzero" needs this to be satisfiable without - touching product code beyond the in-scope checker. -- **N4 — Pages step cwd.** The checker uses `Deno.cwd()` and repo-relative paths; the - build/links/caveats steps use `working-directory: docs/site` (`docs:snippets` runs from root). The - new step must run from repo root (`deno task docs:exports-drift` with no `working-directory`), and - it must sit behind the same `if: env.RUN == 'true'` guard as the other build steps. -- **N5 — `docs:accuracy` calling the named task.** With `--allow-run=deno` the child - `deno task docs:exports-drift` is permitted; keep the child's stdout/stderr surfaced on failure as - today (`check-accuracy-and-discoverability.ts:296-300`). - -## Commands fired (all read-only; raw exits unpiped) +None. No decision the plan leaves open would force checker/doc/JSDoc rework if deferred. + +## Non-blocking observations (implementation lane; not required for PASS) + +- **O1 — `schemas/pagination.ts` example free identifiers.** Its `@example` uses `baseContract` and + `UserSchema` without importing/declaring them. The SA-2 import-subpath-only edit corrects the + export truth (row 1's operative test) but cannot make that fragment compile standalone. SA-1 A4's + "clears all four known example-compile failures" therefore holds for import resolution only; if + #1533's compiler resolves free identifiers, this file may still be red there. Not this leaf's + scope; record it for #1533, not as a fourteenth path. +- **O2 — N3 fixture mechanics.** For the invented/omitted cases, `checkDrift(mapping)` reads + `join(Deno.cwd(), packagePath|docPath)` and runs `deno doc`; the test will need temp fixtures with + cwd-relative paths (or an optional `root` parameter on `checkDrift`, which stays inside the + authorized checker path). Either is within the thirteen; the plan need not change. +- **O3 — live acceptance table labels.** `plan.md` folds issue rows 1 and 2 into one row labelled + "Contracts reference inventory advertises no non-exports"; `research.md` keeps them separate. + Cosmetic; the underlying claims are correct in both. + +## Commands fired (read-only; raw exits unpiped) ```text -git rev-parse HEAD -> a3f6b87b599e778db950daf6ccaecd847c088d19 -deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts -> 0 (PASS) -grep -rnE 'check-exports-drift|exports-drift' deno.json .github/workflows/ -> 1 -grep -rn 'docs-accuracy\|docs:maintenance\|docs:accuracy' .github/workflows/ -> 1 -deno task docs:accuracy -> 0 (PASS) -deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts -> 0 (1 passed) -deno doc --no-lock --filter packages/contracts/{mod,query,transform}.ts (see B1 / A3) -> as tabulated -deno run --no-lock --allow-read --allow-run .llm/tmp/pe-count.ts -> 0 (168) -deno run --no-lock --allow-read --allow-run .llm/tmp/pe-f6.ts -> 0 (168/78/162) -test -e docs/exports -> 1 -fresh-browser -> NOT_RUN (waived, not restated) +git rev-parse HEAD / git ls-remote origin / gh pr view 1666 -> 80046696e x3, draft=true +git merge-base HEAD origin/main -> baf1cdf67 +git diff --name-status baf1cdf67 HEAD -> 6 added .llm/runs/... files only +grep -rn 'docs-accuracy|docs:accuracy|docs:maintenance|exports-drift' .github/workflows/ -> 0 (ci.yml:285,366,367) +sed ci.yml:280-290,360-370 ; catalog.ts:55,59 ; deno.json:85,90 ; check-accuracy…ts:285-305 +grep -rnoE "from ['\"]@netscript/contracts[^'\"]*['\"]" packages/contracts (ts/tsx/md, no tests) -> 14 lines +deno doc --no-lock --filter <12 symbols> packages/contracts/{mod,query,transform,crud}.ts -> as tabulated +grep six symbols from root outside packages/contracts -> 1 (none) +deno run --no-lock --allow-read --allow-env --allow-run .llm/tools/docs/check-exports-drift.ts -> 0 (PASS) +deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts -> 0 (1 passed) +grep pages.yml guards/cwd ; pages-workflow_test.ts assertions ; fresh-ui deno.json exports/pins ; deno.json:174 +grep -c "from '@netscript/contracts';" -> 1 each (unfixed at exit) +fresh-browser -> NOT_RUN (waived, not restated) ``` -Scratch: `.llm/tmp/pe-*.{ts,out,json}` only. No implementation, product, config, generated, plan, -research, amendment, lock, doctrine, debt, or central-state file was modified. +No scratch was written under measured roots. Only this artifact and the `plan-eval-cycle-1.md` +rename were produced. From 6788406036b0ce294262b626b5b3cf0f450df403 Mon Sep 17 00:00:00 2001 From: Rickylabs Date: Sat, 15 Aug 2026 19:49:05 +0200 Subject: [PATCH 08/23] fix(docs): enforce reference export coverage --- .../context-pack.md | 36 + .../reference-export-drift-gate/drift.md | 11 + .../reference-export-drift-gate/worklog.md | 70 ++ .llm/tools/docs/check-exports-drift.ts | 748 +++++++++++++----- .llm/tools/docs/check-exports-drift_test.ts | 103 +++ docs/site/reference/fresh-ui/index.md | 396 ++++++---- packages/contracts/schemas/filters.ts | 2 +- packages/contracts/schemas/pagination.ts | 2 +- .../src/application/paginated-query.ts | 2 +- .../src/application/transform-helpers.ts | 2 +- 10 files changed, 1005 insertions(+), 367 deletions(-) create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/context-pack.md create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/drift.md create mode 100644 .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/worklog.md diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/context-pack.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/context-pack.md new file mode 100644 index 0000000000..dc34031076 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/context-pack.md @@ -0,0 +1,36 @@ +# Context pack — reference-export-drift-gate + +## Current state + +- Branch: `fix/reference-export-drift-gate` +- Base: `baf1cdf67a4e931af17b4772ddf6101f36152184` +- PR: #1666, draft, closes exactly #1296 +- PLAN-EVAL: cycle 2 `PASS` at `45c249b9c` +- Implementation: S1 complete; awaiting coordinator slice review +- S2/S3: not started and not authorized in this pass +- `fresh-browser`: N/A / waived, `NOT_RUN`; no runtime lease + +## S1 result + +The checker now makes coverage mode explicit and reason-bearing, validates policy fail-closed, +reports every package's mode/reason/group counts, and exposes an injectable exit-code seam. Fresh UI +is complete-mode with all 168 live symbols documented. Its seven extra Dropzone inventory names are +machine-readably classified as the copy-source non-exports the page visibly says they are. + +All four residual Contracts examples now import from the entrypoint that exports their symbols. The +diff is limited to the import subpath line in each file. + +## Evidence state + +- Focused checker tests: 6 passed / 0 failed. +- Direct checker: raw exit 0, PASS. +- Docs source format: raw exit 0. +- Docs accuracy: raw exit 0. +- Contracts doc lint: raw exit 1 with the accepted baseline nine private-type-ref findings. +- Browser/runtime/Aspire/Docker/E2E: `NOT_RUN`. + +## Resume rule + +Do not begin S2. First obtain the coordinator's substantive review of the exact pushed S1 head. If +review authorizes continuation, resume with S2's named-task/aggregate/Pages discoverability wiring; +do not fold S3 into it. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/drift.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/drift.md new file mode 100644 index 0000000000..ed2555680f --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/drift.md @@ -0,0 +1,11 @@ +# Drift log — reference-export-drift-gate + +## S1 + +- **Implementation drift:** none. The seven S1 implementation paths match the approved plan. +- **Evidence drift:** none. Intermediate direct-checker reds were preserved and recorded under + N1/D11; final green followed documentation and policy-order reconciliation, not a widened + exclusion or narrowed parser. +- **Known adjacent finding:** PLAN-EVAL O1 notes that `schemas/pagination.ts` uses free example + identifiers beyond its import line. SA-2 authorizes only the import-subpath edit, so the remainder + stays with #1533's example-compile work and did not trigger a fourteenth-path rescope. diff --git a/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/worklog.md b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/worklog.md new file mode 100644 index 0000000000..0fbc655479 --- /dev/null +++ b/.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/worklog.md @@ -0,0 +1,70 @@ +# Worklog — reference-export-drift-gate + +## S1 — explicit coverage and reference reconciliation + +- Authorization: PLAN-EVAL cycle 2 `PASS` at evaluator commit `45c249b9c`, evaluated over SA-2 head + `80046696e`. +- Scope: S1 only. S2 and S3 were not started. +- Commit: the S1 commit containing this artifact; the pushed SHA is recorded in the structured PR + comment. + +### Implementation + +- Replaced boolean `checkSymbols`/`excludedSymbols` state with a discriminated, reason-bearing + `symbolCoverage` policy. +- Added fail-closed runtime policy validation, sorted exact omission groups, stale-omission checks, + and explicit documented-non-export checks. +- Added an exported injectable `checkDrift(mapping): Promise` seam and bound process status + only under `if (import.meta.main)`. +- Restricted symbol parsing to tables whose first trimmed header cell is exactly `Symbol`; prop, + field, shape, and category tables no longer enter the inventory. Display generic suffixes such as + `` normalize to the exported name. +- Promoted Fresh UI to complete coverage across all six entrypoints. Its policy excludes no exported + symbols. The only allowed doc-only names are seven Dropzone copy-source contracts, grouped with + the same reason as the page's explicit non-export label. +- Repaired the Fresh UI reference for ActionMenu, Combobox, all public interactive contracts, + desktop chrome, registry contracts, render-UI types, DataGrid contexts, and the maintainer + derivation/update runbook. +- Corrected exactly the four authorized Contracts `@example` import subpath lines. No runtime, type, + export, or schema line changed. + +### N1 / D11 evidence + +The checker was not tuned quiet: + +1. After policy/parser implementation but before reference reconciliation, the direct checker + returned raw exit 1 with the real Fresh UI omissions plus unsorted policy groups. It reported no + parser-generated inventions. +2. After documenting the live Fresh UI surface, the checker returned raw exit 1 for only the + inherited Telemetry omission group's unsorted order. The group was sorted mechanically without + changing its 154-symbol membership. +3. The final direct checker returned raw exit 0. Fresh UI measured 168 expected exports and 175 + documented inventory names: zero omissions and exactly the seven explicitly classified Dropzone + non-exports. No exported Fresh UI symbol is omitted by policy. + +### Evidence + +| Proof | Result | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| Structured check wrapper on checker + checker test | raw exit 0; 2 files selected, 0 findings | +| Structured focused-test wrapper | raw exit 0; 6 passed, 0 failed | +| Structured lint wrapper | raw exit 0; 6 TypeScript files selected, 0 findings | +| Structured format wrapper | raw exit 0; all 10 changed files selected, 0 findings | +| Four refusal cases | empty/malformed reason, unknown mode, invented symbol, omitted symbol each asserted return code 1 | +| Direct exports/symbol drift | raw exit 0; eight per-package mode/reason/group reports; terminal PASS | +| Fresh UI live inventory diagnostic | raw exit 0; expected 168, documented 175, omissions 0, inventions exactly seven classified Dropzone names | +| Docs source format | raw exit 0; `Docs source format: OK` | +| `deno task docs:accuracy` | raw exit 0; terminal `docs accuracy: PASS` | +| Six affected Contracts symbols on ruled entrypoints | raw exit 0 each via `deno doc --no-lock --filter` | +| Contracts JSDoc diff | exactly one import-subpath line in each of four authorized files | +| Contracts full-export `doc:lint` | raw exit 1; unchanged baseline nine `private-type-ref` diagnostics, zero on `/query` and `/transform` | +| Thirteen-path audit | raw exit 0; seven approved S1 implementation paths plus three slice artifacts, no unauthorized path | +| `fresh-browser` | `NOT_RUN` — N/A / waived; no runtime lease | + +No Aspire, Docker, browser, `e2e:cli`, scaffold/runtime smoke, publish, S2 task/workflow wiring, or +S3 durable gate receipt was fired. + +## Handoff + +S1 stops after commit, explicit-refspec push, and its structured PR comment. The coordinator owns +the required substantive slice review. S2 must not begin until that review authorizes continuation. diff --git a/.llm/tools/docs/check-exports-drift.ts b/.llm/tools/docs/check-exports-drift.ts index b1630dffd4..4237e9db00 100644 --- a/.llm/tools/docs/check-exports-drift.ts +++ b/.llm/tools/docs/check-exports-drift.ts @@ -1,24 +1,55 @@ import { join } from '@std/path'; +export interface SymbolOmissionGroup { + reason: string; + symbols: readonly string[]; +} + +export type SymbolCoverage = + | { + mode: 'complete'; + reason: string; + omittedSymbols?: readonly SymbolOmissionGroup[]; + documentedNonExports?: readonly SymbolOmissionGroup[]; + } + | { + mode: 'entrypoints-only'; + reason: string; + }; + export interface PackageMapping { name: string; packagePath: string; // relative to root, e.g. "packages/plugin" docPath: string; // relative to root, e.g. "docs/site/reference/plugin/index.md" packageName: string; // e.g. "@netscript/plugin" - excludedExports?: string[]; // list of exported keys to ignore, e.g. ["./internal"] - checkSymbols?: boolean; // if true, verifies every exported symbol is listed in the doc - excludedSymbols?: string[]; // list of symbol names to ignore + excludedExports?: readonly string[]; // exported keys intentionally outside the public reference + symbolCoverage: SymbolCoverage; } -export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ +export const AUTHORITATIVE_MAPPING: readonly PackageMapping[] = [ { name: 'fresh-ui', packagePath: 'packages/fresh-ui', docPath: 'docs/site/reference/fresh-ui/index.md', packageName: '@netscript/fresh-ui', excludedExports: [], - checkSymbols: false, - excludedSymbols: [], + symbolCoverage: { + mode: 'complete', + reason: 'All six published entrypoints are maintained as one complete reference surface.', + documentedNonExports: [{ + reason: + 'Dropzone is an explicitly labeled copy-source registry component, not a package export.', + symbols: [ + 'DROPZONE_INGEST_SOURCES', + 'DROPZONE_REJECTED_REASONS', + 'DropzoneIngestDetails', + 'DropzoneIngestSource', + 'DropzoneProps', + 'DropzoneRejectedFile', + 'DropzoneRejectedReason', + ], + }], + }, }, { name: 'plugin', @@ -26,8 +57,11 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/plugin/index.md', packageName: '@netscript/plugin', excludedExports: [], - checkSymbols: false, - excludedSymbols: [], + symbolCoverage: { + mode: 'entrypoints-only', + reason: + 'This page currently guarantees package entrypoint coverage; complete symbol prose is tracked separately.', + }, }, { name: 'config', @@ -35,8 +69,10 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/config/index.md', packageName: '@netscript/config', excludedExports: [], - checkSymbols: true, - excludedSymbols: [], + symbolCoverage: { + mode: 'complete', + reason: 'The config reference is maintained as a complete published-symbol inventory.', + }, }, { name: 'contracts', @@ -44,8 +80,10 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/contracts/index.md', packageName: '@netscript/contracts', excludedExports: [], - checkSymbols: true, - excludedSymbols: [], + symbolCoverage: { + mode: 'complete', + reason: 'The contracts reference is maintained as a complete published-symbol inventory.', + }, }, { name: 'queue', @@ -53,8 +91,11 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/queue/index.md', packageName: '@netscript/queue', excludedExports: [], - checkSymbols: false, - excludedSymbols: [], + symbolCoverage: { + mode: 'entrypoints-only', + reason: + 'This page currently guarantees package entrypoint coverage; complete symbol prose is tracked separately.', + }, }, { name: 'sdk', @@ -62,8 +103,11 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/sdk/index.md', packageName: '@netscript/sdk', excludedExports: [], - checkSymbols: false, - excludedSymbols: [], + symbolCoverage: { + mode: 'entrypoints-only', + reason: + 'This page currently guarantees package entrypoint coverage; complete symbol prose is tracked separately.', + }, }, { name: 'service', @@ -71,8 +115,11 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/service/index.md', packageName: '@netscript/service', excludedExports: [], - checkSymbols: false, - excludedSymbols: [], + symbolCoverage: { + mode: 'entrypoints-only', + reason: + 'This page currently guarantees package entrypoint coverage; complete symbol prose is tracked separately.', + }, }, { name: 'telemetry', @@ -80,163 +127,171 @@ export const AUTHORITATIVE_MAPPING: PackageMapping[] = [ docPath: 'docs/site/reference/telemetry/index.md', packageName: '@netscript/telemetry', excludedExports: [], - checkSymbols: true, - excludedSymbols: [ - 'OtelAiTracer', - 'TelemetryQueryPort', - 'TelemetryQueryOptions', - 'otelDenoDescriptor', - 'OtelDenoTracerProvider', - 'OtelDenoPropagator', - 'OtelDenoMeter', - 'OtelDenoSpanLink', - 'createOtelDenoProvider', - 'createOtelDenoPropagator', - 'createOtelDenoMeter', - 'createOtelDenoSpanLink', - 'SdkTracerProviderHandle', - 'SdkMeterProviderHandle', - 'SdkBinding', - 'SdkLoader', - 'defaultSdkLoader', - 'otelSdkDescriptor', - 'OtelSdkTracerProvider', - 'OtelSdkSpanLink', - 'createOtelSdkProvider', - 'createOtelSdkSpanLink', - 'TelemetryProviderSelection', - 'CreateTelemetryProviderInput', - 'createTelemetryProvider', - 'metricQueryFilterSchema', - 'resourceQueryFilterSchema', - 'TelemetryQueryValidationError', - 'traceQueryFilterSchema', - 'validateMetricQueryFilter', - 'validateResourceQueryFilter', - 'validateTraceQueryFilter', - 'MetricQueryFilter', - 'ResourceQueryFilter', - 'TelemetryAttributeValue', - 'TelemetryLog', - 'TelemetryMetric', - 'TelemetryMetricPoint', - 'TelemetryMetricType', - 'TelemetryOtlpJson', - 'TelemetryResource', - 'TelemetrySpan', - 'TelemetrySpanEvent', - 'TelemetrySpanKind', - 'TelemetrySpanLink', - 'TelemetryTrace', - 'TraceQueryFilter', - 'AspireTelemetryQuery', - 'createAspireTelemetryQuery', - 'AspireTelemetryQueryOptions', - 'createTelemetryQuery', - 'RecordedSpanEvent', - 'RecordedSpanSnapshot', - 'InMemorySpanRecorder', - 'createInMemorySpanRecorder', - 'getTriggerTracer', - 'getTraceContext', - 'parseTraceState', - 'DeprecatedMessagingAttributeAliases', - 'DeprecatedJobAttributeAliases', - 'DeprecatedExecutionAttributeAliases', - 'DeprecatedSagaAttributeAliases', - 'SagaAttributeName', - 'GenAiAttributeName', - 'TelemetryAttributeBuilderValue', - 'TelemetryAttributeBuilderMap', - 'OTEL_SEMCONV_STABILITY_OPT_IN', - 'NETSCRIPT_SEMCONV_STABILITY_OPT_IN', - 'NETSCRIPT_ATTRIBUTE_ROOT', - 'NETSCRIPT_ATTRIBUTE_ALIAS_WINDOW', - 'NETSCRIPT_ATTRIBUTE_ALIAS_MODE', - 'TelemetryConventionId', - 'NetScriptAttributeDomain', - 'MessageContext', - 'EnqueueOptions', - 'ListenOptions', - 'MessageQueue', - 'TracedQueueOptions', - 'TracedMessageContext', - 'TracedQueue', - 'traceQueue', - 'ScheduledJobDefinition', - 'SchedulerTickContext', - 'JobDispatchContext', - 'TracedDispatchOptions', - 'traceSchedulerTick', - 'TracedJobDefinition', - 'TracedJobExecution', - 'JobExecutionOptions', - 'TracedJobResult', - 'TracedWorkerConfig', - 'WorkerMetricValues', - 'WorkerMetricInstruments', - 'createWorkerMetricInstruments', - 'getWorkerMetricInstruments', - 'recordSharedWorkerMetrics', - 'withChildSpan', - 'createProviderRegistration', - 'TELEMETRY_PROVIDER_REGISTRATION_NAME', - 'registerORPCInstrumentation', - 'ErrorClassification', - 'ErrorClassifier', - 'LogLevel', - 'RootInterceptorOptions', - 'RootInterceptor', - 'ClientInterceptorOptions', - 'AnyInterceptor', - 'GenericHandlerOptions', - 'createHonoTracingMiddleware', - 'HonoTracingMiddleware', - 'HonoTracingMiddlewareOptions', - 'AiTelemetryAttributes', - 'AiTelemetryAttributeValue', - 'createOtelAiTelemetryPort', - 'CreateOtelAiTelemetryPortOptions', - 'OtelAiTelemetryPort', - 'OtelAiTelemetrySpan', - 'AttributeValue', - 'Exception', - 'SpanContext', - 'SpanOptions', - 'SpanStatus', - 'TimeInput', - 'TraceState', - 'Counter', - 'Histogram', - 'Meter', - 'MeterPort', - 'MetricInstrumentOptions', - 'ObservableCallback', - 'ObservableGauge', - 'ObservableResult', - 'PropagationExtractCarrier', - 'PropagationInjectCarrier', - 'PropagatorPort', - 'SpanLinkPort', - 'TelemetryProviderDescriptor', - 'TelemetryProviderOptions', - 'TracerProviderPort', - 'createFanInLinks', - 'FanInLinkMessage', - 'getParentContextFromHeaders', - 'PropagationHeaders', - 'NETSCRIPT_TELEMETRY_ENV_VARS', - 'TelemetryProviderId', - 'DEFAULT_TELEMETRY_PROVIDER_ID', - 'OTEL_SEMCONV_STABILITY_OPT_IN_VALUE', - 'markProviderRegistered', - 'clearProviderRegistration', - 'isProviderRegistered', - 'telemetryConfigSchema', - 'TelemetryConfigError', - 'validateTelemetryConfig', - 'TracedResult', - ], + symbolCoverage: { + mode: 'complete', + reason: + 'The telemetry reference curates stable entrypoints and primary APIs while classifying lower-level contracts explicitly.', + omittedSymbols: [{ + reason: + 'Low-level provider, query, instrumentation, compatibility, and framework integration contracts remain API-reference-only.', + symbols: [ + 'AiTelemetryAttributes', + 'AiTelemetryAttributeValue', + 'AnyInterceptor', + 'AspireTelemetryQuery', + 'AspireTelemetryQueryOptions', + 'AttributeValue', + 'clearProviderRegistration', + 'ClientInterceptorOptions', + 'Counter', + 'createAspireTelemetryQuery', + 'createFanInLinks', + 'createHonoTracingMiddleware', + 'createInMemorySpanRecorder', + 'createOtelAiTelemetryPort', + 'CreateOtelAiTelemetryPortOptions', + 'createOtelDenoMeter', + 'createOtelDenoPropagator', + 'createOtelDenoProvider', + 'createOtelDenoSpanLink', + 'createOtelSdkProvider', + 'createOtelSdkSpanLink', + 'createProviderRegistration', + 'createTelemetryProvider', + 'CreateTelemetryProviderInput', + 'createTelemetryQuery', + 'createWorkerMetricInstruments', + 'DEFAULT_TELEMETRY_PROVIDER_ID', + 'defaultSdkLoader', + 'DeprecatedExecutionAttributeAliases', + 'DeprecatedJobAttributeAliases', + 'DeprecatedMessagingAttributeAliases', + 'DeprecatedSagaAttributeAliases', + 'EnqueueOptions', + 'ErrorClassification', + 'ErrorClassifier', + 'Exception', + 'FanInLinkMessage', + 'GenAiAttributeName', + 'GenericHandlerOptions', + 'getParentContextFromHeaders', + 'getTraceContext', + 'getTriggerTracer', + 'getWorkerMetricInstruments', + 'Histogram', + 'HonoTracingMiddleware', + 'HonoTracingMiddlewareOptions', + 'InMemorySpanRecorder', + 'isProviderRegistered', + 'JobDispatchContext', + 'JobExecutionOptions', + 'ListenOptions', + 'LogLevel', + 'markProviderRegistered', + 'MessageContext', + 'MessageQueue', + 'Meter', + 'MeterPort', + 'MetricInstrumentOptions', + 'MetricQueryFilter', + 'metricQueryFilterSchema', + 'NETSCRIPT_ATTRIBUTE_ALIAS_MODE', + 'NETSCRIPT_ATTRIBUTE_ALIAS_WINDOW', + 'NETSCRIPT_ATTRIBUTE_ROOT', + 'NETSCRIPT_SEMCONV_STABILITY_OPT_IN', + 'NETSCRIPT_TELEMETRY_ENV_VARS', + 'NetScriptAttributeDomain', + 'ObservableCallback', + 'ObservableGauge', + 'ObservableResult', + 'OTEL_SEMCONV_STABILITY_OPT_IN', + 'OTEL_SEMCONV_STABILITY_OPT_IN_VALUE', + 'OtelAiTelemetryPort', + 'OtelAiTelemetrySpan', + 'OtelAiTracer', + 'otelDenoDescriptor', + 'OtelDenoMeter', + 'OtelDenoPropagator', + 'OtelDenoSpanLink', + 'OtelDenoTracerProvider', + 'otelSdkDescriptor', + 'OtelSdkSpanLink', + 'OtelSdkTracerProvider', + 'parseTraceState', + 'PropagationExtractCarrier', + 'PropagationHeaders', + 'PropagationInjectCarrier', + 'PropagatorPort', + 'RecordedSpanEvent', + 'RecordedSpanSnapshot', + 'recordSharedWorkerMetrics', + 'registerORPCInstrumentation', + 'ResourceQueryFilter', + 'resourceQueryFilterSchema', + 'RootInterceptor', + 'RootInterceptorOptions', + 'SagaAttributeName', + 'ScheduledJobDefinition', + 'SchedulerTickContext', + 'SdkBinding', + 'SdkLoader', + 'SdkMeterProviderHandle', + 'SdkTracerProviderHandle', + 'SpanContext', + 'SpanLinkPort', + 'SpanOptions', + 'SpanStatus', + 'TELEMETRY_PROVIDER_REGISTRATION_NAME', + 'TelemetryAttributeBuilderMap', + 'TelemetryAttributeBuilderValue', + 'TelemetryAttributeValue', + 'TelemetryConfigError', + 'telemetryConfigSchema', + 'TelemetryConventionId', + 'TelemetryLog', + 'TelemetryMetric', + 'TelemetryMetricPoint', + 'TelemetryMetricType', + 'TelemetryOtlpJson', + 'TelemetryProviderDescriptor', + 'TelemetryProviderId', + 'TelemetryProviderOptions', + 'TelemetryProviderSelection', + 'TelemetryQueryOptions', + 'TelemetryQueryPort', + 'TelemetryQueryValidationError', + 'TelemetryResource', + 'TelemetrySpan', + 'TelemetrySpanEvent', + 'TelemetrySpanKind', + 'TelemetrySpanLink', + 'TelemetryTrace', + 'TimeInput', + 'TracedDispatchOptions', + 'TracedJobDefinition', + 'TracedJobExecution', + 'TracedJobResult', + 'TracedMessageContext', + 'TracedQueue', + 'TracedQueueOptions', + 'TracedResult', + 'TracedWorkerConfig', + 'TraceQueryFilter', + 'traceQueryFilterSchema', + 'traceQueue', + 'TracerProviderPort', + 'traceSchedulerTick', + 'TraceState', + 'validateMetricQueryFilter', + 'validateResourceQueryFilter', + 'validateTelemetryConfig', + 'validateTraceQueryFilter', + 'withChildSpan', + 'WorkerMetricInstruments', + 'WorkerMetricValues', + ], + }], + }, }, ]; @@ -247,6 +302,7 @@ export function parseDocContent( const docSymbols = new Set(); const lines = docContent.split('\n'); let insideExportsTable = false; + let insideSymbolsTable = false; for (const line of lines) { const trimmed = line.trim(); @@ -266,18 +322,28 @@ export function parseDocContent( } } - if (line.startsWith('|') && !line.includes('---') && !line.includes('Symbol |')) { - const parts = line.split('|').map((p) => p.trim()).filter(Boolean); - if (parts.length >= 1) { - const firstCol = parts[0]; - const matches = firstCol.matchAll(/`([^`]+)`/g); - for (const m of matches) { - const val = m[1]; - if (val.includes('@netscript/') || val.startsWith('.')) continue; - const syms = val.split(/[\/,\|]/).map((s) => s.trim()).filter(Boolean); - for (const s of syms) { - docSymbols.add(s); - } + if (!trimmed.startsWith('|')) { + insideSymbolsTable = false; + continue; + } + + const tableCells = trimmed.slice(1, -1).split('|').map((cell) => cell.trim()); + if (tableCells[0] === 'Symbol') { + insideSymbolsTable = true; + continue; + } + if (!insideSymbolsTable || tableCells.every((cell) => /^:?-{3,}:?$/.test(cell))) { + continue; + } + + for (const match of tableCells[0].matchAll(/`([^`]+)`/g)) { + const groupedSymbols = match[1].split(/[\/,|]/).map((symbol) => symbol.trim()).filter( + Boolean, + ); + for (const displaySymbol of groupedSymbols) { + const normalizedSymbol = displaySymbol.replace(/<[^<>]*>$/, '').trim(); + if (normalizedSymbol && !normalizedSymbol.includes('@netscript/')) { + docSymbols.add(normalizedSymbol); } } } @@ -288,7 +354,7 @@ export function parseDocContent( export function deriveExpectedExports( packageName: string, exportsObj: any, - excludedExports: string[] = [], + excludedExports: readonly string[] = [], ): Map { const expectedExports = new Map(); const excludedSet = new Set(excludedExports); @@ -347,10 +413,12 @@ export function checkSymbolsDrift( docPath: string, expectedSymbols: Set, docSymbols: Set, + omittedSymbols: ReadonlySet = new Set(), + documentedNonExports: ReadonlySet = new Set(), ): string[] { const errors: string[] = []; for (const sym of expectedSymbols) { - if (!docSymbols.has(sym)) { + if (!omittedSymbols.has(sym) && !docSymbols.has(sym)) { errors.push( `Symbol Drift Error [${pkgName}]: Document at ${docPath} OMITS exported symbol '${sym}'`, ); @@ -364,7 +432,7 @@ export function checkSymbolsDrift( ) continue; if (sym.includes('/') || sym.startsWith('@')) continue; - if (!expectedSymbols.has(sym)) { + if (!expectedSymbols.has(sym) && !documentedNonExports.has(sym)) { errors.push( `Symbol Drift Error [${pkgName}]: Document at ${docPath} INVENTS nonexistent/unexported symbol '${sym}'`, ); @@ -373,11 +441,215 @@ export function checkSymbolsDrift( return errors; } -async function checkDrift() { +interface ValidatedMapping { + mappings: PackageMapping[]; + errors: string[]; +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function isNonemptyString(value: unknown): value is string { + return typeof value === 'string' && value.trim().length > 0; +} + +function parseOmissionGroups( + value: unknown, + field: string, + errors: string[], +): SymbolOmissionGroup[] { + if (value === undefined) return []; + if (!Array.isArray(value)) { + errors.push(`${field} must be an array when present`); + return []; + } + + const groups: SymbolOmissionGroup[] = []; + for (const [index, candidate] of value.entries()) { + const path = `${field}[${index}]`; + if (!isRecord(candidate)) { + errors.push(`${path} must be an object`); + continue; + } + if (!isNonemptyString(candidate.reason)) { + errors.push(`${path}.reason must be a nonempty string`); + } + if (!Array.isArray(candidate.symbols) || candidate.symbols.length === 0) { + errors.push(`${path}.symbols must be a nonempty array`); + continue; + } + const symbols: string[] = []; + for (const [symbolIndex, symbol] of candidate.symbols.entries()) { + if (!isNonemptyString(symbol)) { + errors.push(`${path}.symbols[${symbolIndex}] must be a nonempty string`); + } else { + symbols.push(symbol); + } + } + if (isNonemptyString(candidate.reason) && symbols.length === candidate.symbols.length) { + groups.push({ reason: candidate.reason.trim(), symbols }); + } + } + return groups; +} + +export function validateAuthoritativeMapping(mapping: unknown): ValidatedMapping { + const errors: string[] = []; + const mappings: PackageMapping[] = []; + if (!Array.isArray(mapping) || mapping.length === 0) { + return { mappings, errors: ['Authoritative mapping must be a nonempty array'] }; + } + + const names = new Set(); + for (const [index, candidate] of mapping.entries()) { + const path = `mapping[${index}]`; + if (!isRecord(candidate)) { + errors.push(`${path} must be an object`); + continue; + } + + const requiredFields = ['name', 'packagePath', 'docPath', 'packageName'] as const; + let fieldsValid = true; + for (const field of requiredFields) { + if (!isNonemptyString(candidate[field])) { + errors.push(`${path}.${field} must be a nonempty string`); + fieldsValid = false; + } + } + + if (isNonemptyString(candidate.name)) { + if (names.has(candidate.name)) errors.push(`${path}.name duplicates '${candidate.name}'`); + names.add(candidate.name); + } + + let excludedExports: string[] | undefined; + if (candidate.excludedExports !== undefined) { + if ( + !Array.isArray(candidate.excludedExports) || + !candidate.excludedExports.every(isNonemptyString) + ) { + errors.push(`${path}.excludedExports must contain only nonempty strings`); + } else { + excludedExports = [...candidate.excludedExports]; + } + } + + if (!isRecord(candidate.symbolCoverage)) { + errors.push(`${path}.symbolCoverage must be an object`); + continue; + } + const coverage = candidate.symbolCoverage; + if (!isNonemptyString(coverage.reason)) { + errors.push(`${path}.symbolCoverage.reason must be a nonempty string`); + } + + let symbolCoverage: SymbolCoverage | undefined; + if (coverage.mode === 'complete') { + const omittedSymbols = parseOmissionGroups( + coverage.omittedSymbols, + `${path}.symbolCoverage.omittedSymbols`, + errors, + ); + const documentedNonExports = parseOmissionGroups( + coverage.documentedNonExports, + `${path}.symbolCoverage.documentedNonExports`, + errors, + ); + if (isNonemptyString(coverage.reason)) { + symbolCoverage = { + mode: 'complete', + reason: coverage.reason.trim(), + omittedSymbols, + documentedNonExports, + }; + } + } else if (coverage.mode === 'entrypoints-only') { + if (coverage.omittedSymbols !== undefined || coverage.documentedNonExports !== undefined) { + errors.push(`${path}.symbolCoverage entrypoints-only mode cannot define symbol groups`); + } + if (isNonemptyString(coverage.reason)) { + symbolCoverage = { mode: 'entrypoints-only', reason: coverage.reason.trim() }; + } + } else { + errors.push(`${path}.symbolCoverage.mode is unknown: '${String(coverage.mode)}'`); + } + + if (fieldsValid && symbolCoverage) { + mappings.push({ + name: String(candidate.name), + packagePath: String(candidate.packagePath), + docPath: String(candidate.docPath), + packageName: String(candidate.packageName), + excludedExports, + symbolCoverage, + }); + } + } + + return { mappings, errors }; +} + +function printCoverageReport(mapping: unknown): void { + if (!Array.isArray(mapping) || mapping.length === 0) { + console.log('Coverage [mapping]: mode=; reason=; omission-groups=0'); + return; + } + for (const [index, candidate] of mapping.entries()) { + const record = isRecord(candidate) ? candidate : {}; + const coverage = isRecord(record.symbolCoverage) ? record.symbolCoverage : {}; + const name = isNonemptyString(record.name) ? record.name : `#${index}`; + const mode = typeof coverage.mode === 'string' ? coverage.mode : ''; + const reason = isNonemptyString(coverage.reason) ? coverage.reason.trim() : ''; + const omittedCount = Array.isArray(coverage.omittedSymbols) + ? coverage.omittedSymbols.length + : 0; + const nonExportCount = Array.isArray(coverage.documentedNonExports) + ? coverage.documentedNonExports.length + : 0; + console.log( + `Coverage [${name}]: mode=${mode}; reason=${JSON.stringify(reason)}; ` + + `omitted-symbol-groups=${omittedCount}; documented-non-export-groups=${nonExportCount}`, + ); + } +} + +function flattenGroups( + pkgName: string, + kind: string, + groups: readonly SymbolOmissionGroup[], +): { symbols: Set; errors: string[] } { + const symbols = new Set(); + const errors: string[] = []; + for (const group of groups) { + const sorted = [...group.symbols].sort((a, b) => a.localeCompare(b)); + if (group.symbols.some((symbol, index) => symbol !== sorted[index])) { + errors.push(`Coverage Policy Error [${pkgName}]: ${kind} symbols must be sorted`); + } + for (const symbol of group.symbols) { + if (symbols.has(symbol)) { + errors.push( + `Coverage Policy Error [${pkgName}]: ${kind} repeats symbol '${symbol}'`, + ); + } + symbols.add(symbol); + } + } + return { symbols, errors }; +} + +export async function checkDrift(mapping: unknown): Promise { + printCoverageReport(mapping); + const validated = validateAuthoritativeMapping(mapping); + if (validated.errors.length > 0) { + for (const error of validated.errors) console.error(`Coverage Policy Error: ${error}`); + return 1; + } + let hasErrors = false; const root = Deno.cwd(); - for (const pkg of AUTHORITATIVE_MAPPING) { + for (const pkg of validated.mappings) { const denoJsonPath = join(root, pkg.packagePath, 'deno.json'); const docPath = join(root, pkg.docPath); @@ -416,32 +688,58 @@ async function checkDrift() { } // Run deno doc to collect all actually exported symbols from this package's entrypoints - if (pkg.checkSymbols) { + if (pkg.symbolCoverage.mode === 'complete') { const expectedSymbols = new Set(); - const excludedSymbolsSet = new Set(pkg.excludedSymbols ?? []); + const omitted = flattenGroups( + pkg.name, + 'omitted-symbol group', + pkg.symbolCoverage.omittedSymbols ?? [], + ); + const documentedNonExports = flattenGroups( + pkg.name, + 'documented-non-export group', + pkg.symbolCoverage.documentedNonExports ?? [], + ); + for (const error of [...omitted.errors, ...documentedNonExports.errors]) { + console.error(error); + hasErrors = true; + } + for (const symbol of omitted.symbols) { + if (documentedNonExports.symbols.has(symbol)) { + console.error( + `Coverage Policy Error [${pkg.name}]: symbol '${symbol}' is both omitted and documented as a non-export`, + ); + hasErrors = true; + } + } for (const [exportName, relativePath] of expectedExports.entries()) { - const fullEntrypointPath = join(pkg.packagePath, relativePath); + const fullEntrypointPath = join(root, pkg.packagePath, relativePath); try { const cmd = new Deno.Command('deno', { - args: ['doc', '--json', fullEntrypointPath], + args: ['doc', '--no-lock', '--json', fullEntrypointPath], }); - const { stdout, code } = await cmd.output(); + const { stdout, stderr, code } = await cmd.output(); if (code !== 0) { console.error( `Failed to run deno doc --json for ${exportName} at ${fullEntrypointPath}`, ); + console.error(new TextDecoder().decode(stderr)); hasErrors = true; continue; } const docJson = JSON.parse(new TextDecoder().decode(stdout)); const fileUrl = Object.keys(docJson.nodes)[0]; - if (fileUrl && docJson.nodes[fileUrl]?.symbols) { - for (const sym of docJson.nodes[fileUrl].symbols) { - if (sym.name && !excludedSymbolsSet.has(sym.name)) { - expectedSymbols.add(sym.name); - } - } + const symbols = fileUrl ? docJson.nodes[fileUrl]?.symbols : undefined; + if (!Array.isArray(symbols) || symbols.length === 0) { + console.error( + `Empty symbol selection from deno doc --json for ${exportName} at ${fullEntrypointPath}`, + ); + hasErrors = true; + continue; + } + for (const sym of symbols) { + if (sym.name) expectedSymbols.add(sym.name); } } catch (err) { console.error(`Error processing deno doc for ${exportName}:`, err); @@ -449,7 +747,41 @@ async function checkDrift() { } } - const symbolsErrors = checkSymbolsDrift(pkg.name, pkg.docPath, expectedSymbols, docSymbols); + for (const symbol of omitted.symbols) { + if (!expectedSymbols.has(symbol)) { + console.error( + `Coverage Policy Error [${pkg.name}]: omitted symbol '${symbol}' is not exported`, + ); + hasErrors = true; + } else if (docSymbols.has(symbol)) { + console.error( + `Coverage Policy Error [${pkg.name}]: omitted symbol '${symbol}' is documented and no longer omitted`, + ); + hasErrors = true; + } + } + for (const symbol of documentedNonExports.symbols) { + if (expectedSymbols.has(symbol)) { + console.error( + `Coverage Policy Error [${pkg.name}]: documented non-export '${symbol}' is now exported`, + ); + hasErrors = true; + } else if (!docSymbols.has(symbol)) { + console.error( + `Coverage Policy Error [${pkg.name}]: documented non-export '${symbol}' is absent from the reference`, + ); + hasErrors = true; + } + } + + const symbolsErrors = checkSymbolsDrift( + pkg.name, + pkg.docPath, + expectedSymbols, + docSymbols, + omitted.symbols, + documentedNonExports.symbols, + ); for (const err of symbolsErrors) { console.error(err); hasErrors = true; @@ -458,12 +790,12 @@ async function checkDrift() { } if (hasErrors) { - Deno.exit(1); - } else { - console.log('Exports & Symbols drift check: PASS'); + return 1; } + console.log('Exports & Symbols drift check: PASS'); + return 0; } if (import.meta.main) { - await checkDrift(); + Deno.exit(await checkDrift(AUTHORITATIVE_MAPPING)); } diff --git a/.llm/tools/docs/check-exports-drift_test.ts b/.llm/tools/docs/check-exports-drift_test.ts index ac98480843..77971a0404 100644 --- a/.llm/tools/docs/check-exports-drift_test.ts +++ b/.llm/tools/docs/check-exports-drift_test.ts @@ -1,7 +1,10 @@ import { assertEquals } from '@std/assert'; +import { join, relative } from '@std/path'; import { + checkDrift, checkExportsDrift, deriveExpectedExports, + type PackageMapping, parseDocContent, } from './check-exports-drift.ts'; @@ -62,3 +65,103 @@ Deno.test('drift checker negative fixture validation', () => { ); assertEquals(errorsDocumented.length, 0); }); + +Deno.test('symbol parsing is table-aware and normalizes display generics', () => { + const { docSymbols } = parseDocContent(` +| Symbol | Kind | +| --- | --- | +| \`DataGridColumn\` / \`Alpha\` | types | + +| Prop | Type | +| --- | --- | +| \`columns\` | array | + +| Field | Type | +| --- | --- | +| \`key\` | string | +`); + assertEquals([...docSymbols].sort(), ['Alpha', 'DataGridColumn']); +}); + +function fixtureMapping(symbolCoverage: unknown): unknown { + return [{ + name: 'fixture', + packagePath: 'unused', + docPath: 'unused', + packageName: '@netscript/fixture', + excludedExports: [], + symbolCoverage, + }]; +} + +Deno.test('drift checker refuses an empty or malformed coverage reason', async () => { + assertEquals( + await checkDrift(fixtureMapping({ mode: 'entrypoints-only', reason: ' ' })), + 1, + ); + assertEquals( + await checkDrift(fixtureMapping({ mode: 'entrypoints-only', reason: 42 })), + 1, + ); +}); + +Deno.test('drift checker refuses an unknown coverage mode', async () => { + const code = await checkDrift(fixtureMapping({ mode: 'unknown', reason: 'fixture policy' })); + assertEquals(code, 1); +}); + +async function withSymbolFixture( + documentedSymbols: readonly string[], + run: (mapping: readonly PackageMapping[]) => Promise, +): Promise { + const scratchRoot = join(Deno.cwd(), '.llm/tmp'); + await Deno.mkdir(scratchRoot, { recursive: true }); + const fixtureRoot = await Deno.makeTempDir({ dir: scratchRoot, prefix: 'exports-drift-test-' }); + const packageRoot = join(fixtureRoot, 'pkg'); + const docPath = join(fixtureRoot, 'reference.md'); + await Deno.mkdir(packageRoot); + try { + await Deno.writeTextFile( + join(packageRoot, 'deno.json'), + JSON.stringify({ exports: { '.': './mod.ts' } }), + ); + await Deno.writeTextFile( + join(packageRoot, 'mod.ts'), + '/** Fixture export. */\nexport const actualSymbol: string = "actual";\n', + ); + const symbolRows = documentedSymbols.map((symbol) => + `| \`${symbol}\` | fixture | Fixture symbol. |` + ).join('\n'); + await Deno.writeTextFile( + docPath, + `# Fixture\n\n## Exports\n\n| Export | Entrypoint | Purpose |\n| --- | --- | --- |\n| @netscript/fixture | ./mod.ts | Fixture entrypoint. |\n\n---\n\n## Symbols\n\n| Symbol | Kind | Description |\n| --- | --- | --- |\n${symbolRows}\n`, + ); + + const relativeRoot = relative(Deno.cwd(), fixtureRoot); + await run([{ + name: 'fixture', + packagePath: join(relativeRoot, 'pkg'), + docPath: join(relativeRoot, 'reference.md'), + packageName: '@netscript/fixture', + excludedExports: [], + symbolCoverage: { + mode: 'complete', + reason: 'Fixture requires complete symbol coverage.', + }, + }]); + } finally { + await Deno.remove(fixtureRoot, { recursive: true }); + } +} + +Deno.test('drift checker refuses an invented symbol through the injectable seam', async () => { + await withSymbolFixture(['inventedSymbol'], async (mapping) => { + assertEquals(await checkDrift(mapping), 1); + }); +}); + +Deno.test('drift checker refuses an omitted symbol through the injectable seam', async () => { + await withSymbolFixture([], async (mapping) => { + assertEquals(await checkDrift(mapping), 1); + }); +}); diff --git a/docs/site/reference/fresh-ui/index.md b/docs/site/reference/fresh-ui/index.md index 78a1ad6c68..171df0f6dd 100644 --- a/docs/site/reference/fresh-ui/index.md +++ b/docs/site/reference/fresh-ui/index.md @@ -1,41 +1,44 @@ --- layout: layouts/base.vto -title: "@netscript/fresh-ui" +title: '@netscript/fresh-ui' --- # `@netscript/fresh-ui` -Fresh UI registry seams and interactive foundations for NetScript. This page is written against -the package public surface reported by `deno doc`. For the full index of packages and -plugins return to the [reference overview](/reference/). +Fresh UI registry seams and interactive foundations for NetScript. This page is written against the +package public surface reported by `deno doc`. For the full index of packages and plugins return to +the [reference overview](/reference/). The root entrypoint (`@netscript/fresh-ui`) intentionally stays small: copy-based registry -components and islands remain on workspace-local deep paths so applications can own and evolve -them after copy. The root module exposes only the supported helper utilities that are safe to -consume as package runtime dependencies. Five sub-path exports carry the package runtime seams: +components and islands remain on workspace-local deep paths so applications can own and evolve them +after copy. The root module exposes only the supported helper utilities that are safe to consume as +package runtime dependencies. Five sub-path exports carry the package runtime seams: -- [`@netscript/fresh-ui/ai/render-ui`](#sub-path-exports) — safe, bounded generative-UI renderer for validated tool payloads. +- [`@netscript/fresh-ui/ai/render-ui`](#sub-path-exports) — safe, bounded generative-UI renderer for + validated tool payloads. - [`@netscript/fresh-ui/desktop`](#sub-path-exports) — browser-safe native desktop chrome helpers. -- [`@netscript/fresh-ui/interactive`](#sub-path-exports) — package-owned interactive namespaces for stateful, accessible primitives. +- [`@netscript/fresh-ui/interactive`](#sub-path-exports) — package-owned interactive namespaces for + stateful, accessible primitives. - [`@netscript/fresh-ui/primitives`](#sub-path-exports) — L0 platform-contract primitives. -- [`@netscript/fresh-ui/registry`](#sub-path-exports) — embedded copy-registry manifest and file content. +- [`@netscript/fresh-ui/registry`](#sub-path-exports) — embedded copy-registry manifest and file + content. ## Class-name helper -| Symbol | Signature | Description | -| --- | --- | --- | -| `cn` | `function cn(...inputs: ClassValue[]): string` | Combines clsx and tailwind-merge for optimal class merging. | +| Symbol | Signature | Description | +| ------ | ---------------------------------------------- | ----------------------------------------------------------- | +| `cn` | `function cn(...inputs: ClassValue[]): string` | Combines clsx and tailwind-merge for optimal class merging. | ## Icon primitive `Icon` is a first-class stroke-SVG icon primitive, re-exported at the package root alongside its supporting types from `@netscript/fresh-ui/primitives`. -| Symbol | Kind | Description | -| --- | --- | --- | -| `Icon` | component | Renders a named stroke-SVG icon (`IconName`) at a given `IconSize`, forwarding standard SVG attributes. | -| `ICON_PATHS` | const | The stroke-path lookup table backing every `IconName`. | -| `IconName` / `IconSize` / `IconProps` / `IconSvgAttributes` / `IconSvgAttributeValue` | type aliases / interface | Supporting types for the `Icon` primitive. | +| Symbol | Kind | Description | +| ------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------- | +| `Icon` | component | Renders a named stroke-SVG icon (`IconName`) at a given `IconSize`, forwarding standard SVG attributes. | +| `ICON_PATHS` | const | The stroke-path lookup table backing every `IconName`. | +| `IconName` / `IconSize` / `IconProps` / `IconSvgAttributes` / `IconSvgAttributeValue` | type aliases / interface | Supporting types for the `Icon` primitive. | ## DataGrid @@ -47,23 +50,23 @@ a `rows` contract, and supports plain, button, and Fresh client-navigation rows. ### DataGrid props -| Prop | Type | Description | -| --- | --- | --- | -| `columns` | `readonly DataGridColumn[]` | Ordered column definitions (required). | -| `rows` | `readonly DataGridRow[]` | Ordered row definitions (required). | -| `label` | `string` | Accessible label applied as `aria-label` on the grid region. | -| `class` | `string` | Additional class names appended to the `ns-data-grid` root. | -| `[attribute: string]` | `unknown` | Any further native attributes are forwarded to the grid root. | +| Prop | Type | Description | +| --------------------- | ------------------------------ | ------------------------------------------------------------- | +| `columns` | `readonly DataGridColumn[]` | Ordered column definitions (required). | +| `rows` | `readonly DataGridRow[]` | Ordered row definitions (required). | +| `label` | `string` | Accessible label applied as `aria-label` on the grid region. | +| `class` | `string` | Additional class names appended to the `ns-data-grid` root. | +| `[attribute: string]` | `unknown` | Any further native attributes are forwarded to the grid root. | ### `DataGridColumn` -| Field | Type | Description | -| --- | --- | --- | -| `key` | `string` | Property key used for fallback cell content and stable cell identity. | -| `header` | `string` | Visible column header text. | -| `width` | `string` | CSS grid track width, e.g. `2fr` or `minmax(0, 12rem)`. Defaults to `minmax(0, 1fr)`. | -| `cell` | `DataGridCellVariant` | Optional built-in cell treatment: `"strong"` (bold) or `"num"` (monospace, right-aligned). | -| `render` | `(row: T) => DataGridRenderable` | Optional per-column template receiving the row payload. | +| Field | Type | Description | +| -------- | -------------------------------- | ------------------------------------------------------------------------------------------ | +| `key` | `string` | Property key used for fallback cell content and stable cell identity. | +| `header` | `string` | Visible column header text. | +| `width` | `string` | CSS grid track width, e.g. `2fr` or `minmax(0, 12rem)`. Defaults to `minmax(0, 1fr)`. | +| `cell` | `DataGridCellVariant` | Optional built-in cell treatment: `"strong"` (bold) or `"num"` (monospace, right-aligned). | +| `render` | `(row: T) => DataGridRenderable` | Optional per-column template receiving the row payload. | ### `DataGridRow` @@ -71,25 +74,26 @@ Every row carries a stable `id`, a caller-owned `data: T` payload, and an option A row renders differently based on which navigation field is present — the three shapes are mutually exclusive (supply at most one of `onSelect` or `href`): -| Shape | Distinguishing field | Renders as | -| --- | --- | --- | -| Plain | neither `onSelect` nor `href` | a `role="row"` `
`. | -| Button | `onSelect: () => void` | a `role="row"` `