A script's execution plane must be DERIVED from capability closure, not declared in a header

Status

AMENDED 2026-08-11 after Drop+Supersede on PR #16944 (closed unmerged). The original prescription — a per-file @plane header plus a token-matching classifier — is retired, not iterated. What replaced it and why is below; the salvage map is in the PR's closing comment.

The defect (unchanged, and still real)

ai/scripts names its directories after the verb and never the execution plane. Per Local Runtime Parity a client topology has no host shell and no Docker socket, so a host-edge script is dead weight there — and finding that out means opening the file. npm run ai:structure-map emits {path, fileCount}: a census, not a map. There is no navigational surface anywhere under ai/scripts.

Why the original prescription was wrong

Discussion #16652 is graduated ([DIVERGENCE_FOLDED]) and already settled this.

• Option D — RETIRED as a plane mechanism: "Directory carries no plane information."
• Option F — RETIRED, two independent falsifiers: "a directory-keyed plane predicate lies."
• Option B — SURVIVES, the convergent shape: an entrypoint-owned authority × capability-closure guard.

On method it is explicit: classify "by what each script reaches, not by what its name says — a header is a name, and this proposal exists because names lie." A @plane header is a name. @neo-opus-ada had already delivered the classification over all 139 entrypoints by transitive reach: 56 store-touching / 11 ambiguous / 72 host-safe.

ADR-0014 independently falsifies the token predicate. Its backup row names the git rev-parse HEAD bundle-meta stamp — the call at ai/scripts/maintenance/backup.mjs:953 — and rules it not a host dependency because it degrades to null without .git. A predicate keyed on "imports child_process" conflates using a capability with requiring one, and convicts backup.mjs against an accepted ADR.

Process cause, recorded so it is not repeated: no prior-art sweep was run before design. §verify_before_assert requires one over the decision space precisely because rigour inside the wrong unit of truth produces authoritative-looking wrong answers at scale.

The Fix

Derive each entrypoint's plane from executable-root authority × transitive capability closure. Nothing is declared by hand.

1. Walk each ai/scripts entrypoint's static import graph to fixpoint, collecting reached capabilities (store packages, host-only surfaces, plane services).
2. Resolve the entrypoint's plane from that closure, taking ai/daemons/orchestrator/taskAuthority.mjs (TASK_AUTHORITY_BY_NAME) as the authority input for mapped tasks rather than re-deriving it.
3. structure-map projects the derived plane per entrypoint plus a per-folder tally — generated, so it cannot rot.
4. An unresolved edge is a named finding, never a silent default.

Requirement vs use is the load-bearing distinction: a capability reached on a path that degrades gracefully is not a requirement. ADR-0014's backup row is the canonical fixture for it.

Carried forward from PR #16944

The enforcement and projection scaffolding is reusable and must not be rebuilt: the hosted script-plane-lint workflow and its real CI reach, the structure-map plane projection and per-folder tally, the stripComments relocation into a shared module, and the header-region fixtures. Discarded: the @plane tag on 146 files and the per-file token classifier.

Acceptance Criteria

• Plane is derived for every ai/scripts entrypoint from transitive capability closure. No hand-authored per-file plane metadata exists.
• TASK_AUTHORITY_BY_NAME is consumed as the authority for mapped tasks, not re-derived, and a disagreement between it and the closure is a hard failure.
• Red-proven against githubWorkflowSync — the false negative the per-file classifier produced.
• Red-proven against backup — the false positive against ADR-0014, with the graceful-degradation path as the reason it is not host.
• Unresolved edge is reported as a named finding, with a fixture; it never falls back to a default plane.
• Non-vacuity: a genuine host entrypoint and a genuine in-plane entrypoint are both classified correctly and neither is reported.
• ai:structure-map projects the derived plane per entrypoint and a per-folder tally; every mixed directory is identifiable from that output alone.
• The lint runs in CI and is registered in the workflow scan-root parity registry (lintWorkflowScanRootParity.spec.mjs) — the separate red on PR #16944.

Out of Scope

• Moving or renaming any file; the SDK/barrel split tracked by Discussion #16652 is its own lane.
• Re-litigating Discussion #16652's dispositions.
• Any judgement about whether a given script should be host-edge.

Avoided Traps

• Hand-authored plane metadata. A header is a name, and this ticket exists because names lie.
• A directory-keyed predicate. Measured to lie; retired twice in #16652.
• Treating capability USE as capability REQUIREMENT. ADR-0014's backup row is the fixture that convicts it.
• A silent default for unresolved edges. The default nobody argues with is where a comparator loses its teeth.
• Iterating the per-file classifier. It is the wrong unit; a better token list does not fix a unit error.

Decision Record impact

none — this applies Discussion #16652's graduated Option B to the ai/scripts surface and consumes ADR-0014's taxonomy. It amends neither.

Origin Session ID: 83ee6112-e066-42b4-a1b5-d064d0f9c276

Retrieval Hint: "ai/scripts execution plane transitive capability closure entrypoint authority"; superseded per-file @plane tag approach.