@lifeaitools/rdc-skills 0.34.0 → 0.35.0

package/commands/full-analysis.md

@@ -0,0 +1,50 @@
+---
+name: full-analysis
+description: >-
+  Usage `rdc:full-analysis <path> [--diff <ref>]` — runs all seven surfaces
+  (solid-validator, architecture-reviewer, clean-code-analyzer,
+  package-design, pattern-advisor, testing-strategy, and
+  pattern-refactoring-guide on anything the others flag) and merges into
+  one report. The full form/fit/function pass — use before merging a new
+  package or a significant refactor, not for routine edits.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+# full-analysis — Complete Form/Fit/Function Pass
+
+## Order — mechanical first, judgment second, refactor plans last
+
+1. **FORM** — Skill tool, skill: "solid-validator" (path, `--diff`)
+2. **FIT** — Skill tool, skill: "architecture-reviewer" (path, `--diff`) —
+   reuses step 1's `boundaryFindings`, does not re-run the mechanical check.
+3. **FUNCTION** — Skill tool, skill: "testing-strategy" (path)
+4. **Naming/dead-code/complexity** — Skill tool, skill: "clean-code-analyzer"
+5. **Package boundaries** — Skill tool, skill: "package-design"
+6. **Patterns** — Skill tool, skill: "pattern-advisor"
+7. **For every HIGH/CRITICAL finding from steps 1-6** — Skill tool, skill:
+   "pattern-refactoring-guide", one dispatch per finding, producing a
+   concrete plan.
+
+## Report
+
+```
+## Full Analysis — <path>
+### FORM (solid-validator)
+### FIT (architecture-reviewer)
+### FUNCTION (testing-strategy)
+### Clean Code
+### Package Design
+### Pattern Suggestions
+### Refactor Plans (for every high/critical finding above)
+## Verdict: CLEAN / HAS ISSUES
+```
+
+## Rules
+
+- Do not re-run the mechanical boundary check inside step 2 — pass step 1's
+  result through.
+- A CLEAN verdict requires all seven surfaces to report clean, not a
+  majority.

package/commands/get-refactoring-plan.md

@@ -0,0 +1,13 @@
+---
+name: get-refactoring-plan
+description: >-
+  Usage `rdc:get-refactoring-plan <finding>` — turns a solid-validator/
+  architecture-reviewer/pattern-advisor finding into a step-ordered
+  before/after refactor plan. Produces a plan, does not apply it. See
+  skills/pattern-refactoring-guide.
+---
+
+# get-refactoring-plan
+
+Use Skill tool with skill: "pattern-refactoring-guide", passing the finding
+(file:line + source skill) as args.

package/commands/quick-check.md

@@ -0,0 +1,13 @@
+---
+name: quick-check
+description: >-
+  Usage `rdc:quick-check <path>` — fast mechanical-only pass: solid-validator
+  score + boundary check. No dispatched judgment agents. For a tight
+  iteration loop, not a merge gate.
+---
+
+# quick-check
+
+Use Skill tool with skill: "solid-validator", passing the path as args.
+This is the mechanical-only subset — no judgment dispatch, meant to run in
+seconds during active editing. Use `full-analysis` before a merge.

package/commands/recover.md

