archgate
diff --git a/‎.archgate/adrs/ARCH-001-command-structure.md‎
Lines changed: 31 additions & 49 deletions b/‎.archgate/adrs/ARCH-001-command-structure.md‎
Lines changed: 31 additions & 49 deletions
@@ -8,15 +8,15 @@ files: ["src/commands/**/*.ts"]
 
 ## Context
 
-The CLI needs a consistent pattern for defining and registering commands. As the command surface grows (init, check, adr, review-context, session-context, upgrade, clean), the registration mechanism must scale without introducing hidden coupling or making the dependency graph opaque.
+The CLI needs a consistent pattern for defining and registering commands. As the command surface grows, the registration mechanism must scale without introducing hidden coupling or making the dependency graph opaque.
 
 **Alternatives considered:**
 
-- **Auto-discovery via `executableDir()`** — Commander.js supports automatic command discovery by scanning a directory for executable files. This eliminates manual imports but hides the dependency graph: adding or removing a command has no type-checked reference, making dead command detection impossible. It also requires each command to be a standalone executable, which prevents in-process testing and forces separate process spawning for every subcommand invocation.
-- **Plugin-based registration** — A plugin system where commands register themselves via a manifest or hook (similar to Oclif or Clipanion). This adds flexibility for third-party extensions but introduces significant complexity for an internal CLI with a known, finite set of commands. The indirection makes it harder to trace which code handles which command.
-- **Single-file command map** — Define all commands in a single file as a map of name-to-handler. Simple but creates a monolithic file that grows with every command, making merge conflicts frequent and readability poor.
+- **Auto-discovery via `executableDir()`** — Commander.js can scan a directory for executables, but that hides the dependency graph (no type-checked reference, so dead commands are undetectable) and forces each command to be a standalone executable, preventing in-process testing.
+- **Plugin-based registration** — Manifest- or hook-based self-registration (Oclif, Clipanion) buys third-party extensibility at the cost of indirection that obscures which code handles which command — overkill for a finite internal command set.
+- **Single-file command map** — One file mapping names to handlers is simple but becomes a monolith that grows with every command, causing frequent merge conflicts and poor readability.
 
-The explicit register pattern strikes the right balance: each command owns its registration logic, the entry point makes all commands visible at a glance, and in-process execution enables straightforward testing without process spawning.
+The explicit register pattern balances these: each command owns its registration, the entry point makes all commands visible at a glance, and in-process execution enables testing without process spawning.
 
 ## Decision
 
@@ -34,20 +34,20 @@ Commands live in src/commands/ and export a register\*Command(program) function.
 
 ### Do
 
-- Export a register\*Command function from each command module
-- Keep commands thin: parse args, call helpers/engine, format output
-- Use src/commands/<name>.ts for top-level commands
-- Use src/commands/<name>/index.ts for command groups with subcommands
-- Import the register function explicitly in src/cli.ts
-- Wrap all async logic in src/cli.ts in an async function main() and call it as main().catch((err) => { logError(String(err)); process.exit(2); }) — this is required for bun build --compile --bytecode compatibility
+- **DO** export a register\*Command function from each command module
+- **DO** keep commands thin: parse args, call helpers/engine, format output
+- **DO** use src/commands/<name>.ts for top-level commands
+- **DO** use src/commands/<name>/index.ts for command groups with subcommands
+- **DO** import the register function explicitly in src/cli.ts
+- **DO** wrap all async logic in src/cli.ts in an async function main() and call it as main().catch((err) => { logError(String(err)); process.exit(2); }) — this is required for bun build --compile --bytecode compatibility
 
 ### Don't
 
-- Don't put business logic in command files — move it to src/engine/, src/helpers/, or src/formats/
-- Don't use executableDir() for command discovery
-- Don't call .parse() in command files — the entry point handles parsing
-- Don't create commands that spawn child processes for subcommand execution
-- Don't use top-level await in src/cli.ts — bun build --compile --bytecode (the binary compiler) rejects it even though bun run and tsc accept it. The symptom is a build-time parse error: "await" can only be used inside an "async" function
+- **DON'T** put business logic in command files — move it to src/engine/, src/helpers/, or src/formats/
+- **DON'T** use executableDir() for command discovery
+- **DON'T** call .parse() in command files — the entry point handles parsing
+- **DON'T** create commands that spawn child processes for subcommand execution
+- **DON'T** use top-level await in src/cli.ts — bun build --compile --bytecode (the binary compiler) rejects it even though bun run and tsc accept it. The symptom is a build-time parse error: "await" can only be used inside an "async" function
 
 ## Implementation Pattern
 
@@ -59,22 +59,17 @@ import type { Command } from "@commander-js/extra-typings";
 import { loadRuleAdrs } from "../engine/loader";
 import { runChecks } from "../engine/runner";
 import { reportConsole, reportJSON, getExitCode } from "../engine/reporter";
-import { logError } from "../helpers/log";
 
 export function registerCheckCommand(program: Command) {
   program
     .command("check")
     .description("Run automated ADR compliance checks")
     .option("--json", "Output results as JSON")
-    .option("--staged", "Only check staged files")
     .action(async (opts) => {
       const adrs = await loadRuleAdrs();
-      const results = await runChecks(adrs, { staged: opts.staged });
-      if (opts.json) {
-        reportJSON(results);
-      } else {
-        reportConsole(results);
-      }
+      const results = await runChecks(adrs);
+      if (opts.json) reportJSON(results);
+      else reportConsole(results);
       process.exit(getExitCode(results));
     });
 }
