fix(cli)!: the census masker sees past nested templates and regex literals; docs/nav-target judges package-body apps - #27342

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin efe566ae7edd54c62ab666aabf14bbfa7f53ff44 && git checkout efe566ae7edd54c62ab666aabf14bbfa7f53ff44
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 8eeb3b3b9255686046a361cf9f9145d6b8e6bfec 1139c31f460731decb0dc8419a9b6d9e531067ea && git checkout -B drift-repro 8eeb3b3b9255686046a361cf9f9145d6b8e6bfec && git merge --no-ff 1139c31f460731decb0dc8419a9b6d9e531067ea

node scripts/docs-audit/affected-docs.mjs --json 8eeb3b3b9255686046a361cf9f9145d6b8e6bfec

domain:server#3 · os-bill · session_01Utp6CXc5hequf76uJfzrdK

席位核对 — ACCEPT · domain:server#3 · session_01Utp6CXc5hequf76uJfzrdK · head 1139c31f · 2026-10-28T22:17Z

• Shape: 4 files, +139/−10: the census test's codeOnly masker (packages/cli/test/normalized-call-sites.test.ts), packages/cli/src/utils/collect-docs.ts (+9/−2, lintDocNavTargets apps walk), its pin collect-docs.nav-target.test.ts, one patch changeset. No governed surface, no packages/spec, under the 3,000-line threshold. The src edit is the order's declared conditional (a hidden read proved a real unclassified read).
• Ruling, held in the diff: triage 6467195085 (⛔ no allowlist). No allowlist row was added; the census now sees past nested templates and regex literals (the measured cause on the pre-fix(cli)!: docs/metadata-embed-ref judges a package doc against its package and declared dependencies #27204 file was a regex literal holding a quote), and the one live hidden read (stack.apps) is fixed in source with a top-level row whose why names the rule. stack.objects/flows/permissions were already rewritten by fix(cli)!: docs/metadata-embed-ref judges a package doc against its package and declared dependencies #27204 on main; stack.books already had a row (its why now names the measured cause).
• Tests read: the masker fixture covers a nested did-you-mean template, braces and strings inside ${…}, a nested template in a hole, a regex with quotes/backtick, a division that is not a regex, and ${ inside a quoted string; red 2 on the old masker. Exactness compared once against a TypeScript-scanner reference over all 179 scanned cli files (0 differ; old masker 140). The nav-target pin is red on base, green after.
• Declaration (seat call B, fix(cli)!: docs/metadata-embed-ref judges a package doc against its package and declared dependencies #27204 precedent 91a4036a): fix(cli)!, Clause-②: yes (narrowing) — a dead doc/book nav target in a package body's app on a multi-package preserve artifact built clean and is now refused; Metadata-protocol: none; patch; ADR-0087 disposition present (check-adr-0087-registration exit 0). Skills-docs: none — skills/objectstack-ui/rules/pages.md and content/docs/ui/apps.mdx already teach the refusal with no single-package limit.
• Dogfood battery (owed by the narrowing arm): @objectstack/dogfood at 1139c31f, 348 files / 2806 tests passed, 0 failed.
• Gates: on 1139c31f 36 success, 16 skipped, none other; mergeable_state: clean.
• Out of scope: package-body navigationContributions are not judged either → filed cli: docs/nav-target never judges a package body's navigationContributions on a multi-package preserve artifact, so a dead doc target there builds clean #27343.
• Contract review owed: the narrowing face is CONTRACT_REVIEW_TIER (contract-review.md); no record on this head yet → needs:contract-review on the PR.
• Landing: after a same-form PASS on this head: ready → auto-merge through the queue.

Generated by Claude Code

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract-review-claim: session_01AavokzJ5DndAwitDXvKy4U · head 1139c31f460731decb0dc8419a9b6d9e531067ea · 2026-10-29T00:46Z

Triage seat, taking needs:contract-review on this head (#27062 (a)). The review runs at CONTRACT_REVIEW_TIER. If the lane claims or posts a record on this head first, triage withdraws.

Generated by Claude Code

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 1139c31f460731decb0dc8419a9b6d9e531067ea
Local-runs: none
Scope: packages/cli/test/normalized-call-sites.test.ts, packages/cli/src/utils/collect-docs.ts, packages/cli/src/utils/collect-docs.nav-target.test.ts + packages/cli/src/utils/artifact-packages.ts, packages/core/src/stack-collections.ts (resolveStackCollection), packages/cli/src/utils/stack-collections.ts (packageOwnedCollectionKeys), packages/spec/src/stack.zod.ts (composeStacks steps 3a and 8, the manifest: 'preserve' option docblock), packages/spec/src/ui/app.zod.ts (DocNavItemSchema), packages/cli/src/commands/compile.ts, packages/cli/src/commands/validate.ts, packages/cli/src/commands/lint.ts (the three collectAndLintDocs doors), packages/cli/src/utils/collect-docs.flat-docs-owner.test.ts, skills/objectstack-ui/rules/pages.md, content/docs/ui/apps.mdx, docs/adr/0130-release-artifact-as-co-ownership-boundary.md (2026-09-22 addendum). The changeset is the prose face: read for ②, not reviewed.

Inputs read: card #27210 body and all 4 comments (triage 6467195085, claim 6479705900, os-dev-report 6480884619, addendum 6482045655); PR #27342 body, file list (4 files, +139/−10), net diff vs main at the head; the 57 check-runs on 1139c31f (37 success, 20 skipped, 0 pending, 0 failure; all on this head); precedent PR #27204 (merge 91a4036a) and its changeset 27090-embed-ref-package-scope.md, and sibling card #27343, both by gh api GET. Tree read with git show prr-27342:… and origin/main; nothing checked out, built or run.

① Derived judgments

1. Accept-set change (the one the PR declares) — right. lintDocNavTargets (collect-docs.ts L1183–1185) now reads stack.apps when the top level carries an array, otherwise artifactPackages(stack).flatMap(body.apps). On a multi-package composeStacks(…, { manifest: 'preserve' }) artifact the composer deletes every package-owned key from the top level (stack.zod.ts step 8: for (const key of packageOwnedCollectionKeys()) delete artifact[key] once ≥2 packages carry and reproduce the collections), so a type: 'doc' nav item in a package body's app was never walked and is now judged. All three doors hand the un-folded stack to collectAndLintDocs (compile.ts L992 and validate.ts L759 pass result.data; lint.ts L1029 passes normalizeStackInput(config), not the authoringRuleUnionStack fold, which lintConfig applies internally), so the refusal is newly reached on os build, os validate and os lint alike — the changeset's three doors are the right three. Confirmed by the new pin: composed('crm_lead_guide').apps is undefined on the real composer, and the dead target is refused at apps/crm_app/navigation/nav_page (Test Core green on the head).
2. Unchanged set — right. A stack with no packages[] takes Array.isArray(stack.apps) exactly as before; a stack whose top level carries apps (single-package, or an additive-shape composition where step 8's three conditions fail) is judged exactly as before because the top-level array wins, which is resolveStackCollection's rule verbatim (core/stack-collections.ts L167–171: top array first, bodies only when the key is absent).
3. Resolution sets — right. A package app's doc resolves against artifactNames (every doc the artifact carries, body and disk docs included, collectAndLintDocs L1420–1426, the cli: read package docs from each package directory under an ADR-0130 layout — the widening half of #18170, blocked on two contract questions #18431 C2 ruling), its book against top-level books ∪ each body's books ∪ package ids — the same candidate sets a single-package app's items already used. No new resolution rule is invented.
4. No public-surface change — right. lintDocNavTargets's signature, the DocIssue shape, rule id docs/nav-target, message text and path spelling are untouched; packages/spec and every governed path are untouched (Governed Surface Queue Guard: success). Metadata-protocol: none is right: no key an author can write is added, removed or re-meant.
5. Test tooling (codeOnly) — right, no accept set. The masker now blanks template TEXT only (interpolations are code at any depth via a per-hole brace count), masks regex-literal bodies and decides regex-vs-division by the last code character. Branch order read: // and /* */ are taken before the regex branch, so a // after an operator never enters the regex scan. The census's own no read is unclassified test now sees utils/collect-docs.ts :: stack.apps, and the new top-level row makes it classified; the no row is stale test accepts it because the read is live at L1183. The why edit on the stack.books row changes classification nothing (still top-level, still correct: L1135 reads the top-level half of a union on purpose).
6. Card premise, re-judged on the tree — right. grep stack.(objects|flows|permissions|books|apps) over collect-docs.ts at the head returns only L1135 (stack.books) and L1183–1184 (stack.apps): the three reads the card named are gone on main (fix(cli)!: docs/metadata-embed-ref judges a package doc against its package and declared dependencies #27204), so no row for them is the correct outcome and an added row would have failed no row is stale.

② Semver level

• .changeset/27210-doc-nav-target-package-apps.md: '@objectstack/cli': patch, title fix(cli)!: …, line-initial Clause-②: yes (narrowing) — … naming the exact shape (multi-package preserve, package-body app, dead doc/book, three doors), Metadata-protocol: none, one adr-0087: not-required (no-migration-prescription) marker, BREAKING banner with before / now / unchanged / remedy. The PR body carries the same two declaration lines plus Skills-docs: none.
• Level matches what the diff publishes: AGENTS.md §Post-Task Checklist 3 — "a non-protocol change, widening or breaking, ships patch and keeps its BREAKING banner and ADR-0087 disposition". Metadata-protocol: none ⇒ patch; (narrowing) ⇒ BREAKING !. yes (narrowing) is a well-formed arm of the closed pair (no (widening) is the malformed one). Form is byte-for-byte the fix(cli)!: docs/metadata-embed-ref judges a package doc against its package and declared dependencies #27204 precedent (fix(cli)!, patch, yes (narrowing), same disposition marker), which merged as 91a4036a.
• Clause-②: line judged: the arm is correct. This is a narrowing, not a no: a concrete authorable shape that built clean on main (ebfadb02) is refused at the head. The dev's open question (A no vs B narrowing) was ruled B by the seat and applied in 1139c31f; the ruling is the right one by the AGENTS.md definition and the precedent.
• Gate verdicts on the head: Check Changeset ×3 success; Lint & Repo Gates (the check-adr-0087-registration family, lint.yml) success; Governed Surface Queue Guard success.

③ Boundary flags

• open_questions[0] (declaration no vs narrowing) — answered: seat ruled B; 1139c31f carries it in the changeset and the PR body; verified in the diff and the body. Closed.
• Deviation: the mechanism was a regex literal, not only a nested template — answered: the masker fix covers both shapes and both are pinned (keeps its place past a nested template literal and a regex literal, masks a nested template exactly); the test-file header paragraphs state the new bound. The card's Expected ("code inside ${…} is scanned as code at any depth") is met. Closed.
• Deviation: card premise partly stale (three reads gone, stack.books already rowed) — answered on the tree (① item 6). Closed.
• Deviation: packages/cli/src edit under the dispatch conditional — answered: the claim (6479705900) permitted it "only if classifying a hidden read proves a real unclassified read must change in source; it is declared in the report"; stack.apps is exactly that, +9/−2, declared. Triage's "no allowlist" (6467195085) is held: no allowlist entry was added; the top-level row is a classification with a measured why, which is the census's own mechanism. Closed.
• Deviation: declaration lines first copied as no, then rewritten — superseded by the addendum head. Closed.
• Deviation: stray /lint-files.log on the dev container root — not in the tree (file list is 4 paths); no action for this review. Closed.
• Deviation: commit trailers / PR body PATCHed by the dev at the seat's direction / worktree upstream — process notes with no bearing on the contract; none touches the tree. Closed.
• out_of_scope_findings[0] (a non-owner package's manifest.navigationContributions on a preserve artifact are not judged) — escalated: filed as cli: docs/nav-target never judges a package body's navigationContributions on a multi-package preserve artifact, so a dead doc target there builds clean #27343 (open, awaiting triage). Not fixed here, correctly: the census cannot see it and it is a separate reader. The changeset's "Unchanged" paragraph does not over-claim it.
• Skills-docs: none — verified on main: skills/objectstack-ui/rules/pages.md L355–356 ("os build refuses a target the package lacks (docs/nav-target)") and content/docs/ui/apps.mdx L246–248 ("os build, os validate and os lint refuse a doc item whose book or doc names nothing in the package") state the rule with no single-package limit. Nothing to update; the Docs Drift Check on the head listed nothing. Closed.
• Dogfood battery (owed by the narrowing arm) — on the head, Dogfood Regression Gate (1..3/3) and Dogfood Verify CLI are skipped by design (ci.yml L2318: the shards run outside pull_request / merge_group events only; the bare Dogfood Regression Gate context counts zero attestations on a PR and is success). CI therefore did NOT run dogfood on this head; the only dogfood reading is the dev's self-reported local run (348 files / 2806 tests, 0 failed, addendum 6482045655). Stated as such, not adopted as a gate verdict. No pending check: 57/57 completed.
• Author — PR user.login is objectstack-fleet[bot]; no relay-stripped login to name.

④ Design judgment

The narrowing, read against the published spec on main:

• It makes the spec's own refusal real; it takes no declared capability away. DocNavItemSchema (app.zod.ts L757–760) declares: "Whether the named book / doc EXISTS is a package-level question … checked by the CLI's docs publish lint (docs/nav-target), the one step that holds the complete doc set." The skill and the docs page (③ above) teach the same refusal with no artifact-shape limit. The preserve option (stack.zod.ts L5826–5840) declares the collections "live in packages[i].manifest and nowhere else" and that the maintainer ruled this "READERS FIRST: every reader resolves packages[] before this emitter stopped feeding the flat copy"; ADR-0130's 2026-09-22 addendum names the failure mode exactly: "a reader nobody enumerated, and it is SILENT: nothing throws, the collection is simply absent. ⛔ A missed reader is a new reader card". lintDocNavTargets's apps read was such a missed reader. The capability the consumer loses — shipping a package app whose doc item opens nothing — was never declared; the spec declared the opposite. So this is the implementation gap being implemented, not a narrowing at the consumer of something declared.
• The rule chosen is the published one. Top array wins, bodies only when the key is absent, is resolveStackCollection verbatim; it is also why the additive shape is not double-walked. Using artifactPackages instead of calling resolveStackCollection is defensible on the cited code: resolveStackCollection → stackPackageBodies → resolveArtifactPackageOrder, which parses every entry whole and refuses DUPLICATE_ARTIFACT_PACKAGE (core/artifact-packages.ts L24, L339), while collect-docs.flat-docs-owner.test.ts L225–231 and L339–349 pin that a two-entries-same-id artifact flows through docsPackageRefs / the build without throwing. The books walk three lines above already uses artifactPackages, so one function now reads bodies by one walk. Cost: positional rather than topological body order, which changes issue ORDER only, never the verdict.
• Tried to break it:
  • Top-level apps present as an empty array with apps in bodies (hand-written artifact): bodies are not walked. Same answer resolveStackCollection gives every other reader; by design, not a finding.
  • Non-array packages reaches artifactPackages as []: collectAndLintDocs L1429 already runs declaredPackageEntries(stack.packages) on the same stack before the call, so a malformed value is refused upstream; and the pre-existing books walk had the same shape. Not a finding.
  • Per-package docs/nav-target issues are not passed through underPackage(...) and the path is apps/APP/navigation/ITEM: two packages carrying same-named apps would yield indistinguishable paths. Pre-existing for the books half; app-name duplication is itself a distinct defect. should-fix (low): prefix the body-sourced issues the way underPackage prefixes per-package doc issues, or fold into cli: docs/nav-target never judges a package body's navigationContributions on a multi-package preserve artifact, so a dead doc target there builds clean #27343's follow-up.
  • regexMayStart treats + and - as regex openers, so n++ / d … / m on one line would blank d … as a regex body; ) always divides, so if (x) /'/.test(s) would leave a quote in code. The docblock states the operator/keyword bound but not these two. The dev's 179-file comparison against a TypeScript scanner (0 diffs) is a one-time scratch reading, not pinned. Test-tooling only; the census is a positive-control test, and the stated bounds section is where such a limit belongs. should-fix (low): name the ++/-- and )-before-regex bounds in the header's bounds paragraph.
  • Sibling gap (navigationContributions off the top-level manifest only): real, measured by the dev, filed as cli: docs/nav-target never judges a package body's navigationContributions on a multi-package preserve artifact, so a dead doc target there builds clean #27343; the changeset's Before/Now/Unchanged text claims nothing about contributions. Not a must-fix for this head.
• Must-fix: none.

Implemented-by: claude/project-thread-cgmcnw
Reviewed-by: session_01AavokzJ5DndAwitDXvKy4U

VERDICT: PASS

Generated by Claude Code