fix(docs/exports): gate reference drift and repair Fresh UI coverage

[rickylabs]

Summary

This closes #1296 with a fail-closed reference-drift policy and a current-main-safe publication cascade:

• fixes all four residual Contracts JSDoc example imports;
• makes Contracts and Fresh UI reference coverage explicit, including reason-bearing machine-readable omissions;
• adds a named docs:exports-drift task and Pages step while preserving the existing docs:accuracy enforcement chain;
• integrates main without rewriting evaluated history and regenerates the four owned publication outputs as the exact fix(sdk): isolate cache write failures and settle cache telemetry contracts #1665 + fix(docs/exports): gate reference drift and repair Fresh UI coverage #1666 union;
• repairs the two changed-source quality findings raised by the first ready run with guarded unknown parsing and discriminating tests.

The initial premise that CI enforcement was absent was corrected during planning. Qualifying non-draft CI already reaches the checker fail-closed through quality-docs-accuracy -> docs:accuracy -> check-accuracy-and-discoverability.ts -> check-exports-drift.ts; this PR adds direct discoverability, durable refusal tests, and the maintainer runbook.

Scope

Closes #1296

• Archetype 6 CLI/tooling with frontend + docs overlays; Contracts is A1, Fresh UI is A4.
• Current main 0ef48c2ec is merged by content commit 8c03d8629, whose parents are prior evaluator 0d4c82d6e and main 0ef48c2ec.
• Final implementation set: 14 paths inside the authorized 17-path ceiling; no eighteenth path.
• The quality repair changes only the checker, its focused tests, and append-only run evidence; it does not change the accepted generated publication union.
• The only generated conflict outputs are:
  • .llm/assets/agent-docs/prose.json.gz
  • .llm/assets/agent-docs/provenance.json
  • packages/cli/src/kernel/assets/agent-docs.generated.ts
  • packages/mcp/src/publish-assets.generated.ts
• No runtime, schema, export-map, deno.lock, docs/exports, Contracts public-barrel, or MCP export-corpus mutation.

Delivered slices

• PLAN-EVAL cycle 2 PASS — 45c249b9c
• S1 explicit coverage policy, Fresh UI repair, and all four Contracts JSDoc corrections — 678840603
• S2 named local/Pages drift-gate discoverability — 47ca22abe
• Discriminating refusal-test repair — 423867017
• Canonical four-output publication cascade — 46528ae4c
• Current-main history-preserving union refresh — 8c03d8629
• Exact-head refresh evidence — 021c7ffc6
• Integration-delta IMPL-EVAL PASS — 05ac90d00
• Changed-source quality repair — e357938df
• Quality-repair delta IMPL-EVAL cycle 5 PASS — evaluator commit 92988da30

Validation

The 12 selected integration receipts bind gitHead == actualGitHead == 8c03d8629 and pass:

• check: 2,925 files, 25 batches, zero findings.
• test: 4,211 passed, 0 failed, 19 ignored (4,230 total).
• quality-job, arch-check, docs-source-format, docs-source-format-test, docs-tagline, docs-accuracy, agent-docs-prose, assets-barrel, publish-assets, and publish-dry-run: PASS.
• The canonical generator cascade ran twice at the integration head and left an empty tree after every step; no fifth output appeared.
• Direct corpus comparison proves the merged asset contains both fix(sdk): isolate cache write failures and settle cache telemetry contracts #1665's query-bridge contribution and fix(docs/exports): gate reference drift and repair Fresh UI coverage #1666's Fresh UI contribution.
• Scope is 14-of-17 and deno.lock remains blob a1522e6e… across base, main, pre-merge evaluator, content, evidence, repair, and evaluator heads.

Cycle 5 independently re-ran the repaired-head gates at e357938df:

• changed-files code-quality mode selected all nine changed source paths, including the checker and test, with zero findings and raw exit 0;
• checker tests: 12 passed / 0 failed; all six targeted mutations were killed by their named tests;
• docs:exports-drift: PASS with complete Contracts and Fresh UI coverage;
• root check: 2,925 files, 25 batches, zero failed;
• root test: 4,217 passed, 0 failed, 19 ignored (4,236 total);
• the four generated cascade outputs and deno.lock are byte-identical between 8c03d8629 and e357938df.

Honest retained reds and non-applicable gates:

• The original scanner-contaminated root-test receipt remains RED at 4,202/1/19; its unchanged-head replacement is PASS at 4,203/0/19.
• check:mcp-export-corpus is the same pre-existing raw red at main and head and was not regenerated, waived, or reclassified.
• Contracts doc-lint remains 9 findings; Fresh UI remains 123, identical at main and head.
• fresh-browser is N/A/waived and NOT_RUN; runtime and real-publish gates are not applicable to this leaf.

Evaluation and readiness

• Fresh internals Tier-A over the integration refresh: PASS at topic checkpoint 6658ad9c0.
• Integration-delta IMPL-EVAL cycle 4: PASS at 05ac90d00; verdict comment.
• Changed-source quality repair: e357938df; repair evidence.
• Fresh separate Claude Fable 5/medium Remote Control IMPL-EVAL cycle 5: PASS, evaluator commit 92988da30; verdict comment, Remote Control session.
• Final branch head is 92988da30a4468f5ea77ea4e5a3e243469f92e52; current main remains ancestor 0ef48c2ec661a7e6d55ec2faf5def6ae7dd2e6eb.
• impl-eval:skip remains attributed so the ready transition does not duplicate the completed native evaluator.
• Merge is conditional on the exact-head GitHub CI suite, including changed-source code quality, completing green.

Definition of done

