Follow-up from review of #501. Deferred there because narrowing what an ADR guarantees is a normative change, not prose compression.
Both ADRs claim broader enforcement than their companion rules implement. This is the exact drift this repository's governance exists to catch, so it is worth fixing deliberately.
ARCH-015 — describes the wrong discovery mechanism
The ADR frames command discovery in terms of register*Command(program) calls in src/cli.ts. The rule does not inspect src/cli.ts at all; it globs module paths:
const topLevelFiles = await ctx.glob(`${COMMANDS_DIR}/*.ts`);
const groupIndexFiles = await ctx.glob(`${COMMANDS_DIR}/*/index.ts`);So a command registered without a matching module path, or a module never registered, is outside what the check sees. The examples should describe adding/removing a top-level command module, which is what is actually enforced.
ARCH-016 — overstates depth
The ADR says "every subcommand", "every command at every level", and claims deeper children are covered by the parent pattern. The rule is explicitly one level deep — its own comment says so — and globs:
ctx.glob(`${COMMANDS_DIR}/${parentName}/*.ts`),
ctx.glob(`${COMMANDS_DIR}/${parentName}/*/index.ts`),It does not recurse. src/commands/adr/domain/add.ts, list.ts and remove.ts sit three levels deep and are never checked.
This is latent, not currently broken. archgate adr domain is documented in docs/src/content/docs/reference/cli/adr.mdx, and its add/list/remove subcommands are covered under a ### Subcommands heading, so archgate check --adr ARCH-016 passes today. The gap is that this holds by convention rather than by enforcement: a future archgate adr domain <new> can ship undocumented and nothing will fail.
Suggested approach
Either narrow the prose to state that the rules cover top-level command modules and direct subcommands, adding an explicit manual-review requirement for deeper groups — or extend the rules to recurse, and keep the prose. The first is smaller; the second is what the ADRs currently promise.
Whichever is chosen, ARCH-015 and ARCH-016 should land together so the two documentation-accuracy ADRs stay consistent with each other.
Review threads
Both lines fall outside #501's changed hunks — pre-existing content surfaced because the files appeared in that diff.
Follow-up from review of #501. Deferred there because narrowing what an ADR guarantees is a normative change, not prose compression.
Both ADRs claim broader enforcement than their companion rules implement. This is the exact drift this repository's governance exists to catch, so it is worth fixing deliberately.
ARCH-015 — describes the wrong discovery mechanism
The ADR frames command discovery in terms of
register*Command(program)calls insrc/cli.ts. The rule does not inspectsrc/cli.tsat all; it globs module paths:So a command registered without a matching module path, or a module never registered, is outside what the check sees. The examples should describe adding/removing a top-level command module, which is what is actually enforced.
ARCH-016 — overstates depth
The ADR says "every subcommand", "every command at every level", and claims deeper children are covered by the parent pattern. The rule is explicitly one level deep — its own comment says so — and globs:
It does not recurse.
src/commands/adr/domain/add.ts,list.tsandremove.tssit three levels deep and are never checked.This is latent, not currently broken.
archgate adr domainis documented indocs/src/content/docs/reference/cli/adr.mdx, and itsadd/list/removesubcommands are covered under a### Subcommandsheading, soarchgate check --adr ARCH-016passes today. The gap is that this holds by convention rather than by enforcement: a futurearchgate adr domain <new>can ship undocumented and nothing will fail.Suggested approach
Either narrow the prose to state that the rules cover top-level command modules and direct subcommands, adding an explicit manual-review requirement for deeper groups — or extend the rules to recurse, and keep the prose. The first is smaller; the second is what the ADRs currently promise.
Whichever is chosen, ARCH-015 and ARCH-016 should land together so the two documentation-accuracy ADRs stay consistent with each other.
Review threads
Both lines fall outside #501's changed hunks — pre-existing content surfaced because the files appeared in that diff.