@@ -0,0 +1,149 @@
+---
+name: recover
+description: >-
+  Usage `rdc:recover [list|start]` — deterministic post-crash recovery: detect, repair (CodeFlow/PM2 only), verify, then find and resume abandoned Claude/Codex worktree-lane sessions.
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` §
+> RDC_TEST Sandbox Contract. Under `$RDC_TEST=1`, Phase 3 (REPAIR) is skipped —
+> echo `[RDC_TEST] skipping CodeFlow/PM2 repair` and proceed. DETECT, DIAGNOSE, VERIFY,
+> and SESSIONS are all read-only probes and run normally.
+
+# rdc:recover — post-crash session recovery
+
+## When to Use
+- After a box crash, terminal-window crash, or unclean shutdown
+- Checking whether any Claude/Codex worktree-lane session was mid-work when it happened
+- Resuming a session that got abandoned, without hunting for its id by hand
+
+## The one thing to understand first
+
+**This is a script, not a hunt.** All the actual logic — crash detection, engine-specific
+liveness, lane classification, self-elevation to a visible window — lives in the project's
+own `scripts/box-recovery.ps1` / `scripts/recover-session.ps1` / `scripts/lib/session-detect.ps1`.
+This skill is a thin, deterministic dispatcher onto those scripts. Do not reimplement any of
+their classification logic here, and do not improvise an alternate repair path if a phase
+fails — report the failure with its exact command + output instead.
+
+**Both scripts self-elevate to a real, persistent, visible terminal window on their own** —
+they detect a non-interactive invocation (`[Console]::IsOutputRedirected`, true when your
+tool call captures/pipes their output) and relaunch themselves via `wt.exe new-tab`, then
+exit immediately. Do NOT manually wrap them in your own `wt.exe` call — just invoke the
+script directly. That used to be the caller's job and got done wrong repeatedly live; it's
+the script's own job now.
+
+## Usage
+
+```
+rdc:recover                # full pipeline — detect, repair, verify, report+offer sessions
+rdc:recover list           # report only — no repair, no launch, no prompt
+rdc:recover start          # skip detect/diagnose/repair/verify — just resume matched sessions
+```
+
+## Subcommands
+
+### `rdc:recover` (no argument) — full pipeline
+
+Resolve the caller's actual project root first (never assume it's this plugin's own repo):
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+pwsh -File "$ROOT/scripts/box-recovery.ps1"
+```
+
+Deterministic, five phases in order — do not skip ahead, do not improvise alternate repair
+commands:
+
+1. **DETECT** — was there actually an unclean shutdown (Kernel-Power Event 41), and is
+   memory/commit charge under pressure right now.
+2. **DIAGNOSE** — is CodeFlow's local gateway (`:3109`) up, is the local PM2 process table
+   empty (nothing resurrected after reboot).
+3. **REPAIR** — owner-sanctioned repair only: `node scripts/codeflow-repair.mjs` for
+   CodeFlow, `pm2 resurrect` for the local PM2 fleet. **Never** auto-starts an app named
+   `rtp` even if it's in the saved PM2 dump — see the script's own header for why. Do not
+   override that by hand-invoking `pm2 start rtp`.
+4. **VERIFY** — `pnpm agent:readiness` must report `ok:true`, plus a live probe of clauth
+   (`:52437/ping`) and CodeFlow (`:3109/health`). Do not report recovery as complete on
+   anything less than a live probe.
+5. **SESSIONS** — reports every worktree lane that was mid-session at crash time and is not
+   live right now (`aborted`), lanes with a crash-window transcript that have already
+   reattached (`✅ Already recovered`), and general stale lanes unrelated to this crash
+   (`orphan`). Prints exact resume commands for everything pending, then offers one
+   interactive prompt to resume some/all of it. A lane whose session engine doesn't match
+   its lane's owning engine (a Claude session in an `x-codex-*` lane, or vice versa) is
+   reported as a `LANE MISMATCH` and is a HARD RULE never launched, under any flag.
+
+Because this launches a real visible window and its own interactive prompt, when running as
+an agent (no human at that window to answer it) do not rely on the bare form to resume
+anything — the window opens, the prompt waits, nothing gets resumed until a human answers
+it. Report that the window is open and stop there. To have the agent itself resume sessions
+non-interactively, use `rdc:recover start` below instead.
+
+### `rdc:recover list` — report only, no repair, no launch, no prompt
+
+Skips the entire detect/diagnose/repair/verify stack entirely. Pure report:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+pwsh -File "$ROOT/scripts/recover-session.ps1" -ListOnly
+```
+
+Add `-All` for the full inventory including `live` and `clean` lanes, not just
+`aborted`/`orphan`.
+
+### `rdc:recover start` — resume, skipping the whole recovery stack
+
+Also skips detect/diagnose/repair/verify — this is the addressable primitive, not the
+crash orchestrator. Since an agent invoking this has no human sitting at the window to
+answer an interactive prompt, always pass `-Launch` explicitly to skip it:
+
+```bash
+ROOT=$(git rev-parse --show-toplevel)
+
+# all matched (aborted + orphan by default; narrow with -Status/-Engine/-Role)
+pwsh -File "$ROOT/scripts/recover-session.ps1" -Launch
+
+# one specific session
+pwsh -File "$ROOT/scripts/recover-session.ps1" -Id <sessionId> -Launch
+```
+
+## After launching, in every subcommand
+
+Tell the user the window is open and to watch/answer it there — do not try to relay live
+phase-by-phase output, you don't have it. If you need to verify the result yourself (e.g.
+to answer a follow-up), read the run-record log the script writes on completion under
+`C:\Dev\.logs\regen-root\<script-name>\<date>\` (newest file), rather than re-running the
+script a second time in your own context.
+
+## Rules
+
+- **Never reimplement the classification logic in this skill.** Engine-specific liveness,
+  crash-window matching, lane-mismatch detection, and orphan/aborted status all live in
+  `scripts/lib/session-detect.ps1` — read it if you need to understand *why* a session was
+  classified a certain way, never re-derive the answer independently.
+- **Lane mismatch is never launched, under any flag or filter.** A Claude session found
+  sitting in a Codex-owned lane (or vice versa) is a HARD RULE violation if resumed there —
+  both scripts already enforce this; do not work around it.
+- **If any phase fails, report exactly what failed and why** (cited command + output) — do
+  not guess a cause or invent a fix outside the script's own repair paths. If CodeFlow
+  repair itself fails, that is CodeFlow's own failure: report it, do not hand-patch
+  `packages/codeflow`.
+- **Do not disrupt what you're trying to recover.** Never restart clauth, CodeFlow, or PM2
+  mid-diagnosis as a troubleshooting step — that can BE the reason a symptom changes.
+- **-AutoRun's launch (if the caller wires this into logon) stays scoped to crash casualties
+  only.** Orphan lanes are reported for visibility but never silently auto-launched on an
+  unrelated crash's recovery run — see `box-recovery.ps1`'s own `$launchSet` handling.
+
+## Verification
+
+The scripts themselves are the source of truth; this skill does not carry its own test
+suite. To verify a change to the underlying scripts, from the caller's project root:
+
+```bash
+pwsh -Command '$e=$null; [System.Management.Automation.Language.Parser]::ParseFile("scripts/box-recovery.ps1", [ref]$null, [ref]$e); if ($e.Count -gt 0) { $e } else { "OK" }'
+pwsh -File scripts/recover-session.ps1 -ListOnly -All -NoSelfElevate
+```

package/commands/review-arch.md

@@ -0,0 +1,12 @@
+---
+name: review-arch
+description: >-
+  Usage `rdc:review-arch <path> [--diff <ref>]` — layering/dependency-
+  direction review, mechanical + judgment (FIT corner). See
+  skills/architecture-reviewer.
+---
+
+# review-arch
+
+Use Skill tool with skill: "architecture-reviewer", passing the path and any
+`--diff` flag as args.

package/commands/review.md

@@ -1,120 +1,19 @@
 ---
 name: review
 description: >-
-  Usage `rdc:review [--unattended]` — tests, typecheck, stale docs, export conflicts across modified packages. Fixes issues found. Use after a build session or before merging to main.
+  Usage `rdc:review [--unattended]` — post-build quality gate: tsc, tests,
+  stale docs, export conflicts, a mandatory pr-review-toolkit:code-reviewer
+  pass, and the form/fit/function gate (solid-validator + architecture-
+  reviewer) across modified packages. See skills/review.
 ---
 
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+# review
 
-> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`).
+Use Skill tool with skill: "review", passing `--unattended` through if given.
 
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
-
-
-# rdc:review — Quality Gate
-
-## When to Use
-- After a build session (especially overnight builds)
-- Before merging development → main/production
-- Project lead asks "review the work", "is everything clean"
-- Before any production deployment
-- Called by `rdc:overnight` after each epic build completes
-
-## Arguments
-- `rdc:review` — interactive review, pauses on issues needing judgment
-- `rdc:review --unattended` — silent mode, auto-fixes everything fixable
-
-## Procedure
-
-1. **Identify modified packages:**
-   ```bash
-   git diff --name-only origin/main...HEAD | grep "^packages/" | cut -d/ -f2 | sort -u
-   ```
-
-2. **Run tests for each modified package:**
-   ```bash
-   cd packages/<name> && npx vitest run 2>&1 | tail -10
-   ```
-   Report: package → test count → pass/fail → new tests added
-
-   **IMPORTANT:** `pnpm build` must NEVER be run (crashes system). Use `npx tsc --noEmit --project <path>/tsconfig.json` for typecheck instead. For packages without tests, typecheck is the verification method. Do NOT run vitest across the entire monorepo — check only modified packages individually.
-
-3. **Check test coverage delta:**
-   ```bash
-   git diff origin/main...HEAD -- packages/*/src/ | grep -c "^+" | head -5
-   git diff origin/main...HEAD -- packages/*/test* packages/*/src/**/*.test.* packages/*/src/**/*.spec.* 2>/dev/null | grep -c "^+" || echo 0
-   ```
-   Flag any package where implementation lines added > 50 but test lines added = 0.
-
-4. **Check for export conflicts:**
-   - Read `packages/*/src/index.ts` for any package with new exports
-   - Look for duplicate export names across the barrel
-   - Verify aliased exports don't shadow each other
-
-5. **Check for TODO/FIXME/HACK:**
-   ```bash
-   grep -rn "TODO\|FIXME\|HACK\|XXX" packages/*/src/ --include="*.ts" --include="*.tsx"
-   ```
-
-6. **Check package versions:**
-   - Any package with significant new code should have a version bump
-   - Compare package.json versions to what's in `docs/SYSTEM-STATE.md`
-
-7. **Check for stale CLAUDE.md:**
-   - If new modules were added to a package, does its CLAUDE.md mention them?
-   - Flag any package where exports grew by >10 lines but CLAUDE.md wasn't updated
-
-8. **Orphan work item audit:**
-   ```sql
-   SELECT id, title, item_type, status, source, created_at::date
-   FROM work_items
-   WHERE parent_id IS NULL
-     AND item_type NOT IN ('epic', 'bug')
-     AND status NOT IN ('done', 'archived')
-   ORDER BY created_at DESC;
-   ```
-   For each orphaned task found:
-   - If it clearly belongs to an open epic → attach it: `UPDATE work_items SET parent_id = '<epic-id>' WHERE id = '<task-id>'`
-   - If unclear → report (interactive) or flag in REVIEW_STATUS (unattended)
-   - Never silently leave orphaned tasks
-
-9. **Verification gate — dispatch the verify agent:**
-   After any fixes land, run the verify gate on every touched package. See `guides/agents/verify.md`.
-   **Iron Law: no CLEAN verdict without fresh evidence.** Quote the vitest + tsc output in the report.
-   If verify fails → do NOT emit CLEAN. Loop back, fix, re-run verify.
-
-10. **Fix issues found:**
-   - Failing tests → fix and commit
-   - Export conflicts → resolve and commit
-   - Missing version bumps → bump and commit
-   - All fixes as separate commits with descriptive messages
-
-   **Judgment calls:**
-   - Interactive: report — don't guess
-   - Unattended: escalate via advisor tool with: error message, surrounding context,
-     two most likely fix paths. Resume with advisor's recommendation.
-     If advisor unavailable: take the most conservative path, flag in status block.
-
-11. **Report:**
-    - Interactive:
-      ```
-      ## Review Results
-      | Package | Tests | Pass/Fail | New Tests | Issues |
-      ## Fixed
-      ## Remaining Issues
-      ## Verdict: CLEAN / HAS ISSUES
-      ```
-    - Unattended: emit status block only:
-      ```
-      REVIEW_STATUS: { verdict: "CLEAN|HAS_ISSUES", packages_checked, tests_passed, tests_failed, new_tests_added, fixes_applied, escalations }
-      ```
-
-## Rules
-- Do NOT run `pnpm build` (crashes system) — vitest only
-- Interactive: fix what you can, flag what needs decision
-- Unattended: fix everything fixable; escalate judgment calls to advisor
-- Each fix is a separate commit (not batched)
-- Always push fixes to origin after committing *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
-- Unattended: NEVER pause for input
+> This file previously carried a full duplicate of the procedure now owned by
+> `skills/review/SKILL.md`. The two drifted — this copy was missing the
+> mandatory code-review gate (step 8b) and the `engineering-behavior.md` read
+> that the other had. One home for the content closes that class of bug
+> permanently rather than requiring the next editor to remember to update
+> both.