• All residual Contracts examples import from exporting subpaths.
• Contracts reference inventory advertises no non-exports.
• Fresh UI reference matches its published and curated surfaces.
• Intentional omissions are explicit, reason-bearing, machine-readable, and reported.
• Refusal tests distinguish malformed policy, unknown mode, invented symbols, and omitted symbols.
• Maintainer regeneration procedure is documented.
• Drift enforcement is fail-closed and directly named locally and in Pages.
• Current-main generated publication union is canonical, convergent, and independently evaluated.
• The changed-source quality repair removes both findings without suppression and has a fresh cycle-5 IMPL-EVAL PASS.

[rickylabs]

[PHASE: RESEARCH]

Re-baselined #1296 against baf1cdf67; the carried-in wiring conclusion was materially incomplete.

Findings

1. The drift checker is already indirectly wired. The direct deno.json/workflow search has zero hits (raw exit 1), but check-accuracy-and-discoverability.ts runs the checker, propagates its child exit, and is called by both docs:accuracy and docs:maintenance. Baseline direct drift and aggregate accuracy commands both returned raw exit 0.
2. docs/exports is stale contract scope. It is absent on baseline and reachable history, with no producer or consumer. Creating it would duplicate the live deno.json.exports + deno doc authority.
3. The briefed Contracts root row is baseline-earned. baseContract, BaseContractRoute, BaseContractOutputRoute, and OffsetPaginationQuerySchema resolve from the root and their named examples import correctly. No leaf credit claimed.
4. A different Contracts JSDoc remains wrong. paginated-query.ts imports paginatedQuery from the root; the symbol exists only on @netscript/contracts/query.
5. Fresh UI's six entrypoints are listed, but symbol proof is disabled. The six deno doc --json surfaces contain 168 unique symbols. Forcing the current parser on yields 162 mixed real/false errors because prop tables and generic display names are misclassified.
6. JSR evidence is explicit. Contracts has a real shipped-JSDoc publish delta and no internal NetScript dependency pins. Fresh UI pins both SDK subpaths exactly to 0.0.6. Package audits exited 0; existing full-surface doc-lint remains red (Contracts 9, Fresh UI 123) and is not mislabeled green.
7. MySQL remains prisma-adapter-mysql: adapter class is unexported and has no connection-error hook — the honest example needs both #1293's open status:impl scope and is neither touched nor blocking.

Research artifact: .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/research.md

Next

• Coordinator reviews the pushed planning head 9d0b4bf128ba52fcd52091ba50590661d09470c1; no implementation begins in this author session.

[rickylabs]

[PHASE: PLAN]

Locked a three-slice implementation contract; implementation remains prohibited pending coordinator gates.

Locked decisions

1. Keep deno.json.exports + per-entrypoint deno doc --json as the sole authority; do not create docs/exports.
2. Replace silent checkSymbols: false with a discriminated, reason-bearing complete versus entrypoints-only policy. Invalid/empty reasons refuse rather than pass.
3. Repair the Markdown parser before enforcement: only Symbol-headed tables count, display generics normalize, and explicitly labeled copy-source symbols require reason-bearing classification.
4. Put Fresh UI in complete mode, repair its missing desktop/ActionMenu/Combobox/registry/public-contract coverage, and enumerate any intentional low-level omissions machine-readably.
5. Correct only the published paginated-query.ts JSDoc to @netscript/contracts/query; preserve the already-correct Contracts root files.
6. Add a least-permission docs:exports-drift task, retain docs:accuracy/docs:maintenance as the local aggregate, and add the named task to the existing Pages build job.
7. Use only the frozen nine implementation paths. The plan deliberately leaves docs/exports, contract-primitives.ts, and src/public/mod.ts untouched and names every other non-scope path.

Gates

• Contracted: check, test, publish-dry-run, quality-job, arch-check, docs-source-format, docs-accuracy, plus focused drift/JSR evidence and exact path/lock review.
• fresh-browser: NOT FIRED. The plan judges it not genuinely required because no route/component/CSS/interaction changes, and asks the coordinator to record waiver/N/A. If required for rendered-reference assurance, only an authorized coordinator lane may grant/run it.
• No Aspire, Docker, browser, e2e:cli, scaffold runtime, publish, or release operation.

PLAN-EVAL

REQUIRED, not assumed. The machine-readable omission contract, parser boundary, and coverage-versus-compliance semantics are decision-heavy and would force rework if deferred. The coordinator owns Tier-A and a fresh separate-session opposite-family PLAN-EVAL on exact head 9d0b4bf128ba52fcd52091ba50590661d09470c1. This author did not create a verdict or dispatch an evaluator.

Plan artifact: .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan.md

Next

• Coordinator: Tier-A review, decide fresh-browser classification, and grant/dispatch PLAN-EVAL.
• Author: stopped; no implementation until recorded PASS.

[rickylabs]

[PHASE: PLAN] [STATE: TIER-A_REVIEWED] — topic-internals-0.0.7

Tier-A verdict: PASS on plan quality, with one required rescope escalation to the coordinator.
No implementation is authorized yet; PLAN-EVAL remains the coordinator's grant.

Verified at head 9d0b4bf128ba52fcd52091ba50590661d09470c1

Check	Result
Three-way head identity (local / remote / PR)	match
Plan-only boundary	held — git diff --name-status baf1cdf67 9d0b4bf12 is three added run artifacts; the filtered list outside .llm/runs/ is empty
PR state	draft, base main, milestone 0.0.7, exactly one status: label
Closing keyword	Closes #1296 present; #1293 referenced without a keyword

Independently confirmed — Step-0 is materially corrected

