fix(core): PHASE2_IMPLEMENTATION.md imports from the root barrel, not an undeclared subpath

[claude]

Fixes #15931

Route (2) of the two the card names, as ruled at dispatch: repoint the document at the root barrel. packages/core/package.json is untouched — no ./security exports entry, no files change. Widening the published surface to make a document true stays the maintainer's call and this PR does not foreclose it.

The defect, measured live at this head

packages/core/PHASE2_IMPLEMENTATION.md sections 4 and 5 told readers to write from '@objectstack/core/security'. That subpath is declared in no exports entry, so it is refused outright rather than merely untyped:

REFUSED: ERR_PACKAGE_PATH_NOT_EXPORTED - Package subpath './security' is not defined
         by "exports" in packages/core/package.json
CONTROL: import('@objectstack/core/logger') -> RESOLVED, exports: ObjectLogger,createLogger

The control fires on the same command and scope, so the refusal is a reading and not a broken probe. exports keys re-derived on this tree: exactly ['.', './logger'], no wildcard. files: ['dist','README.md','CHANGELOG.md'].

The repair, and the proof it is true

Both lines now name @objectstack/core. Both classes are exported from the root barrel via export * from './security/index.js' in packages/core/src/index.ts, and the repaired specifier was checked against the built root entry rather than against the source:

surface	PluginPermissionManager	PluginSandboxRuntime	control: PluginSecurityScanner (retired)	control: PluginHealthMonitor
dist/index.d.ts (the . types target)	declare class @ 1577	declare class @ 1680	0 occurrences	present
dist/index.cjs (the . require target)	function	function	undefined	function

Both controls fire in the direction they should, so neither column is a vacuous read.

Counted, not eyeballed

Occurrences of the bad specifier over the whole document before editing: 2, at lines 161 and 219 — the card's arithmetic holds and its line numbers are exact, not stale. Firing control on the same command and file: @objectstack/core without the /security tail counted 5. After the edit: 0 bad, and the two repaired lines join the four that already named the root barrel.

Repo-wide, the import-statement shape from '@objectstack/core/security' existed in exactly these 2 places plus one prose row in docs/qa/platform-checklist/FOLLOW-UPS.md that describes this very defect (control on the same command and scope: the same shape on the real ./logger subpath returns 2 files). The other 14 files carrying the string carry it as prose, changelog history, or a @module tag — none is an import instruction. Every from '@objectstack/...' specifier in this document was swept: only two distinct ones exist, @objectstack/core (now 6) and the repaired subpath (now 0).

Two prose notes that this PR makes stale — flagged, deliberately not edited

Both describe the residue as still present, and both stop being true when this lands. They are named here rather than fixed, because neither repair is mechanically pinned and one of them sits in a test file whose suite this diff otherwise does not touch:

• docs/qa/platform-checklist/FOLLOW-UPS.md — "sections 4 and 5 still tell readers to import … from '@objectstack/core/security' … Deliberately left".
• packages/core/src/security/security-scanner-retirement.pin.test.ts — a comment reading "PHASE2_IMPLEMENTATION.md sections 4 and 5 still teach it; filed separately". No assertion in that file reads the document, so nothing there goes red.

Contract and publishing

Clause-②: no — re-derived from this diff, not predicted. The diff is one markdown file that reaches no published artefact: untouched text from the document appears in 0 files under packages/core/dist/, while three firing controls on the same command and scope reach 6, 6 and 4 dist files — the third taken from a source comment, which proves sourcemap sourcesContent was inside the compared set and the zero is not a scope artefact. npm pack --dry-run over packages/core lists 16 files; PHASE2_IMPLEMENTATION.md is not among them, while the controls README.md and dist/index.d.ts are. No accept set moves, no exported symbol moves.

No changeset, skip-changeset label instead — measured by that same npm pack reading rather than assumed: this diff publishes nothing from any released package.

Gates

All 36 families derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (derived from the real change set, not from a hand-written list) were run, 36/36 green, on the final commit 9b833a084 against a clean tree — exit codes captured by redirect-then-read, never through a pipe. The family was not narrowed for being markdown: check:system-context-census and the other anchor/census families were run in full, and separately no PHASE2_IMPLEMENTATION.md:LINE anchor exists anywhere in the tree (0 hits, with a firing control proving 45 files under docs/ do carry PATH:LINE anchors). The diff changes no line count regardless: 375 lines before and after.

Two of the 36 first returned PREREQUISITE NOT MET (exit 3, which is not a red and not a pass); a full pnpm build — 72/72 tasks — was run under the shared verify lock and both were re-run to a real green: check:dual-build-cjs-loads over 103 entries / 66 packages / 619 CJS files, and check:dts-closure over 72 built packages with @objectstack/core in the swept set.

check:published-readme-exports was also run to a real green over its full population — 60 published documents across 79 workspace packages — and confirms the card's account of why no gate saw this: PHASE2_IMPLEMENTATION.md is not one of the 60, because packages/core does not publish it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/core/PHASE2_IMPLEMENTATION.md), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/core/PHASE2_IMPLEMENTATION.md) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 159dbad233cf84476c2c552c2a962bed1d4b5172 → packageMentionDocs.

[claude]

Backlinks for the two things this PR reports but does not change, both filed unassigned and ungraded:

• lint: no gate resolves a documented @objectstack/* import SPECIFIER against the target package's exports map — check:published-readme-exports asks a different question #16207 (finding) — the gate the card's "Acceptance" section floats: no gate resolves a documented @objectstack/* import specifier against the target package's exports map. Ruled out of scope at dispatch, and it needs its own population count before it can be written. The body carries the sizing evidence this round measured: 16 tracked files carry the string @objectstack/core/security, only 3 in an import-statement shape, only 2 of those instructions to a reader.
• docs: two prose notes still describe PHASE2_IMPLEMENTATION.md sections 4 and 5 as teaching the unresolvable @objectstack/core/security subpath, which PR #16205 repaired #16208 — the two prose notes that go stale when this lands (docs/qa/platform-checklist/FOLLOW-UPS.md, and a header comment in packages/core/src/security/security-scanner-retirement.pin.test.ts). Neither goes red; the PR body section "Two prose notes that this PR makes stale" explains why they were reported rather than absorbed.

---

Generated by Claude Code