@@ -84,11 +79,9 @@ export function registerCheckCommand(program: Command) {
 // src/cli.ts — explicit imports make all commands visible
 import { registerCheckCommand } from "./commands/check";
 import { registerInitCommand } from "./commands/init";
-import { registerAdrCommand } from "./commands/adr";
 
 registerInitCommand(program);
 registerCheckCommand(program);
-registerAdrCommand(program);
 ```
 
 ### Bad Example
@@ -97,12 +90,11 @@ registerAdrCommand(program);
 // BAD: business logic inside command file
 export function registerCheckCommand(program: Command) {
   program.command("check").action(async () => {
-    // Business logic should NOT be here
     const files = await glob("src/**/*.ts");
     for (const file of files) {
       const content = await Bun.file(file).text();
       const violations = content.match(/console\.error/g);
-      // ... complex processing ...
+      // ... complex processing that belongs in src/engine/ ...
     }
   });
 }
@@ -117,9 +109,6 @@ bun build --compile --bytecode — the command used to produce standalone binari
 import { logError } from "./helpers/log";
 
 // Synchronous bootstrap checks can remain at top level
-if (!semver.satisfies(Bun.version, ">=1.2.21"))
-  throw new Error("You need to update Bun to version 1.2.21 or higher");
-
 createPathIfNotExists(paths.cacheFolder);
 
 async function main() {
@@ -129,10 +118,7 @@ async function main() {
   registerInitCommand(program);
   // ... register other commands ...
 
-  const updateCheckPromise = checkForUpdatesIfNeeded(packageJson.version);
   await program.parseAsync(process.argv);
-  const notice = await updateCheckPromise;
-  if (notice) console.log(notice);
 }
 
 main().catch((err) => {
@@ -143,11 +129,7 @@ main().catch((err) => {
 
 ```typescript
 // src/cli.ts — BAD: top-level await breaks bun build --compile --bytecode
-createPathIfNotExists(paths.cacheFolder);
-
 await installGit(); // ERROR: "await" can only be used inside an "async" function
-
-const program = new Command().name("archgate").version(packageJson.version);
 await program.parseAsync(process.argv); // also breaks
 ```
 
@@ -158,8 +140,6 @@ await program.parseAsync(process.argv); // also breaks
 import type { Command } from "@commander-js/extra-typings";
 import { registerAdrCreateCommand } from "./create";
 import { registerAdrListCommand } from "./list";
-import { registerAdrShowCommand } from "./show";
-import { registerAdrUpdateCommand } from "./update";
 
 export function registerAdrCommand(program: Command) {
   const adr = program
@@ -168,8 +148,6 @@ export function registerAdrCommand(program: Command) {
 
   registerAdrCreateCommand(adr);
   registerAdrListCommand(adr);
-  registerAdrShowCommand(adr);
-  registerAdrUpdateCommand(adr);
 }
 ```
 
@@ -180,19 +158,23 @@ export function registerAdrCommand(program: Command) {
 - **In-process execution enables testing** — Commands can be tested by calling register\*Command() directly, without spawning subprocesses or mocking executables
 - **Explicit imports make dependencies clear** — Opening src/cli.ts shows every command the CLI supports. No hidden commands loaded at runtime.
 - **Subcommand nesting is straightforward** — Command groups use the same pattern as top-level commands, with an index.ts that composes children
-- **Type-safe registration** — Commander.js @commander-js/extra-typings provides full type inference for options and arguments within each register function
-- **Binary-compatible entry point** — The main() wrapper pattern ensures src/cli.ts compiles cleanly with bun build --compile --bytecode for standalone binary distribution
+- **Type-safe registration** — @commander-js/extra-typings provides full type inference for options and arguments within each register function
+- **Binary-compatible entry point** — The main() wrapper ensures src/cli.ts compiles cleanly with bun build --compile --bytecode for standalone binary distribution
 
 ### Negative
 
-- **Manual import bookkeeping** — Each new command requires adding an import and registration call in src/cli.ts. This is a minor overhead for a CLI with fewer than 15 commands.
-- **No hot-reload of commands** — Adding a new command requires restarting the CLI process. Acceptable for a development tool.
+- **Manual import bookkeeping** — Each new command requires an import and registration call in src/cli.ts. Minor overhead at this command count.
+- **No hot-reload of commands** — Adding a command requires restarting the CLI process. Acceptable for a development tool.
+- **Entry-point indirection** — Because top-level await is forbidden, src/cli.ts carries a main()/.catch() scaffold instead of straight-line bootstrap code.
 
 ### Risks
 
-- **Stale imports when commands are removed** — If a command file is deleted but its import in src/cli.ts is not removed, TypeScript will catch the error at compile time. The bun run typecheck step in the validation pipeline prevents this from reaching production.
-- **Command group index.ts confused with barrels** — The index.ts files in command group directories (e.g., src/commands/adr/index.ts) contain real composition logic, not re-exports. ARCH-004 No Barrel Files explicitly permits index.ts files with logic.
-- **Top-level await regression** — A developer unfamiliar with the --bytecode constraint may introduce top-level await back into src/cli.ts. Mitigation: The bun run build:check step in the validate pipeline catches this immediately — bun run validate will fail locally before the code reaches CI.
+- **Stale imports when commands are removed** — Deleting a command file without removing its import in src/cli.ts leaves a dangling reference.
+  - **Mitigation:** TypeScript catches it at compile time; the bun run typecheck step in the validation pipeline blocks it before production.
+- **Command group index.ts confused with barrels** — The index.ts files in command group directories (e.g., src/commands/adr/index.ts) contain real composition logic, not re-exports.
+  - **Mitigation:** ARCH-004 No Barrel Files explicitly permits index.ts files with logic.
+- **Top-level await regression** — A developer unfamiliar with the --bytecode constraint may reintroduce top-level await in src/cli.ts.
+  - **Mitigation:** The bun run build:check step in the validate pipeline catches it immediately — bun run validate fails locally before the code reaches CI.
 
 ## Compliance and Enforcement