docs(requirements): repoint REQ-0002's three paths — stale the day they were written (#1933)

[os-elon-musk]

Part of #1933 — the implementation half only, per the PM's 2026-09-15 comment on that card.

⚠️ This body carries no issue-closing keyword, deliberately. #1933 is a decision+fix card
and its policy half stays with the maintainer; the merge queue would otherwise take the card
out of the open-issue inbox that half is waiting in. What is still open on #1933 after this lands:
the ruling on what a requirements record frozen at triage owes when it is also an agent's
authoring input — and, standing on that ruling, docs/architecture/module-split-plan.md,
module-split-inventory.json, and the half of the TREE_DOCS roster that #1923 left hand-written
for exactly this reason.

What this corrects

#1924 / PR #1932 judged 246 dead-path sites one at a time and kept these three, on the ground
that a requirements record is frozen at triage. PM review reversed that single site — the only one
of the 246 where PM and the implementing seat disagreed. The reversal rests on a measurement:
freezing protects a statement that was true when written, and these three never were.

Ancestry reading

The checkout is shallow, so a negative ancestry answer would need a control leg. The reading
below needs none: both legs are positive (exit 0 self-proves in any checkout), and the
load-bearing one is a tree lookup at a single commit, which traverses no ancestry at all.

$ git rev-parse --is-shallow-repository
true

Leg A — the move is an ancestor of the commit that authored REQ-0002
$ git merge-base --is-ancestor 36b27dd 9f13c77 ; echo $?
0
$ git merge-base --is-ancestor 9f13c77 HEAD    ; echo $?      # control leg, known-true
0

Leg B — the three cited paths in the record's OWN tree (shallow-immune)
$ git ls-tree --name-only 9f13c77 src/
src/docs   src/marketing   src/revenue   src/sales   src/service

$ git cat-file -e 9f13c77:src/objects                             ; echo $?   -> 128  absent
$ git cat-file -e 9f13c77:src/flows/opportunity-approval.flow.ts  ; echo $?   -> 128  absent
$ git cat-file -e 9f13c77:src/flows/billing-handoff.flow.ts       ; echo $?   -> 128  absent

positive control — same commit, same command, the paths this PR writes instead
$ git cat-file -e 9f13c77:src/sales/objects                                        -> 0
$ git cat-file -e 9f13c77:src/sales/flows/opportunity-approval.flow.ts             -> 0
$ git cat-file -e 9f13c77:src/sales/flows/billing-handoff-closed-won.flow.ts       -> 0
$ git cat-file -e 9f13c77:src/revenue/flows/billing-handoff-contract-activated.flow.ts -> 0

