lint: complete the hook-rule reach ledger — enumerate the intakes, pin the scaffold door

The reach annotation landed naming three `os *` commands. The doors are the
call sites of `runAuthoringRules`, and there are more of them than there are
commands: `os build` enters twice (the union run and the per-package run) and
`runScaffoldAuthoringRules` — which `os init` / `dev` drive over a rendered
template — is a fourth intake that lowers before it parses and has therefore
reached this family all along. A ledger that omits a reached door mis-states
coverage in the same direction the card is about.

Both rule headers now enumerate every measured intake, each recorded with the
body-authored control that makes its verdict readable, and the scaffold door
gains a pin with that control beside it. The pin asserts `schemaError` is null
before reading the verdict, so a stack that stops parsing cannot read as "no
finding". No rule logic changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vbw3RPgdtqesx4azk9SbW8

Author: claude

.changeset/lint-hook-rules-reach-handler-authored-hooks.md

@@ -14,4 +14,6 @@ The `hook-body-write-unknown-field`, `hook-body-write-unprovisioned-anchor`, `ho
 - Nothing about what `objectstack build` accepts changes, and `objectstack validate` — which parses without lowering — is unchanged and still does not see handler-authored hooks; both are recorded in the rules' headers.
 - The lint input is never mutated: rules that read the live function value (`hook-body/not-lowerable` and its siblings) keep seeing it, and a handler the extractor refuses has no body on any command, so no rule guesses about a body that was not produced.
 
-`@objectstack/lint` carries only the header ledger recording which commands reach each hook rule; its behaviour is unchanged.
+Measured on this repository's own four example apps (`examples/app-crm`, `app-showcase`, `app-todo`, `app-multi-package`), before and after: **121 findings before, 121 after — row for row identical, and zero at `error` on both sides.** No config that passes today starts failing. Two of the six hooks in that corpus are `handler`-authored and were invisible to this family before; their bodies write nothing the family objects to, which is why the delta is zero rather than the family being unreached. The reach itself is pinned separately, with a body-authored control beside every leg.
+
+`@objectstack/lint` carries only the header ledger recording which *intakes* reach each hook rule — the call sites of `runAuthoringRules`, which are more numerous than the three commands (the scaffold validator is a fourth, and it has always reached this family). Its behaviour is unchanged.

packages/cli/test/lint-hook-rules-reach-handler-hooks.test.ts

@@ -20,6 +20,7 @@
 import { describe, expect, it } from 'vitest';
 import { normalizeStackInput } from '@objectstack/spec';
 import { lintConfig } from '../src/commands/lint';
+import { runScaffoldAuthoringRules } from '../src/utils/scaffold-validate';
 
 const READONLY_RULE = 'hook-api-update-readonly-field';
 const READONLY_WHEN_RULE = 'hook-api-update-readonly-when-field';
@@ -199,3 +200,43 @@ describe('#16095 — the lowering is a VIEW for the registry, not a rewrite of t
     expect(issues.filter((i) => i.rule === READONLY_RULE)).toEqual([]);
   });
 });
+
+/**
+ * The FOURTH door, and the reason it is pinned here rather than left to the
+ * three `os *` legs in the e2e sibling.
+ *
+ * `runScaffoldAuthoringRules` is a separate entry into the same registry —
+ * `os init` / `dev` drive it over a freshly rendered template — and it is NOT
+ * one of the three commands. It reaches the family, and always did, because it
+ * lowers before it parses exactly as `compile.ts` does; nothing in this card
+ * changed it. It is pinned because an unpinned reached door is the failure the
+ * ledger in the two rule headers exists to prevent: a reachability claim
+ * measured through one entry point is a claim about that entry point, not
+ * about the rule. The control below is what makes the RED leg readable — if
+ * the scaffold path ever stops lowering, the handler leg goes silent while the
+ * body leg keeps firing, and that asymmetry is the signal.
+ */
+describe('#16095 — door: `runScaffoldAuthoringRules` (reached, and not one of the three commands)', () => {
+  const scaffoldStack = (hook: Hook) => ({ objects: OBJECTS, hooks: [hook] });
+  const familyOf = (hook: Hook) => {
+    const report = runScaffoldAuthoringRules(scaffoldStack(hook));
+    // A schema failure returns empty lists, which would read exactly like "no
+    // finding" — assert the stack actually parsed before reading the verdict.
+    expect(report.schemaError).toBeNull();
+    return [...report.errors, ...report.advisories].filter((f) => f.rule === READONLY_RULE);
+  };
+
+  it('INTAKE — the handler-authored hook IS judged here (it lowers before it parses)', () => {
+    expect(
+      familyOf(
+        handlerHook('escalate', async (ctx: any) => {
+          await ctx.api.object('crm_case').update({ id: ctx.input.id, is_escalated: true });
+        }),
+      ),
+    ).toHaveLength(1);
+  });
+
+  it('CONTROL — the identical statement as an explicit `body` fires the same finding', () => {
+    expect(familyOf(bodyHook('escalate_body', WRITE_READONLY_SOURCE))).toHaveLength(1);
+  });
+});

packages/lint/src/validate-hook-body-writes.ts

@@ -719,15 +719,27 @@ export function extractHookBodyWriteSet(source: string): ExtractedHookBodyWriteS
  * is a property of the DOOR — what each caller hands this function — not of
  * the rule. Measured (`packages/cli/test/lint-hook-rules-reach-handler-hooks*`):
  *
- *   `os build`     lowers every inline handler to a metadata body before its
- *                  parse (`lowerCallables`) — REACHED, always was.
- *   `os lint`      hands the registry's `parsed` tier that same lowered view —
- *                  REACHED since #16095.
- *   `os validate`  parses the normalized stack without lowering — NOT reached;
- *                  the body-authored control fires there. Changing that
- *                  changes what `os validate` refuses and is its own decision.
- *   direct call    judges exactly the stack it is given — NOT reached unless
- *                  the caller lowers first.
+ * Every leg below was measured with the body-authored control beside it, so a
+ * silent leg is a reading about that door and never about this rule. The doors
+ * are the call sites of `runAuthoringRules`, enumerated — not the three `os *`
+ * commands, which are fewer than the doors:
+ *
+ *   `os build` union        `compile.ts` lowers every inline handler to a
+ *                           metadata body BEFORE its parse (`lowerCallables`)
+ *                           and judges the parsed result — REACHED, always was.
+ *   `os build` per-package  same lowered `result.data`, re-entered one package
+ *                           manifest at a time — REACHED, always was.
+ *   `os lint`               hands the registry's `parsed` tier that same
+ *                           lowered view — REACHED since #16095.
+ *   scaffold validate       `runScaffoldAuthoringRules` (`os init` / `dev` over
+ *                           a rendered template) lowers before it parses too —
+ *                           REACHED, always was, and pinned since #16095.
+ *   `os validate`           parses the normalized stack WITHOUT lowering — NOT
+ *                           reached; the body-authored control fires there.
+ *                           Changing that changes what `os validate` refuses
+ *                           and is its own decision, not this card's.
+ *   direct call             judges exactly the stack it is given — NOT reached
+ *                           unless the caller lowers first; measured both ways.
  *
  * A handler the extractor refuses (forbidden token, free identifier,
  * unparseable) is left with no `body` on every door, so this rule stays silent

packages/lint/src/validate-readonly-hook-writes.ts

@@ -284,15 +284,27 @@ function isRec(v: unknown): v is AnyRec {
  * is a property of the DOOR — what each caller hands this function — not of
  * the rule. Measured (`packages/cli/test/lint-hook-rules-reach-handler-hooks*`):
  *
- *   `os build`     lowers every inline handler to a metadata body before its
- *                  parse (`lowerCallables`) — REACHED, always was.
- *   `os lint`      hands the registry's `parsed` tier that same lowered view —
- *                  REACHED since #16095.
- *   `os validate`  parses the normalized stack without lowering — NOT reached;
- *                  the body-authored control fires there. Changing that
- *                  changes what `os validate` refuses and is its own decision.
- *   direct call    judges exactly the stack it is given — NOT reached unless
- *                  the caller lowers first.
+ * Every leg below was measured with the body-authored control beside it, so a
+ * silent leg is a reading about that door and never about this rule. The doors
+ * are the call sites of `runAuthoringRules`, enumerated — not the three `os *`
+ * commands, which are fewer than the doors:
+ *
+ *   `os build` union        `compile.ts` lowers every inline handler to a
+ *                           metadata body BEFORE its parse (`lowerCallables`)
+ *                           and judges the parsed result — REACHED, always was.
+ *   `os build` per-package  same lowered `result.data`, re-entered one package
+ *                           manifest at a time — REACHED, always was.
+ *   `os lint`               hands the registry's `parsed` tier that same
+ *                           lowered view — REACHED since #16095.
+ *   scaffold validate       `runScaffoldAuthoringRules` (`os init` / `dev` over
+ *                           a rendered template) lowers before it parses too —
+ *                           REACHED, always was, and pinned since #16095.
+ *   `os validate`           parses the normalized stack WITHOUT lowering — NOT
+ *                           reached; the body-authored control fires there.
+ *                           Changing that changes what `os validate` refuses
+ *                           and is its own decision, not this card's.
+ *   direct call             judges exactly the stack it is given — NOT reached
+ *                           unless the caller lowers first; measured both ways.
  *
  * A handler the extractor refuses (forbidden token, free identifier,
  * unparseable) is left with no `body` on every door, so this rule stays silent