docs(instructions): point the logic brief at hotcrm's real layout, and put the agent briefs under a gate

[os-sales]

Fixes #1233

Two halves. The second is the one worth reviewing.

Half 1 — the stale paths

.github/instructions/logic.md named packages/crm/src/ in two worked examples, not one. The card names line 71; line 47 carries the same prefix. Re-derived on origin/main @ d3fb7ca, both fixed:

line	was	now
47	// packages/crm/src/opportunity.hook.ts	// src/objects/opportunity.hook.ts
71	// packages/crm/src/ai_briefing.actions.ts	// src/actions/ai_briefing.actions.ts

There is no packages/ directory in this repo; top-level entries are apps assets content docs e2e scripts src test.

Each target was confirmed against the real tree rather than assumed:

• Hooks are not in src/hooks/. That directory holds only index.ts, a re-export barrel; all seventeen *.hook.ts files live in src/objects/, and src/objects/opportunity.hook.ts exists. So the hook example points at the file it is an example of.
• ai_briefing.actions.ts survives the move. src/actions/ is keyed by convention on ENTITY.actions.ts, but nothing gates the basename, and global.actions.ts is the standing proof — its own header says it "is still named global.actions.ts for import stability; nothing here is a global action any more". A new AI-briefing action file belongs at src/actions/ai_briefing.actions.ts.

Half 2 — the guard, and why the pattern had to widen

These six per-role briefs sat outside every gate in the repo. Nothing under test/, scripts/ or package.json referenced the directory at all — re-measured, still 0 hits. That is why this drifted unnoticed.

The guard moved. The card points at TREE_DOCS in test/docs-drift.test.ts; #1196 split that file by family and the repo-tree path family now lives in test/docs-src-tree-paths.test.ts. The work lands there, and the SPLIT BY FAMILY pointer table in docs-drift.test.ts is updated to say so.

Two rules, because the defect has two halves:

1. src/DIR/ named implies it exists — the same check the maintainer and product docs already get, over logic.md, with the vacuity assertion PRODUCT_TREE_DOCS carries.
2. No packages/... path at all, over every .md in the directory, walked rather than listed — a brief added tomorrow is covered without anyone remembering to enrol it.

Rule 2 is not decoration, and this is the measurement the grading asked for. inlineSrcDirs() wants a directory (src/([a-z][a-z0-9_]*)/); the defect names a file directly under src/. Run the existing extractor over the unfixed brief and it returns [] — so the names-implies-exists assertion has nothing to find missing and is green. Appending the path to TREE_DOCS, which carries no vacuity guard, would have shipped a check that is green on the very defect it was added for.

Rule 2 is keyed on the tree, not on a taste for src/: packages/ is banned because this repo has none, and the assertion saying so runs first. Give hotcrm a real packages/ directory and the block throws and demands a rewrite instead of going on banning prose that has become true.

Observed failing before it was accepted

Ablation on the committed tree: the two paths were reverted to packages/crm/src/..., the mutation was confirmed on disk (2 injected lines, 0 remaining fixed lines, on-disk hash 4df75933 differing from the HEAD blob b3ae1a39), and the file was run.

Tests  2 failed | 26 passed (28)      exit 1

x no brief points into the retired packages/ layout, beyond the tracked backlog
    + ".github/instructions/logic.md"
x .github/instructions/logic.md: every src/DIR/ it names exists
    names no src/DIR/ at all ... expected 0 to be greater than 0

The second failure is the fake-green, caught in the act: the substantive missing assertion never ran, because there was nothing to check. Restored with git checkout HEAD -- ABSOLUTE_PATH, hash back to b3ae1a39, git diff HEAD empty, re-run 28 passed, exit 0. No build step is involved — the test reads the briefs as text, so there is no dist/ for a stale artefact to hide in.

The architect.md question, answered

The dispatch asked whether architect.md's packages/hr/src/... references are the same defect class. They are — the "worked teaching example" reading is only half the file.

Exact count, since it matters: 9 lines of the form packages/hr/src/NAME.KIND.ts (11-13, 17-18, 22-23, 27-28), plus packages/[name] on line 46 — 10 distinct packages/... strings.

Lines 11-28 are indeed a hypothetical Recruiting System, and taken alone the illustrative reading holds. Lines 30-37 and 46 are not examples:

• Dependency Management Rules are standing rules in the imperative, naming crm / products / finance as layered packages and forbidding imports "from a higher-layer package". None exist.
• The Output Format is mandatory — "Always start your response with the Architecture Plan" — and heads every plan the architect emits with ### 📦 Package: packages/[name]. That is a path an agent is told to write, same kind as the logic.md comment.
• The file contradicts itself: that same template fills its table rows with bare src/foo.object.ts — the single-package layout. Strong evidence the packages/ content is residue, not teaching.

It is not fixed here, and not suppressed either. The remedy is not a path rewrite: it needs a decision on whether this repo's architect plans in packages at all, and the same example routes files to .mask.ts / .workflow.ts / .rls.ts kinds that have no directory here (all three finds return nothing), so stripping the prefix would trade one absent path for another. Filed as #1518 with the measurement.

The file is recorded in PENDING_PACKAGES_REFS naming #1518, under an equality assertion, so it fails in both directions: a new brief picking up the layout goes red, and architect.md being cleaned up also goes red, demanding the entry be deleted. The exception can only shrink and cannot outlive its defect. The ablation output above shows it doing exactly that job — architect.md sits in the expected set while logic.md is reported as the new offender.

Changeset

Empty-frontmatter, matching agents-md-pure-metadata-principles.md and dangling-tabs-citations.md: agent briefs and a test only, nothing released to HotCRM users, no src/ metadata touched. The skip-changeset label is the alternative sanctioned by changeset-check.yml; the in-repo declaration was preferred because it leaves a durable record and needs no label write.

Gates

pnpm verify on d7d54a9, the tip of this branch, exit 0 — all eight stages:

✓ Validation passed (1147ms)        tsc --noEmit clean        objectstack lint
✓ i18n lint gate: 0 i18n/missing-*  ✓ source hygiene clean    ✓ source token ratchet clean
  business semantics ~83,079 / 85,000    interaction layer ~37,534 / 40,000
  authored total ~134,954 / 140,000      (the ratchet reads src/ only; nothing here moves it)
objectstack build                   Test Files 156 passed | Tests 3298 passed, 1 skipped

Landing

Draft on purpose. Per the 2026-08-25 grading on #1233 this lands by human merge, not the merge queue — .github/instructions/** is not in the literal governed-surface list, but these are per-role agent instruction files (logic.md opens "You are the Backend Engineer for HotCRM") and are treated as AGENTS.md-class. The grading also asks for os-zhuang on review; that request is left to the dispatching seat, which owns the landing path.

Whether .github/instructions/** is formally governed is not decided here — it is a change to the governed-surface definition and belongs to the maintainer / skills seat.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated
hotcrm	Ignored		Sep 3, 2026 6:40am UTC

[hotlong]

Maintainer ruling, 2026-09-03, given in chat to the director seat (session_01WXyGTWPbbreqXow7Z2pZCk) on decision batch 2, item 4 (this PR, option A: merge whole, gate included). Verbatim: 「同意」.

Executing on that instruction from the maintainer's own account: marking ready and arming auto-merge (squash), since this repository's rule requires the merge queue; the queue re-validates against today's main. No approving review is submitted by any seat; the human decision is the review record for .github/instructions/**, handled as AGENTS.md-class per the card's grading. Whether that directory is formally governed stays an open question for the maintainer and the skills seat, not decided here.

---

Generated by Claude Code