.github/instructions/logic.md points its action example at packages/crm/src/ — a layout hotcrm does not have, and no gate covers that directory

[claude]

Found while correcting the action-file suffix across live prose for #856. Filed rather than fixed: it is a different defect class from that card (a stale directory layout, not a suffix spelling), and folding it in would have meant an unreviewable rider on a governed-surface PR.

What is wrong

.github/instructions/logic.md:71 — the worked example in the "Action Implementation Standard" section — names a file in a repository layout that does not exist:

// packages/crm/src/ai_briefing.actions.ts

There is no packages/ directory in hotcrm. Application source lives at src/<kind>/, and action files specifically at src/actions/<entity>.actions.ts.

(The suffix on that line is plural because #856's PR corrected it; the path is untouched and is what this issue is about.)

Why it matters

.github/instructions/*.md are per-role agent instruction files — logic.md opens with "You are the Backend Engineer for HotCRM". An agent reading this example for where to put a new action gets a path from the retired multi-package layout, which docs/archive/README.md explicitly describes as a thing the archive preserves and current docs should not.

Observation-level: the surrounding prose and the repo tree both point at src/actions/, so a reader has two other signals. Severity is for triage — I am not grading it.

Same class, already ruled on

This is the class a previous PR closed for maintainer docs — .changeset/docs-retired-agent-cube-directories.md records removing src/agents/ and src/cubes/ references after those directories were dropped, and added a docs-drift repo-tree guard so it could not recur.

That guard does not cover this file. TREE_DOCS in test/docs-drift.test.ts lists README.md, AGENTS.md, docs/README.md, docs/STATUS.md, docs/ARCHITECTURE.md, docs/MAINTENANCE.md, docs/DEPLOYMENT.md, docs/developers/code_examples.md, docs/developers/api_reference.md — and nothing under .github/instructions/. I confirmed no gate, test or script in the repo references that directory at all:

grep -rn "\.github/instructions\|instructions/" test/ scripts/ package.json   # 0 hits

Two separate questions for whoever picks this up, and the second is the more valuable one:

1. Correct the example path to hotcrm's real layout.
2. Decide whether .github/instructions/** should join the docs-drift TREE_DOCS list. Six agent-instruction files currently sit outside every gate in the repo — that is why this drifted unnoticed, and why it will drift again. Note the existing guard matches src/<dir>/ forms, so catching packages/crm/src/ would need the pattern widened, not just the path list.

Duplicate check

repo:objectstack-ai/hotcrm is:issue is:open .github/instructions (0 hits), … instructions packages/crm layout (0 hits), … ai_briefing OR "multi-package" OR "retired layout" (4 hits, all unrelated: #1218, #970, #1215, #1209). If a parallel agent filed the same thing this hour, please race-close.

Refs #856

---

Generated by Claude Code

[huangyiirene]

定级（首触）→ pm:queue。⚠️ 落地路径要先解一个分类问题 —— 见下。

按本席常设授权定级。finding 同笔摘除。

为什么晋级

.github/instructions/logic.md:71 的示例给出 packages/crm/src/ai_briefing.actions.ts —— 一个 hotcrm 没有的仓库布局。而 logic.md 开篇就是「You are the Backend Engineer for HotCRM」：这是按角色分发的 agent 指令文件。一个照着这个示例找「新 action 放哪」的 agent，拿到的是已退休的多包布局的路径，而 docs/archive/README.md 明说归档保留它、当前文档不该用它。

卡片自己判 observation（周围散文与仓库树都指向 src/actions/，读者有另外两个信号），这点公允。但两条把它推过线：

1. 同类已有裁决与先例：.changeset/docs-retired-agent-cube-directories.md 记录了在 src/agents/ 与 src/cubes/ 被删后清掉对它们的引用，并加了一道 docs-drift 仓库树守卫防止复发。同一个类，已经被判过一次值得修 + 值得守。
2. 更有价值的是第二个问题（卡片说得对）：TREE_DOCS 列了 9 个文件，没有一个在 .github/instructions/ 下，而卡片实测：

grep -rn "\.github/instructions\|instructions/" test/ scripts/ package.json   # 0 hits

六个 agent 指令文件坐在本仓所有门禁之外。 这就是它悄悄漂掉的原因，也是它会再漂的原因。

范围：两件事，第二件是重点

1. 把示例路径改成 hotcrm 的真实布局（src/actions/<name>.actions.ts）。
2. 决定 .github/instructions/** 是否加入 docs-drift 的 TREE_DOCS。 ⚠️ 卡片给了一条关键实现注记：现有守卫匹配 src/<x>/ 形式，要抓住 packages/crm/src/ 需要把模式放宽，而不只是加路径。⛔ 只加路径不改模式 = 加了一道抓不到本缺陷的守卫，是本仓反复付账的那种假绿。

⚠️ 落地路径：先解分类问题，⛔ 不要自己猜

governed 面的统一定义是 docs/adr/** + .claude/** + skills/** + AGENTS.md + CLAUDE.md。.github/instructions/** 不在其中 —— 而座位贴把这一点明确记为未决（「⚠️ Open: .github/instructions/** sit outside both」，点名的就是本卡）。

两个事实拉向相反方向：

• 按字面定义，它不是 governed ⇒ 可走合并队列。
• 按 2026-08-18 那条裁决的精神（「任何对 agents.md 等文件的修改」都要人工审核），它是面向 agent 的指令文本，与 AGENTS.md 同族。

⇒ 本卡按保守方向执行：PR 以 draft-only + 人工合并处理（request review os-zhuang，轮次报告列 “awaiting a human merge”）。多付一次人工合并的成本，远小于把一份 agent 指令文件从审核面里漏出去。

⚠️ 分类本身不由本席裁 —— 「.github/instructions/** 算不算 governed」是 governed 面定义的变更，属维护者/skills 席。本轮的轮次报告会把这一问单独列出。

查重

卡片已做且记录在正文（四组搜索，命中的 #1218 / #970 / #1215 / #1209 均无关）。本席未发现同题卡。

Refs #856。

---

Generated by Claude Code

[os-sales]

Claim: PM loop round R28
Session: session_019hUuCQStzXGMFSX4dzww5t
Branch: claude/issue-1233-instructions-layout-drift
Worktree: hotcrm-issue-1233
Domain: repo:hotcrm execution seat (single-lane repo — ⛔ no domain:*)
File surface: .github/instructions/logic.md, test/docs-drift.test.ts (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus (⛔ fable exhausted 2026-09-02, floor opus per the standing exemption)
Clause-②: no
Serial constraints cleared: both files sole occupant; no in-flight PR touches .github/** or test/docs-drift.test.ts. #1494 touches docs/README.md + docs/developers/api_reference.md, which appear inside TREE_DOCS as data — it is pm:queue undispatched, and this card must not rewrite those two files' contents.

Premise re-verified on origin/main @ d3fb7ca: .github/instructions/logic.md:47 and :71 still name packages/crm/src/…; there is no packages/ directory in this repo (real layout is src/actions/, src/hooks/, src/objects/, …). The card's zero-gate finding also re-measured: nothing under test/, scripts/ or package.json references .github/instructions/.

⚠️ Landing path is the conservative one already ruled on this card (2026-08-25 grading): draft-only + human merge, ⛔ not the merge queue. The classification question — whether .github/instructions/** is a governed surface — is not this seat's to rule; it goes in the round report as an open item for the maintainer / skills seat.

---

Generated by Claude Code

[os-sales]

Dev claim (os-dev subagent, separate from the PM claim above)

Session: session_019hUuCQStzXGMFSX4dzww5t
Branch: claude/issue-1233-instructions-layout-drift (pushed, empty, before first edit)
Worktree: hotcrm-issue-1233, base origin/main @ d3fb7ca
Assignee: untouched (PM owns it)

Note on identity: this seat runs as a subagent inside the PM's session, so the session id above is identical to the PM's. The distinguishing identity bit for this claim is the branch, not the session id.

Premise re-verified on origin/main @ d3fb7ca:

• .github/instructions/logic.md:47 and :71 both name packages/crm/src/... — confirmed, two hits, not one.
• No packages/ directory exists. Top-level dirs: apps assets content docs e2e scripts src test.
• Nothing under test/, scripts/ or package.json references .github/instructions/ — re-measured, still 0 hits.

Two premise corrections found while verifying, both reported to the PM:

1. The guard has moved. TREE_DOCS is no longer in test/docs-drift.test.ts — PR test/docs-drift.test.ts is at 97.8% of the 100KB hygiene cap — the next rule added to it turns the gate red #1196 split that file by family, and the repo-tree path family now lives in test/docs-src-tree-paths.test.ts. The guard work lands there.
2. Hooks do not live in src/hooks/. src/hooks/index.ts is a barrel; the 17 real *.hook.ts files live in src/objects/. So logic.md:47 retargets to src/objects/opportunity.hook.ts (a file that exists), not src/hooks/.

Landing path followed as ruled on 2026-08-25: draft PR, human merge, not the merge queue. The governed-surface classification question is not answered here.

Generated by Claude Code

---

Generated by Claude Code

[os-sales]

os-dev-report

{
  "issue": 1233,
  "status": "done",
  "branch": "claude/issue-1233-instructions-layout-drift",
  "head_sha": "d7d54a9",
  "pr": "https://github.com/objectstack-ai/hotcrm/pull/1520",
  "pr_state": "draft, base main, first line `Fixes #1233`, no reviewer requested (left to the dispatching seat per Zone 1)",
  "premise_still_valid": true,
  "sanitizer_truncation_observed": "none. Issue body (3083 chars) and both comments read in full over the REST channel; angle-bracket-shaped text inside backticks survived intact. Read-back of my own claim comment and of the PR body: no loss, no angle-bracket shapes eaten. One cosmetic artefact, not sanitizer: the MCP create/comment path appends its own `_Generated by_` footer, so the footer appears twice on both the claim comment and PR #1520. Not corrected - a PATCH would demote the session-URL footer to bare form.",
  "guard_observed_failing": "YES - observed red before it was accepted, on the committed tree. Mutation: the two paths reverted to `packages/crm/src/...`; confirmed on disk by anchor grep (2 injected, 0 remaining fixed) and by hash divergence (on-disk 4df75933 vs HEAD blob b3ae1a39), not by the editor's exit code. Result: exit 1, `Tests 2 failed | 26 passed (28)`. Restore: `git checkout HEAD -- ABSOLUTE_PATH`, hash back to b3ae1a39, `git diff HEAD` empty, re-run exit 0, 28 passed. Script carried `trap restore EXIT INT TERM` with an absolute REPO_ROOT. No build leg exists to fake - the test reads the briefs as text, no dist resolution.",
  "files_changed": [
    ".github/instructions/logic.md (2 lines: 47, 71)",
    "test/docs-src-tree-paths.test.ts (+167, the new guard)",
    "test/docs-drift.test.ts (SPLIT BY FAMILY pointer table, 1 entry rewrapped to 3 lines)",
    ".changeset/instructions-layout-drift-guard.md (new, empty frontmatter)"
  ],
  "gates": {
    "command": "pnpm verify",
    "sha": "d7d54a9 (branch tip; worktree clean, run after the final commit)",
    "exit": 0,
    "stages": "validate ✓ Validation passed (1147ms) | typecheck tsc --noEmit clean | lint objectstack lint | lint:i18n-gate ✓ 0 i18n/missing-* (59 pre-existing lint issues, unaffected) | hygiene ✓ source hygiene clean | hygiene:tokens ✓ source token ratchet clean (business ~83,079/85,000; interaction ~37,534/40,000; total ~134,954/140,000 - scans src/ only, unmoved by this PR) | build objectstack build | test Test Files 156 passed, Tests 3298 passed | 1 skipped",
    "narrowing": "none - the full repo-wide pipeline ran in the foreground, 231s for the test stage"
  },
  "premise_corrections": [
    "The card and the dispatch both point at `TREE_DOCS` in `test/docs-drift.test.ts`. #1196 split that file by family; the repo-tree path family now lives in `test/docs-src-tree-paths.test.ts`. Guard landed there, and the pointer table in docs-drift.test.ts updated.",
    "The dispatch says hooks are at `src/hooks/`. That directory holds only `index.ts`, a re-export barrel; all 17 `*.hook.ts` files live in `src/objects/`. logic.md:47 retargets to `src/objects/opportunity.hook.ts`, which exists.",
    "The card names line 71 only; lines 47 and 71 both carried the prefix. Both fixed (the dispatch had already measured this).",
    "architect.md carries 9 `packages/hr/src/...` lines plus `packages/[name]` on line 46 = 10 distinct `packages/...` strings, not 10 `packages/hr/src/` references."
  ],
  "deviations": [
    "File surface: touched `test/docs-src-tree-paths.test.ts` instead of the declared `test/docs-drift.test.ts` (the guard moved - see premise_corrections), plus a 1-entry comment edit in docs-drift.test.ts to keep its pointer table honest, and the changeset. No other file touched; no other claim held either file.",
    "Changeset chosen over the `skip-changeset` label: empty frontmatter, matching `agents-md-pure-metadata-principles.md` / `dangling-tabs-citations.md`. Durable in-repo record, no label write, no exposure to a label-stripping race.",
    "Duplicate-check channel: repo-scoped REST reads work unauthenticated (200), but `/search/issues` returns 403 without auth. Fell back to one repo-scoped REST list of all 82 open issues + local grep - zero MCP quota, single call, no paging. 2 hits, both expected (#1353 seat note, #1233 itself). No targeted MCP search was needed."
  ],
  "architect_md_verdict": "SAME defect class - the dispatch's out-of-scope read is half right. Lines 11-28 are a hypothetical Recruiting System and are arguably illustrative. Lines 30-37 and 46 are not: the Dependency Management Rules are standing imperatives naming crm/products/finance as layered packages that do not exist, and the MANDATORY Output Format ('Always start your response with the Architecture Plan') heads every plan with `### 📦 Package: packages/[name]` - a path the agent is told to write, same kind as the logic.md comment. The file contradicts itself: the same template fills its rows with bare `src/foo.object.ts`. NOT fixed here and NOT suppressed: filed as #1518, and pinned in PENDING_PACKAGES_REFS under an EQUALITY assertion that goes red in both directions (new offender, or that file cleaned up without the entry removed). Not folded in because the remedy is not a path rewrite - it needs a decision on whether this repo's architect plans in packages at all, and its example routes files to .mask.ts / .workflow.ts / .rls.ts kinds with no directory here, so stripping the prefix trades one absent path for another.",
  "summary": "Corrected both stale `packages/crm/src/` paths in `.github/instructions/logic.md` (hook -> `src/objects/opportunity.hook.ts`, action -> `src/actions/ai_briefing.actions.ts`), each target confirmed against the real tree rather than assumed. Added a two-rule guard over `.github/instructions/**` in `test/docs-src-tree-paths.test.ts`: the `src/DIR/` names-implies-exists check the other docs get, plus a ban on `packages/...` paths keyed on that directory's absence and applied to every brief by directory walk. The pattern had to widen, and the measurement proves it: `inlineSrcDirs()` returns `[]` over the unfixed brief, so the names-implies-exists assertion is GREEN on the defect - appending the path to TREE_DOCS, which has no vacuity guard, would have shipped a check that cannot fail on its own defect.",
  "tests": "pnpm verify on d7d54a9, exit 0, all eight stages green (156 test files, 3298 passed, 1 skipped). Targeted: `pnpm exec vitest run --maxWorkers=2 test/docs-src-tree-paths.test.ts` -> 28 passed, exit 0. Ablation (details in guard_observed_failing): mutated exit 1 with `Tests 2 failed | 26 passed (28)`, the two failures being (a) the packages/ ban naming `.github/instructions/logic.md` as a new offender while `architect.md` sat in the expected set, and (b) the rule-1 VACUITY assertion - `names no src/DIR/ at all ... expected 0 to be greater than 0` - which is the fake-green caught in the act, since the substantive `missing` assertion never ran for want of anything to check. Restored byte-identical (hash b3ae1a39), 28 passed, exit 0.",
  "mcp_calls": "4 (claim comment, create #1518, create PR #1520, this report comment). All reads - issue body, both comments, 82-issue open list, PR read-back, comment read-back - went over the zero-quota REST channel.",
  "open_questions": [
    {
      "question": "Is `.github/instructions/**` formally a governed surface? Explicitly NOT decided here, per Zone 1.",
      "options": [
        "A - add it to the governed-surface list (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, .github/CODEOWNERS), making draft-only + human merge the standing rule rather than a per-card choice",
        "B - leave it ungoverned and keep deciding per card"
      ],
      "recommendation": "Not this seat's to rule - it is a change to the governed-surface definition and belongs to the maintainer / skills seat. Evidence gathered this round that bears on it: these are per-role agent briefs (`logic.md` opens 'You are the Backend Engineer for HotCRM'), they instruct where files go, and until this PR none of the six was covered by any gate."
    },
    {
      "question": "#1518 (architect.md): does hotcrm's architect plan in packages at all?",
      "options": [
        "A - no. Drop the Dependency Management Rules and the `packages/[name]` heading from the mandatory Output Format; remap the worked example onto the real single-package tree",
        "B - yes, because the role designs ObjectStack apps generally rather than only this repo - in which case the file must say so, since it currently reads as a claim about this workspace"
      ],
      "recommendation": "Needs the maintainer, not a dev seat. It changes what an AGENTS.md-class brief tells every future architect agent to emit, and a second decision rides along: the example routes files to `.mask.ts` / `.workflow.ts` / `.rls.ts` kinds that have no directory in this repo, so 'just strip the prefix' is not available."
    }
  ],
  "out_of_scope_findings": [
    "filed as #1518: .github/instructions/architect.md prescribes a packages/ layout in its standing dependency rules and its mandatory Output Format, not only in its worked example - same class as this card, different remedy"
  ],
  "cleanup": "worktree hotcrm-issue-1233 removed without --force after node_modules deletion; tree was clean and d7d54a9 pushed. No background process started, no dev server, no monitor left running."
}

Generated by Claude Code

---

Generated by Claude Code