• 36b27dd — refactor(layout): a directory under src/ is a package … (refactor(layout): a directory under src/ is a package — move every authored file into sales / service / revenue / marketing #1910), 2026-09-14T14:07:19Z
• 9f13c77 — docs(architecture): PSA module design, REQ-0002 … (docs(architecture): PSA module design, REQ-0002, and the final ADR-0130 module shape #1906), 2026-09-14T14:36:11Z

⇒ 29 minutes after the layout move, the record was written citing three paths the move had
already removed, while all four correct paths were already sitting in the same tree. Stale the day
they were written — a typo, not a record.

REQ-0001 stays frozen, and this measurement is why. Two positive legs, no negative needed:
git merge-base --is-ancestor 3b72afa 36b27dd answers 0 (the shallow graft root precedes the
move) and git cat-file -e 3b72afa:docs/requirements/0001-agency-tier-lead-tagging.md answers 0
(REQ-0001 was already there). Its src/flows/* at line 20 was true when written and is untouched
here. ⚠️ Note for anyone re-running this: git log --diff-filter=A names 3b72afa as REQ-0001's
adding commit, which is a shallow-boundary artifact, not a fact — the real add is beyond the
graft. The two legs above avoid depending on it.

The three repoints

Cited in REQ-0002	present at 9f13c77?	now reads	present?
src/objects/	no	src/sales/objects/	yes
src/flows/opportunity-approval.flow.ts	no	src/sales/flows/opportunity-approval.flow.ts	yes
src/flows/billing-handoff.flow.ts	no	both successors, below	yes

The prefix is per-file, not uniform: the sales half's four objects (crm_account, crm_contact,
crm_lead, crm_opportunity) and the amount-approval flow are the sales package's, while the
contract-activated hand-off is the revenue package's.

REQ-0003 … REQ-0006 already spell the package-qualified form, so this only brings REQ-0002 into
line with its own siblings.

Why the hand-off citation names two files

src/flows/billing-handoff.flow.ts has no same-named successor — the ADR-0130 move split it
by trigger, so mechanically adding a prefix would have produced a second path naming nothing. The
record cites the file as evidence for the 2026-08-02 ruling that HotCRM models no orders, invoices
or payments, and each half carries that ruling in its own header:

HotCRM owns lead → contract. It does not model Orders, Invoices or Payments (maintainer
decision, 2026-08-02): billing is an external system's job. What the CRM owes that system is a
reliable hand-off, and these two flows are it

So the citation names each half, with what fires it:
src/sales/flows/billing-handoff-closed-won.flow.ts (an opportunity enters closed_won) and
src/revenue/flows/billing-handoff-contract-activated.flow.ts (a contract enters activated).

Verification

pnpm verify — package.json is the single source of truth for that chain and it was run whole,
not narrowed. Run on the final head of this branch, under the shared heavy-verify lock; the exit
code was captured by the lock wrapper, never read through a pipe.

HEAD = ea3735b
os-verify-lock: VERDICT command-exit 0 · held the lock 157s (2m37s) · waited 0s

  ✓ Validation passed (1464ms)            # objectstack validate
  ✓ i18n lint gate: 0 i18n/missing-* issues
  ✓ source hygiene clean
  ✓ source token ratchet clean
  ✓ Build complete (1464ms)               # objectstack build
  Test Files  170 passed (170)
       Tests  3646 passed | 1 skipped (3647)

⚠️ Those seconds are shared-box seconds — the lock excludes other locked runs, not unlocked
sibling work. The verdict, not the duration, is the reading.

Plus a resolution check with both controls, on the working tree: every src/ path the record now
names resolves on disk (4/4), and the two paths it used to name still do not (the checker can
report a miss, so 4/4 is a measurement rather than a vacuous pass).

Changeset

.changeset/req-0002-repoint-the-three-stale-paths.md, empty frontmatter — the sanctioned
"releases nothing" declaration .github/workflows/changeset-check.yml documents, on par with the
skip-changeset label. Rationale: the whole diff is under docs/requirements/ (internal
maintainer documentation) plus the changeset itself. Nothing under src/ or content/docs/ moves,
the package is private: true with no files[], and the built artifact and the published
documentation site are byte-identical to main. This matches the level chosen by the two nearest
precedents — PR #1932 and the commit that created this very record (#1906) both used empty
frontmatter for maintainer-docs-only diffs, while #1921 carried a patch precisely because it
moved content/docs/, the published half.

Acceptance notes

Observations found on the way, none acted on here:

• docs/requirements/TEMPLATE.md line 33 teaches the retired flat layout — the B bullet
  every new requirement record is copied from says "the standard metadata to add/change under
  src/{type}/", one level short of the post-ADR-0130 src/{package}/{type}/. PR docs: keep the record, repoint the pointer — the ADR-0130 dead paths in docs/, scripts/ and the root configs #1932's 246-site
  sweep never reached docs/requirements/ at all (its diff is 8 files, none of them here), so
  this has not been judged by anyone. An author following it writes into a directory that does not
  exist, and a file that never reaches a package barrel is registered by nothing while
  pnpm validate stays at exit 0. Reported for triage rather than repaired here: this PR's file
  surface is one file and three paths, and the template is not a record, so it is not covered by
  the ruling [decision] what does a frozen requirements record owe when it is also an AI's input surface — the same ruling governs three document classes (REQ-0002 half already repaired in #1942) #1933 is waiting on either way.
• Nothing guards docs/requirements/** for dead src/ paths. TREE_DOCS in
  test/docs-src-tree-paths.test.ts does not list this file, which is why the three survived a
  dedicated sweep. Successor named: the policy half of [decision] what does a frozen requirements record owe when it is also an AI's input surface — the same ruling governs three document classes (REQ-0002 half already repaired in #1942) #1933, which [finding] docs-src-tree-paths is green over a Mermaid diagram naming 13 removed directories (inlineSrcDirs needs a trailing slash), and its own failure message instructs the next agent to use five dead paths #1923 left that roster
  hand-written for.
• The crm_opportunity bullet's second line is now 97 characters against the file's ~90 wrap.
  Left unwrapped on purpose so the diff is one line per repoint; no guard measures it.
• docs/architecture/module-split-plan.md and module-split-inventory.json are untouched, as
  directed: both describe the pre-move tree on purpose.

---

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 15, 2026 7:07pm UTC