Found during the new-developer first-run journey audit, #10264. This is precisely the "needs knowledge only this monorepo has" failure mode the audit was built to detect.
objectstack.config.ts and src/objects/note.object.ts are the first two files a newcomer opens after scaffolding. Both carry comments pointing at references that do not exist in — and are not linked from — the generated project. Verified by the PM on origin/main:
templates/blank/objectstack.config.ts:15 Protocol compatibility range (ADR-0087 D1): …
templates/blank/objectstack.config.ts:18 scripts/sync-template-versions.mjs.
templates/blank/objectstack.config.ts:22 `automation` backs flow execution and, per ADR-0097, …
templates/blank/objectstack.config.ts:29 Generic connector executors (ADR-0022/0023/0024 + ADR-0097) …
templates/blank/objectstack.config.ts:33 Security (#3055): a declarative `mcp` stdio transport …
templates/blank/src/objects/note.object.ts:25 posture gate (ADR-0090) requires an explicit, authored decision here.
None of docs/adr/**, #3055, or scripts/sync-template-versions.mjs ships in a scaffolded project. A stranger reading // per ADR-0097 has no way to find out what that means, and the comment reads as a reference they are failing to follow rather than as context.
The comments themselves are good — they explain why a setting is the way it is, which is unusually thoughtful for template boilerplate. The problem is only that they address a reader who has the monorepo open. Rewriting them to be self-contained, or pointing at a public docs anchor instead of an internal identifier, keeps the value and drops the dead end.
Suggested landing (hint for triage, not a routing decision)
packages/create-objectstack/src/templates/blank/objectstack.config.ts and …/src/objects/note.object.ts. Worth a sweep of the rest of the template tree for the same pattern rather than fixing only the lines listed above.
Filed by the PM loop from the audit in #10264. Not yet graded or routed.
Found during the new-developer first-run journey audit, #10264. This is precisely the "needs knowledge only this monorepo has" failure mode the audit was built to detect.
objectstack.config.tsandsrc/objects/note.object.tsare the first two files a newcomer opens after scaffolding. Both carry comments pointing at references that do not exist in — and are not linked from — the generated project. Verified by the PM onorigin/main:None of
docs/adr/**,#3055, orscripts/sync-template-versions.mjsships in a scaffolded project. A stranger reading// per ADR-0097has no way to find out what that means, and the comment reads as a reference they are failing to follow rather than as context.The comments themselves are good — they explain why a setting is the way it is, which is unusually thoughtful for template boilerplate. The problem is only that they address a reader who has the monorepo open. Rewriting them to be self-contained, or pointing at a public docs anchor instead of an internal identifier, keeps the value and drops the dead end.
Suggested landing (hint for triage, not a routing decision)
packages/create-objectstack/src/templates/blank/objectstack.config.tsand…/src/objects/note.object.ts. Worth a sweep of the rest of the template tree for the same pattern rather than fixing only the lines listed above.Filed by the PM loop from the audit in #10264. Not yet graded or routed.