package/commands/suggest-patterns.md

@@ -0,0 +1,11 @@
+---
+name: suggest-patterns
+description: >-
+  Usage `rdc:suggest-patterns <path>` — design pattern suggestions,
+  advisory only, "no pattern needed" is a valid verdict. See
+  skills/pattern-advisor.
+---
+
+# suggest-patterns
+
+Use Skill tool with skill: "pattern-advisor", passing the path as args.

package/commands/validate-solid.md

@@ -0,0 +1,11 @@
+---
+name: validate-solid
+description: >-
+  Usage `rdc:validate-solid <path> [--diff <ref>]` — deterministic SOLID +
+  Clean Architecture scoring (FORM corner). See skills/solid-validator.
+---
+
+# validate-solid
+
+Use Skill tool with skill: "solid-validator", passing the path and any
+`--diff`/`--config` flags as args.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -25,9 +25,18 @@
   "bin": {
     "rdc-skills-install": "scripts/install-rdc-skills.js",
     "rdc-skills-self-test": "scripts/self-test.mjs",
-    "rdc-skills-mcp": "bin/rdc-skills-mcp.mjs"
+    "rdc-skills-mcp": "bin/rdc-skills-mcp.mjs",
+    "rdc-solid-score": "scripts/solid-score.mjs",
+    "rdc-clean-code-score": "scripts/clean-code-score.mjs",
+    "rdc-package-metrics": "scripts/package-metrics-cli.mjs",
+    "rdc-architecture-score": "scripts/architecture-score.mjs",
+    "rdc-pattern-score": "scripts/pattern-score.mjs",
+    "rdc-refactoring-score": "scripts/refactoring-score.mjs",
+    "rdc-test-smell-score": "scripts/lib/test-smell-scoring.mjs",
+    "rdc-duplication-score": "scripts/duplication-score.mjs"
   },
   "scripts": {
+    "test:validator": "node --test tests/lib/*.test.mjs",
     "postinstall": "node scripts/postinstall.js",
     "install-rdc-skills": "node scripts/install-rdc-skills.js",
     "uninstall:win": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
@@ -51,6 +60,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "express": "^5.0.0",
+    "tree-sitter-wasms": "^0.1.13",
+    "ts-morph": "^24.0.0",
+    "web-tree-sitter": "^0.24.7",
     "yaml": "^2.9.0",
     "zod": "^3.25.76"
   }