Step-0 recorded acceptance row 1 as already satisfied after checking four symbols in
contract-primitives.ts. This plan found a fifth, in a different file. I verified it two ways
rather than accepting the claim:

• paginatedQuery appears nowhere in packages/contracts/src/public/mod.ts
• deno doc --filter paginatedQuery packages/contracts/mod.ts → Node paginatedQuery was not found!
• query.ts:23 re-exports it, and its own JSDoc correctly cites @netscript/contracts/query

So paginated-query.ts:6 ships an example a reader cannot resolve. Row 1 was partly satisfied.

Plan discipline worth recording

Nine frozen paths narrowed to six edited with three explicit do-not-touch entries; docs/exports
declared a stale frozen entry and deliberately not created rather than invented to satisfy the
contract; D5 repairs the symbol-table parser before enabling enforcement ("exclusions must never
compensate for parser defects"); D11 forbids tuning the checker to baseline green. fresh-browser
is classified NOT FIRED with a reasoned waiver request rather than quietly skipped.

Required escalation — bounded tenth path requested

S1 rewrites check-exports-drift.ts substantially: a discriminated symbolCoverage policy (D2),
two modes with mandatory nonempty reasons (D3), documented-non-export groups (D4), and a new table
parser (D5) — all fail-closed. But .llm/tools/docs/check-exports-drift_test.ts is not among
the nine frozen surfaces, so the new refusal paths would be proven only by one-off probes
recorded as diagnostic evidence (S1; validation row 1). Those probes do not persist and cannot
fail a future CI run. The test file currently holds exactly one test, predating every new
semantic.

Shipping fail-closed policy whose failure modes nobody re-verifies is the same defect #1296 exists
to remove. Requested: one bounded tenth path, .llm/tools/docs/check-exports-drift_test.ts,
test-only. The author raised and deferred this correctly — the gap is the contract's, not theirs.

Coordinator decisions outstanding

1. Tenth-path grant (above) — test-only.
2. fresh-browser waiver / n/a classification for this surface.
3. PLAN-EVAL cycle 1 grant and evaluator lease.

PR stays draft at status:plan. No merge, publish, ready flip, relabel, or central-state
mutation performed.

[rickylabs]

[PHASE: TIER-A] Scope amendment SA-1 — PASS (one recorded caveat)

Supervisor substantive review by topic-internals-0.0.7, run fresh over the amended head. This
gates the amendment only; it is not a plan evaluation and does not substitute for PLAN-EVAL.

Field	Value
Amended head	a3f6b87b599e778db950daf6ccaecd847c088d19
Prior head	9d0b4bf128ba52fcd52091ba50590661d09470c1
Base	baf1cdf67a4e931af17b4772ddf6101f36152184
Amendment	SA-1 — scope-amendment.md, plus inline AMENDED (SA-1) annotations in plan.md

What SA-1 changes

1. Tenth implementation path authorized, test-only: .llm/tools/docs/check-exports-drift_test.ts.
2. fresh-browser classified N/A / waived; NOT_RUN evidence preserved, no runtime lease.
3. PLAN-EVAL cycle 1 granted over the amended immutable head, separate session, artifact-only.
4. fix(docs/exports): gate reference drift and repair Fresh UI coverage #1666 sequences before test(docs): nothing compiles JSDoc @example blocks, so a published JSR reference can import a module that does not exist #1533.

No locked decision (D1-D11) is modified. The nine frozen paths and their per-path actions are
unchanged, including docs/exports (do not create), contract-primitives.ts and src/public/mod.ts
(do not edit).

Checks executed

#	Check	Result
T1	Amendment commit touches only slice run artifacts	git show --name-status a3f6b87b5 → M plan.md, A scope-amendment.md. No implementation path in the diff.
T2	plan.md carries no unannotated prohibition on the authorized path	5 remaining references to check-exports-drift_test.ts; each is either the new authorization row, an AMENDED (SA-1) annotation, or the struck-through original. The author's original text is preserved, not deleted.
T3	The authorized path exists and is a real test file	.llm/tools/docs/check-exports-drift_test.ts, 2059 bytes, 1 Deno.test.
T4	The existing fixture passes unchanged at the amended head	deno test --no-lock --allow-all .llm/tools/docs/check-exports-drift_test.ts, unpiped → raw exit 0, 1 passed | 0 failed. SA-1 adds cases; it does not license rewriting what is already there.
T5	Waiver surface — any route/component/island/CSS in scope?	docs/site/reference/fresh-ui/ contains only index.md. No .tsx, route, or island in the frozen surface. The waiver argument holds on the surface as frozen.
T6	A4 sequencing premise still live	packages/contracts/src/application/paginated-query.ts:6 still reads import { paginatedQuery } from '@netscript/contracts'; at the amended head. #1533's gate would go red here.
T7	Central contract re-read	leaf-contracts.json entry reference-export-drift-gate: 9 fileSurfaces, no test path, fresh-browser present in provingGates. The divergence from SA-1 is real and recorded.

Caveat recorded, not waived away

docs/site/reference/fresh-ui/index.md carries layout: layouts/base.vto — it is rendered by
the docs site. The fresh-browser waiver is therefore not free: it trades away rendered-page
assurance for the one page this leaf substantially rewrites. What remains covering it is
docs-source-format, the links check, and the docs build. That is a deliberate accepted risk under
the coordinator's classification, not an absence of risk, and NOT_RUN must stay reported as
NOT_RUN.

Central-state reconciliation is owed upstream

leaf-contracts.json is coordinator-owned; this lane does not edit it. SA-1 is the leaf-local record
of the tenth path and lives in the immutable head the evaluator reads. Reconciling central state
against SA-1 remains the coordinator's.

Next

PLAN-EVAL cycle 1 dispatches now over a3f6b87b5 — fresh separate session, native Fable 5 / medium,
Remote Control, artifact-only. The PR stays draft. No merge, ready flip, relabel, issue closure,
or milestone change from this lane.

[rickylabs]

[PHASE: PLAN] [STATE: PLAN-EVAL_DISPATCHED] — topic-internals-0.0.7

Independent Tier-A on the SA-1 amendment: PASS, with one caveat recorded below.
PLAN-EVAL cycle 1 is live over the immutable amended head.

Verified at a3f6b87b599e778db950daf6ccaecd847c088d19

Check	Result
Head identity (local / remote / PR)	match, draft
Amendment 9d0b4bf12 → a3f6b87b5	artifacts-only — plan.md modified, scope-amendment.md added
Product mutation vs baseline baf1cdf67	none — filtered diff outside .llm/runs/ is empty

Tenth path — escalation properly resolved

The refusal coverage is now persistent, not ephemeral. .llm/tools/docs/check-exports-drift_test.ts
is admitted as edit — test assertions only, and S1 plus validation row 1 require the four refusal
cases — empty/malformed reason, unknown coverage mode, invented symbol, omitted symbol — to be
committed test cases, so they "can fail a future CI run rather than only this author's terminal."
The superseded do-not-touch entry is struck through and an eleventh-path rescope guard replaces
the old tenth-path guard.

fresh-browser is classified N/A / waived, NOT_RUN preserved, no runtime lease requested.

Caveat — required correction during implementation

The surface table now holds ten rows, but three references still say nine:

• plan.md:36 — "the nine frozen implementation paths"
• plan.md:233 — risk guard "outside the nine paths"
• plan.md:145 — the S3 validation gate, "exact nine-path diff audit"

The third is a gate definition. A diff audit hard-coded to nine against a ten-path contract either
fails spuriously or gets reconciled by hand — the reconcile-until-green defect this leaf exists to
remove. Not a blocker: the operative contract, guard, and per-path justifications are all correct at
ten. It must be corrected before the S3 audit runs.

(plan.md:203's "nine private-type-ref reds" is a doc:lint count, correctly left alone.)

PLAN-EVAL cycle 1 — evaluator lease

Field	Value
Session	68c31fcc-f93b-496f-8c0b-10e6736dded7
Bridge	cse_01DcmCJnvESF3a4nVDvUR8u8, bridgeOutboundOnly: false
Remote Control	https://claude.ai/code/session_01DcmCJnvESF3a4nVDvUR8u8
Route (observed = requested)	native claude-fable-5 / effort medium / --remote-control
cwd	/home/codex/repos/netscript-007-reference-export
Evaluated head	a3f6b87b599e778db950daf6ccaecd847c088d19 (immutable)
Scope	artifact-only; no implementation

Route was read from the job registry rather than argv, providerEnv is empty (native Anthropic, not
a gateway), and token movement confirms real inference rather than a stalled attach.

Exactly one evaluator is live for this PR — verified by sweeping every job in working/blocked
state before acting, since cycle 1 had already been dispatched by a concurrent instance of this
supervisor session two minutes before the coordinator's order arrived. A second launch would have
double-dispatched the singleton evaluator slot.

PR stays draft at status:plan. No merge, publish, ready flip, relabel, or central-state
mutation. Implementation resumes on the preserved Sol/medium author only on PASS.

[rickylabs]

[PHASE: PLAN-EVAL] cycle 1 of 2 — FAIL_PLAN

Field	Value
Evaluated head (immutable)	a3f6b87b599e778db950daf6ccaecd847c088d19
Base	baf1cdf67a4e931af17b4772ddf6101f36152184
Route	native Claude Fable 5 / medium, fresh separate session (68c31fcc-f93b-496f-8c0b-10e6736dded7), artifact-only
Artifact	.llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/plan-eval.md (commit 5d229e0f3)

Blocking finding B1

Acceptance row 1 of #1296 is not baseline-earned except for paginated-query.ts:6. Enumerating every from '@netscript/contracts…' line in shipped Contracts sources and checking each symbol with deno doc --filter finds three more root imports of symbols the root does not export, all outside the frozen surface and all in the publish set:

• packages/contracts/src/application/transform-helpers.ts:6 — createTransformer (root EXIT=1, /transform EXIT=0)
• packages/contracts/schemas/filters.ts:6 — FilterConditionSchema, buildPrismaWhere (root EXIT=1, /query EXIT=0)
• packages/contracts/schemas/pagination.ts:6 — PaginationInputSchema, createPaginatedOutput (root EXIT=1, /query EXIT=0)

So research.md F3/F4, plan.md D8 and the deferrals section misstate row 1; Closes #1296 would close an issue with row 1 unmet in three shipped files; and SA-1 A4's #1533 sequencing rationale applies to four files, not one. Required fix: correct research/plan with the full inventory, then resolve — coordinator decision — either (a) a JSDoc-only scope amendment for the three files, or (b) keep the surface, record row 1 as unmet for them, and re-decide the closing keyword. Not remediated by the evaluator.

Re-derived and holding

Checker PASS raw exit 0; direct task/workflow search exit 1 but indirect fail-closed edge in check-accuracy-and-discoverability.ts:292-301 via docs:accuracy (raw exit 0) — no workflow runs it; paginatedQuery absent from root/present on /query; Fresh UI 28/11/35/82/16/7 = 168 union; forced symbol check 168/78/162 (126 OMITS + 36 INVENTS) reproduced exactly; Symbol-header boundary safe for Config/Contracts/Telemetry; docs/exports absent in tree and history; existing test 1 passed; contract shows 9 surfaces + fresh-browser. fresh-browser = packages/fresh/tests/form-navigation_browser.ts, untouched by this surface — waiver correct, NOT_RUN.

Non-blocking N1–N5 (S1 wording vs D11, per-package coverage report in checker output, test seam for refusal cases, Pages step cwd/guard, docs:accuracy child call) are in the artifact.

No merge, relabel, ready flip, issue/milestone change, or central-state mutation. Cycle 1 of 2; no re-run by this session.

[rickylabs]

[PHASE: TIER-A] PLAN-EVAL cycle 1 verdict review — B1 CONFIRMED, FAIL_PLAN stands

Supervisor review of the evaluator's verdict by topic-internals-0.0.7. I re-derived the blocking
finding independently rather than relaying it.

Field	Value
Evaluated head	a3f6b87b599e778db950daf6ccaecd847c088d19
Evaluator head	5d229e0f399fdafa4e9b8194d0ce8e57c158e5e2 (adds plan-eval.md only)
Cycle	1 of 2 — spent
Verdict	FAIL_PLAN, one blocking finding (B1)

Evaluator conduct

Artifact-only as briefed: git show --name-status 5d229e0f3 is a single A plan-eval.md. PR stays
draft at status:plan with no relabel. fresh-browser left NOT_RUN. No runtime lease taken.
Head asserted before evaluating.

B1 re-derived independently — confirmed

Root-vs-subpath resolution, deno doc --no-lock --filter <symbol> packages/contracts/mod.ts, raw
exit read unpiped (1 = Node … was not found!):

createTransformer      root_exit=1     schemas/../application/transform-helpers.ts:6
FilterConditionSchema  root_exit=1     schemas/filters.ts:6
buildPrismaWhere       root_exit=1     schemas/filters.ts:6
PaginationInputSchema  root_exit=1     schemas/pagination.ts:6
createPaginatedOutput  root_exit=1     schemas/pagination.ts:6
paginatedQuery         root_exit=1     src/application/paginated-query.ts:6   (already in plan)
baseContract           root_exit=0     src/application/contract-primitives.ts (correct, as claimed)

All four defective files are in the publish set — packages/contracts/deno.json publish.include
carries src/**/*.ts and schemas/**/*.ts. They ship JSDoc a reader cannot copy.

One detail beyond the evaluator's finding: schemas/pagination.ts:8 also uses baseContract in
the example body without importing it at all. Correcting the import specifier alone would leave that
example still uncopyable. Whoever fixes these should read each example whole, not just its first
line.

Why this is a plan failure and not an implementation detail

research.md F3/F4, plan.md D8, and the deferrals section all record acceptance row 1 as
baseline-satisfied except for one file. That is false in three more shipped files, and those files
sit outside the frozen surface. plan.md also locks Closes #1296, so merging as planned would
auto-close an issue whose row 1 is still unmet. Neither fixing them nor declining to is the author's
call.

Escalated, not decided here

This lane has no scope authority. The choice is the coordinator's:

• (a) a JSDoc-only scope amendment covering transform-helpers.ts, schemas/filters.ts,
  and schemas/pagination.ts — @example import lines only, same publish-delta treatment as
  paginated-query.ts — added to S1 and to validation row 11's path audit; or
• (b) keep the frozen surface, record row 1 as unmet for those three files, and decide
  whether Closes #1296 may stand. It should not, absent (a) or a follow-up issue referenced
  without a closing keyword.

Either way, SA-1 A4's sequencing rationale needs correcting: #1533's example-compile gate would go
red on four files, not one, so landing #1666 first does not by itself prevent that red.

Cycle 1 of 2 is spent. Cycle 2 is not being launched — the required fix is a scope decision, and
re-running the evaluator against an unchanged scope would only reproduce B1. The leaf is parked at
5d229e0f3, draft, pending that decision.

[rickylabs]

[PHASE: PLAN-EVAL] [STATE: FAIL_PLAN] — cycle 1 of 2

Verdict: FAIL_PLAN at evaluator commit 5d229e0f399fdafa4e9b8194d0ce8e57c158e5e2, over
immutable evaluated head a3f6b87b599e778db950daf6ccaecd847c088d19.

Per the coordinator's order this is stop and attribute. No implementation resumed, no cycle 2
launched. Evaluator session 68c31fcc-f93b-496f-8c0b-10e6736dded7
(cse_01DcmCJnvESF3a4nVDvUR8u8, native claude-fable-5 / medium / Remote Control) confirmed
terminal — tokens stable at 32,287 across three samples — then released. Its boundary held: the
commit adds only plan-eval.md, and the diff versus baseline outside .llm/runs/ is empty.

B1 — blocking, and I re-verified it independently

Three more shipped Contracts JSDoc examples import symbols the root does not export, beyond the
paginated-query.ts:6 this plan covers:

File	Symbols	Root	Correct subpath
src/application/transform-helpers.ts:6	createTransformer	EXIT=1	transform.ts (EXIT=0)
schemas/filters.ts:6	FilterConditionSchema, buildPrismaWhere	absent	/query
schemas/pagination.ts:6	PaginationInputSchema, createPaginatedOutput	absent	/query

All three are in the publish set and all three sit outside the frozen ten paths, while plan.md
locks Closes #1296. Merging as planned would auto-close an issue whose row 1 is unmet in three
shipped files. That needs a coordinator decision: a JSDoc-only rescope for the three files, or keep
the surface and drop the closing keyword in favour of a follow-up reference.

It also extends the #1533 sequencing note — that gate would go red on four files, not one.

Correction — my A1 was wrong, and it propagated

I briefed this leaf that .llm/tools/docs/check-exports-drift.ts was "wired to nothing" and
"guards nothing". That is false, and the error is mine: I grepped only deno.json and
.github/workflows/, but the wiring is a Deno.Command spawn in a TypeScript file —
check-accuracy-and-discoverability.ts:291-301 runs the checker and throws on a nonzero child
code.

The evaluator's inverse claim — "no workflow runs docs:accuracy/docs:maintenance/docs-accuracy" —
is also wrong. The enforced chain exists today:

ci.yml:366  --gate docs-accuracy   (quality job, ci.yml:282, gated on draft == false)
  -> catalog.ts:59  docs-accuracy -> deno task docs:accuracy
    -> check-accuracy-and-discoverability.ts:291-301  -> spawns check-exports-drift.ts, fail-closed

Net truth: the drift gate is genuinely enforced on non-draft PRs and pushes. What is missing is
discoverability, not enforcement — no named docs:exports-drift task, no explicitly named
workflow step (it runs only as an unnamed child), no maintainer runbook. Row 5's remediation stays
valid on those grounds; the premise as I stated it does not, and research/plan text inherited from
my brief needs correcting alongside B1.

Three parties asserted a wiring state from a too-narrow grep. Only reading the spawning source
settled it.

PR stays draft at status:plan. No merge, publish, ready flip, relabel, or central-state
mutation.

[rickylabs]

Correction to the record: the drift checker is enforced in CI today

This corrects two claims — one of mine, one in plan-eval.md. Both were produced by grepping
for a name in config, and both missed a gate that reaches its command through an id.

The verified chain

.github/workflows/ci.yml  "Docs accuracy check"
  → deno run … .llm/tools/gates/run-gate.ts --gate docs-accuracy --id quality-docs-accuracy
    → .llm/tools/gates/catalog.ts:59   'docs-accuracy': ['deno', 'task', 'docs:accuracy']
      → deno.json  docs:accuracy  → .llm/tools/docs/check-accuracy-and-discoverability.ts
        → :291-301  new Deno.Command('deno', {args:['run','--allow-all',
                       '.llm/tools/docs/check-exports-drift.ts']})
          → :297-301  if (driftCode !== 0) throw new Error(
                        'Documentation exports/symbols drift check failed')

It is fail-closed: a nonzero child exit throws, docs:accuracy fails, the gate receipt fails,
the CI step fails.

What each of us got wrong

• My dispatch brief, A1 — "the tool exists, works, and guards nothing — no task, no workflow, not
  in docs:maintenance." Wrong on the last two clauses. I grepped deno.json and
  .github/workflows/ for check-exports-drift|exports-drift and never looked in the docs tooling
  directory, where the spawn actually lives.
• plan-eval.md, verified-claims row A1 — "No workflow runs docs:accuracy/docs:maintenance/
  docs-accuracy (grep … .github/workflows/ → EXIT=1)." Also wrong. The workflow names the
  gate id docs-accuracy, not the task, so a grep for the task name returns nothing while the
  gate runs on every qualifying CI job. The EXIT=1 was real; the conclusion drawn from it was not.

This lane has now hit gate-catalog indirection twice — it is the same shape as
lint: ['deno','task','lint']. A grep of workflows is not evidence about what CI enforces; the
catalog is the resolution step, and it has to be followed.

What it changes for #1296 and this plan

Acceptance row 4 is not an enforcement gap. Enforcement exists and is fail-closed. What is genuinely
missing is discoverability and the maintainer path: a named docs:exports-drift task, an
explicit Pages step, and the regeneration runbook. That is still worth doing, and D9 still describes
roughly the right work — but research.md F1, S2's "proves" bullet ("direct search now finds
explicit task/workflow wiring"), and any PR narrative must say improves discoverability of an
already-enforced gate, not wires an unwired gate. Claiming the latter would be this leaf
taking credit for coverage that already existed — which is precisely the defect class it was opened
to remove.

Blocking finding B1 is unaffected and still stands on its own evidence.

Verified independently at cb91b225d: ci.yml "Docs accuracy check" step, catalog.ts:59,
check-accuracy-and-discoverability.ts:291-301.

[rickylabs]

[PHASE: IMPL] — bounded post-eval base refresh

Current main 0ef48c2ec is integrated without rewriting evaluated history. Content merge 8c03d8629 has parents 0d4c82d6e and 0ef48c2ec; run-artifact head is 021c7ffc6.

Generated conflict resolution

• Preflight and the real merge found exactly the four generated publication conflicts briefed by the coordinator. The merge combined-diff/remerge-diff contains those four paths and no fifth output.
• Resolved only through the canonical order: gen:agent-docs-prose → gen:publish-assets → gen:assets-barrel. No generated payload was hand-edited; gen:mcp-export-corpus was not run.
• The first corpus run honestly returned raw 1 because conflict-marked provenance is invalid JSON. First-parent provenance was used only as a temporary metadata seed; the canonical generator overwrote the final corpus/provenance from merged inputs and returned raw 0. The other two owners returned raw 0.
• Two full post-commit cascade cycles returned raw 0 ×6 and left git diff --quiet green with empty status after each.

Positive union proof

Direct gzip decompression found both contributions in one corpus:

• fix(sdk): isolate cache write failures and settle cache telemetry contracts #1665: pages/web-layer/query-bridge/index.md and its new duplicate-@netscript/sdk-module guidance.
• fix(docs/exports): gate reference drift and repair Fresh UI coverage #1666: pages/reference/fresh-ui/index.md and its exact reason-bearing omission-group maintenance rule.

Corpus: 181 files, 4,770,349 uncompressed bytes, 1,368,351 compressed bytes, canonical SHA-256 c1d095a62e72555356d346d78848bff144ce9773c38eb9cd95f2d406b28174b3.

Exact-content-head receipts

All 12 selected receipts under receipts/base-refresh/ are PASS/raw 0 and bind gitHead == actualGitHead == 8c03d8629:

• check: 2,925 files / 25 batches / zero findings.
• test: 4,211 passed / 0 failed / 19 ignored, 4,230 total.
• quality-job, arch-check, docs-source-format, docs-source-format-test, docs-tagline, docs-accuracy, agent-docs-prose, assets-barrel, publish-assets, and publish-dry-run: PASS/raw 0.
• publish-dry-run remains static packaging evidence only, not real-publish proof.

Focused drift returned raw 0. A first focused checker command omitted required write permission and returned raw 1 before four fixtures ran; it is preserved as an invocation error, not called a product result. The corrected command returned raw 0, 6/0; the exact-head root test independently covers it and passed.

Scope and preserved evidence

• Seventeen-path classifier: raw 0; 14 changed implementation paths, all authorized, zero unexpected. No fifth generated output.
• deno.lock is byte-identical across pre-merge evaluator head, current main, content head, and working tree: blob a1522e6e….
• 46528ae4c, b67414f4f, 0d4c82d6e, and current main are all ancestors. Prior SA4 receipts/reds, audits, PLAN-EVAL, and IMPL-EVAL artifacts are byte-unchanged and append-only.
• The known MCP export-corpus baseline red was not rerun, generated, waived, or reclassified.

Full evidence: .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/base-refresh-evidence.md.

PR remains draft at status:impl. fresh-browser and close-gate remain NOT_RUN; runtime and real publication actions remain NOT FIRED. Stop for fresh internals Tier-A and fresh delta evaluation; readiness, labels, issue boxes, draft state, and merge remain coordinator-owned.

[rickylabs]

[PHASE: IMPL-EVAL] — cycle 4, post-integration delta

Verdict: PASS

Field	Value
Evaluated content head	8c03d862931b64573df9a4bac76ebf266e0ec175 (union merge: ^1 0d4c82d6e, ^2 main 0ef48c2ec)
Evaluated evidence head	021c7ffc62cea5b0f6728ddb8ee377393a647f44
Evaluator commit	05ac90d00706d4bd9f3d93a59ab58bcdbfea5909 — .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/impl-eval.md (cycle 3 preserved as impl-eval-cycle-3.md)
Evaluator	Claude Fable 5, fresh separate session, opposite-family to Codex author thread 01a005d2-7c9d-7dd1-b6fc-531b72dc14e4; Remote Control claude.ai/code/session_01RQ7Eb4N4NaQEuAA6zPtpxV (bg job be3774eb)

Re-derived (not re-read): local/remote/PR head agree; merge-tree 0d4c82d6e 0ef48c2ec = exactly the four generated outputs, zero source conflicts; the merged corpus is the exact three-way union (per-member equality to the changed side; llms-full.txt line-identical to git merge-file, both #1665 and Fresh UI content present, zero foreign lines); stamp retention is gated on gunzipped-payload byte equality, so sourceCommit 0d4c82d6e hides no stale corpus; full three-generator cascade run twice at 8c03d8629 with an empty tree after every step, freshness checks 0/0/0, check:mcp-export-corpus raw 1 at main and head (baseline, unwaived); 14 product paths vs main within 17, no eighteenth, deno.lock blob identical across base/main/leaf/head; 12 base-refresh receipts bound to 8c03d8629, evidence-set SUFFICIENT; sa4/s3/fix1 receipts, preserved red test.json (4202/1/19), and prior verdicts unamended; quarantine SHA-256 d0251bc2…eab2 intact, scanner and hook unweakened; MCP mirror delta is sourceCommit only (Fresh UI not in the 12-doc selection); contracts 9 / fresh-ui 123 doc-lint reds identical at main and head; Closes #1296 earned, boxes untouched; fresh-browser and close-gate remain NOT_RUN.

Non-blocking observation: audit/sa4/ JSR audits were not recut at 8c03d8629; acceptable since no package config/export map changed 0d4c82d6e→8c03d8629 and publish-dry-run is head-bound.

No product, receipt, label, issue, draft-state, runtime, or close-gate action taken.

[rickylabs]

[PHASE: IMPL] — changed-source quality repair

Focused repair pushed at e357938df. PR state/body/labels were not changed.

Fixed findings

• Former line 356 explicit-any (exportsObj: any) is now the untrusted exportsObj: unknown boundary at line 364, narrowed before enumeration.
• Former line 372 unsafe-cast ((value as any).default) is now the cast-free resolveDenoExportPath path at lines 384 and 399-401, backed by the DenoExportTarget string/object union and type guards.
• No allowance, suppression, lint-ignore, unsafe cast, or scanner change was added.

Behavior decision

• String exports and string/default object targets preserve their paths.
• Missing or falsy default values preserve the exact '' fallback.
• Target-level null deliberately changes from throwing to ''. This is safer because one malformed entry no longer aborts the entire audit; downstream drift comparison still sees an empty target.
• A top-level exports value that is neither a string nor a non-array object now throws a typed error and fails closed, instead of allowing a primitive to derive an empty inventory.

The focused suite has separate discriminating cases for the root string form, record string target, conditional default, missing default, falsy/malformed default, target-level null, and malformed top-level refusal, alongside the four existing policy-refusal tests.

Gates

• Exact CI nine-file changed-source quality scan: raw exit 0, 9 nonempty scanned paths, 0 findings, 0 allowances. The pre-fix local reproduction was raw exit 1 with exactly the two CI findings and no others.
• deno task check: raw exit 0 (package/plugin inputs cache-valid); direct focused deno check --unstable-kv on both edited files: raw exit 0.
• deno task test: raw exit 0 — 4,217 passed / 0 failed / 19 ignored, 4,236 total.
• Focused checker tests at pushed head: raw exit 0 — 12 passed / 0 failed.
• deno task docs:exports-drift at pushed head: raw exit 0; all 8 package reports unchanged, terminal PASS. Contracts and Fresh UI remain mode=complete; reasons and omission-group counts are unchanged.
• Four generated cascade outputs: no working diff; no generator ran. deno.lock remains blob a1522e6e….
• Scope audit: exactly 2 authorized implementation paths plus 4 append-only run artifacts. Protected evaluator artifacts and all prior receipts/reds are unchanged.

Evidence: .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/ci-quality-repair-evidence.md.

Stop for fresh internals Tier-A. No evaluator, readiness transition, close-gate, mirror, checkbox, merge, runtime, or publication action was fired.

[rickylabs]

[PHASE: IMPL-EVAL] [VERDICT: PASS] — cycle 5, changed-source quality repair delta

• Evaluated head: e357938df82b2a87ccc69ac3217c165c16572930 (local = remote = PR head, fetched before judging)
• Evaluator commit: 92988da30 — impl-eval.md (cycle 5) + prior canonical preserved as impl-eval-cycle-4.md; pushed by explicit refspec
• Evaluator identity: Claude Fable 5, fresh separate session, Remote Control claude.ai/code/session_016v2se871QD9Q9Rd6YADAKC (bg job dc433b8d); opposite-family to Codex GPT-5.6 Sol thread 01a005d2-7c9d-7dd1-b6fc-531b72dc14e4

Re-derived (not re-read)

1. Findings gone by real typing — zero any/as unknown/@ts-/lint-ignore/quality-allow in checker + test; scanner, code-quality.yml, --max-allow 7 byte-unchanged base→head. Pre-fix archive of 05ac90d00 reproduces exactly explicit-any L356 + unsafe-cast L372, raw exit 1.
2. Fails closed — 42/null/undefined/[]/['./a.ts']/true all throw TypeError: Deno exports must be a string or a record; no empty-map fallback.
3. Mutation test 6/6 killed — string form, conditional default, missing default, falsy default, null target, permissive top-level: each mutant fails exactly its correspondingly named test (11/1, exit 1), restored byte-identical after each.
4. Changed-files scan at head — mode: changed-files, 9 scanned (incl. both repaired files), findings: [], allowCount 0, raw exit 0. CI Code quality at e357938df is draft-skipped; this is the head-bound evidence.
5. Gates match claims — focused suite 12/0; docs:exports-drift raw 0, 8 rows, contracts/fresh-ui mode=complete, PASS; focused deno check --unstable-kv 0; fmt 0; root deno task check 0 (2925 files); root deno task test 0 — 4217/0/19 = 4236.
6. Integration contract intact — deno.lock a1522e6e… and the four cascade outputs blob-identical 8c03d8629↔e357938df; packages/+plugins/ diff empty; checker not in agent-tools.generated.ts → no publish delta.
7. Append-only — impl-eval*, plan-eval*, receipts/{s3,fix1,sa4,base-refresh}, audit/ empty diff since 05ac90d00; sa4/test.json still FAIL / exit 1 / 4202/1/19 = 4222.
8. fix(docs/exports): repair contracts and Fresh UI reference drift, then wire the regeneration gate #1296 — five rows hold (no packages//docs/site delta since cycle 4; pages step, runbook, root baseContract re-export spot-checked); Closes #1296 earned; boxes untouched.

Non-blocking observation: .llm/ is excluded from deno lint by repo config (pre-existing); the quality scanner is the governing gate there and is green.

No readiness/label/checkbox/mirror/close-gate/merge/runtime action fired; #1663/#1651 untouched. Artifact: .llm/runs/release-0.0.7-internals--orchestration/slices/reference-export-drift-gate/impl-eval.md.

[rickylabs]

[PHASE: REVIEW] [VERDICT: PASS] — coordinator readiness handoff

• Final branch head: 92988da30a4468f5ea77ea4e5a3e243469f92e52 (local = remote = PR).
• Evaluated repair head: e357938df82b2a87ccc69ac3217c165c16572930.
• Fresh separate IMPL-EVAL cycle 5: PASS at evaluator commit 92988da30; verdict, Remote Control session.
• Current origin/main is 0ef48c2ec661a7e6d55ec2faf5def6ae7dd2e6eb, already an ancestor of this branch; no base refresh is pending.
• PR Definition of Done has no unchecked rows; fix(docs/exports): repair contracts and Fresh UI reference drift, then wire the regeneration gate #1296 has all five acceptance rows checked with linked evaluator/implementation evidence.
• Review-thread gate: PASS, 0 threads / 0 unanswered.
• Acceptance mirror preflight at the final head: mapping is valid; no mutation required.
• impl-eval:skip remains intentionally attached to prevent duplicate automatic evaluation.

status:ready-merge is being applied while the PR is still draft, followed by the ready-for-review transition. Merge remains conditional on every exact-head GitHub check completing successfully, including the dedicated changed-source code-quality job that caught the prior repair need.