package/scripts/architecture-score.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * architecture-score — mechanical Clean Architecture boundary / dependency-
+ * direction / layer-separation scoring, ported from
+ * github.com/OnSightTeam/architecture-toolkit (MIT) — see
+ * `lib/architecture-scoring.mjs`'s header for the full provenance and what
+ * was deliberately NOT ported (the toolkit's own broken circular-dependency
+ * check).
+ *
+ * Same architecture as `package-metrics-cli.mjs`: this file owns argv
+ * parsing, file discovery, config loading, and output formatting. It does
+ * NOT know what an AST is — `lib/architecture-scoring.mjs` is plain
+ * `node:fs` + regex/path parsing, independent of the ts-morph
+ * `language-plugin.mjs` used by SOLID/clean-code.
+ *
+ * Config (`--config <file>`, YAML) — same loading discipline as
+ * `solid-score.mjs`'s `--config`: an explicitly-passed path that doesn't
+ * exist is an error, not a silent fallback to defaults; an absent flag
+ * legitimately means "use `DEFAULT_LAYERS`."
+ *
+ *   layers:
+ *     - name: Entities
+ *       level: 4
+ *       globs: ["**\/entities/**", "**\/domain/**"]
+ *
+ * Usage:
+ *   node architecture-score.mjs <path> [--config <file>] [--format text|json]
+ *
+ * DETERMINISM (ATF golden-record requirement): file walk order is sorted
+ * (see `walkSourceFiles`), every finding array is emitted in a stable order
+ * (files sorted by relPath, rule keys in a fixed object-literal order,
+ * cycles canonicalized+sorted), no absolute paths in output (every
+ * `location` is scan-root-relative), no timestamps. Verified by running
+ * this CLI twice against the same target and diffing — see the task report
+ * for the actual command and its empty diff.
+ *
+ * Exit code is always 0 — a reporting tool, not a gate (same policy as
+ * `package-metrics-cli.mjs`; nothing asked for a `--fail-on` this round).
+ */
+
+import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+import { walkSourceFiles, architectureScoreAll, DEFAULT_LAYERS } from './lib/architecture-scoring.mjs';
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i !== -1 ? process.argv[i + 1] : fallback;
+}
+
+/**
+ * Bash-tool / MSYS argv can hand this native-Windows process a POSIX-shaped
+ * path — normalize before use. Same fix as solid-score.mjs / clean-code-score.mjs.
+ */
+function normalizePath(p) {
+  const m = /^\/([A-Za-z])\/(.*)$/.exec(p);
+  const windowsShaped = m ? `${m[1].toUpperCase()}:/${m[2]}` : p;
+  const abs = path.resolve(process.cwd(), windowsShaped);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+}
+
+export function loadConfig(configPath) {
+  if (!configPath) return { layers: DEFAULT_LAYERS, configPath: null, configLoaded: false };
+  if (!existsSync(configPath)) throw new Error(`--config ${configPath} does not exist`);
+  const raw = parseYaml(readFileSync(configPath, 'utf8')) ?? {};
+  const layers = raw.layers ?? DEFAULT_LAYERS;
+  return { layers, configPath, configLoaded: true };
+}
+
+function printHelp() {
+  console.error('Usage: node architecture-score.mjs <path> [--config <file>] [--format text|json]');
+  console.error('');
+  console.error('  <path>            file or directory to scan (required)');
+  console.error('  --config <file>   YAML file with a `layers:` section (see lib/architecture-scoring.mjs header). Default: DEFAULT_LAYERS (Entities/UseCases/InterfaceAdapters/Frameworks).');
+  console.error('  --format          text (default) or json');
+}
+
+function printText(output) {
+  for (const r of output.results) {
+    if (r.totalFindings === 0) continue;
+    console.log(`${r.file}  [layer: ${r.layer ?? 'UNCLASSIFIED'}${r.layer ? ` via ${r.layerBasis}` : ''}]  — ${r.totalFindings} finding(s)`);
+    for (const rule of Object.values(r.rules)) {
+      for (const f of rule.findings) {
+        console.log(`  [${rule.ruleId}] [${f.severity}] [${f.confidence}] ${f.detail}`);
+      }
+    }
+  }
+  if (output.circularLayerDependency.findings.length) {
+    console.log('\nCIRCULAR LAYER DEPENDENCIES:');
+    for (const f of output.circularLayerDependency.findings) console.log(`  ${f.location}`);
+  } else {
+    console.log('\nNo circular layer dependencies found.');
+  }
+  if (output.unclassifiedFiles.length) {
+    console.log(`\n${output.unclassifiedFiles.length} file(s) matched no configured layer (path or name-hint) — skipped by every layer-aware rule, not silently passed as any specific layer:`);
+    for (const f of output.unclassifiedFiles) console.log(`  ${f}`);
+  }
+  console.log(`\nLayers in effect: ${output.layers.map((l) => `${l.name}(${l.level})`).join(' > ')}`);
+}
+
+async function main() {
+  const rawTarget = process.argv[2]?.startsWith('--') ? null : process.argv[2];
+  if (!rawTarget) {
+    printHelp();
+    process.exit(1);
+  }
+  const targetPath = normalizePath(rawTarget);
+  const configArg = arg('--config');
+  const format = arg('--format', 'text');
+
+  if (!existsSync(targetPath)) throw new Error(`target path does not exist: ${targetPath}`);
+  const { layers, configPath, configLoaded } = loadConfig(configArg ? normalizePath(configArg) : null);
+
+  const isFile = statSync(targetPath).isFile();
+  const root = isFile ? path.dirname(targetPath) : targetPath;
+  const files = isFile ? [targetPath] : walkSourceFiles(targetPath);
+
+  const scored = architectureScoreAll(files, root, { layers });
+  const output = {
+    results: scored.results,
+    circularLayerDependency: scored.circularLayerDependency,
+    unclassifiedFiles: scored.unclassifiedFiles,
+    layers: scored.layers,
+    config: { configPath, configLoaded, layerRuleCount: layers.length },
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(output, null, 2));
+  } else {
+    printText(output);
+  }
+
+  process.exit(0);
+}
+
+function realFileURL(p) {
+  try {
+    return pathToFileURL(realpathSync(p)).href;
+  } catch {
+    return pathToFileURL(p).href;
+  }
+}
+const isMain = process.argv[1] && import.meta.url === realFileURL(process.argv[1]);
+if (isMain) {
+  main().catch((err) => {
+    console.error(err.stack || String(err));
+    process.exit(2);
+  });
+}
+
+export { normalizePath };