akili-specs 2.2.2 → 2.4.1

package/.claude/commands/akili-resume.md

@@ -0,0 +1,120 @@
+---
+description: Resume work after a session break by scanning active specs and presenting a multi-spec dashboard briefing.
+---
+
+# Resume AKILI-SPECS Session
+
+Recover context after a session break, accidental close, or when switching between projects. Scans all active specs under `docs/specs/` and presents a dashboard showing where each spec stands.
+
+> **Recommended model tier:** T5 Fast-Cheap. This is a file-scanning and summarization job; a deep reasoning model is not required.
+
+## Usage
+
+```
+/akili-resume
+```
+
+No arguments required. The command scans `docs/specs/` automatically.
+
+## Behavior
+
+### Step 0: Scan Active Specs
+
+1. List all directories under `docs/specs/` (excluding `archive/`).
+2. For each spec directory, read available files to determine current phase:
+   - `proposal.md` exists → proposed
+   - `requirements.md` exists → requirements defined
+   - `design.md` exists → design defined
+   - `tasks.md` exists → tasks defined
+   - `execution.md` exists → in execution or completed
+   - `test-report.md` exists → tested
+   - `validation-report.md` exists → validated
+
+### Step 1: Determine Phase & Progress
+
+For each spec, determine:
+
+- **Current Phase:** PROPOSE → SPECIFY → EXECUTE → TEST → VALIDATE → ARCHIVE
+- **Progress:** Count `[x]` vs total tasks in `tasks.md`
+- **Last Action:** Most recent entry in `execution.md` (if exists)
+- **Blocked:** Any `[~]` tasks or unresolved FAIL findings
+
+### Step 2: Present Dashboard
+
+If **one spec** is active, go directly to the briefing:
+
+```markdown
+📋 Resuming: changes/add-remember-me
+
+Phase: EXECUTION
+Progress: ██████░░ 6/8 tasks done
+
+Last Action:
+  Task 6 PASS — Implementer completed cookie persistence
+
+Blocked: none
+
+Ready to continue? Next eligible task:
+  [ ] Task 7: Add remember-me checkbox to login form
+```
+
+If **multiple specs** are active, present a dashboard:
+
+```markdown
+📋 AKILI Active Specs (3 open)
+
+1. changes/add-remember-me    [EXECUTION]  ██████░░ 6/8 tasks done
+   Last: Task 6 PASS — Implementer completed cookie persistence
+   Blocked: none
+
+2. admin/user-management      [SPECIFY]    ████░░░░ Design approved, tasks pending
+   Last: HITL menu — user approved design, pending task breakdown
+   Blocked: none
+
+3. bugfix/login-redirect      [VALIDATE]   ████████ 4/4 tasks done
+   Last: Validation report — 1 WARN (missing edge case test)
+   Blocked: none
+
+Which spec do you want to resume? (or "all" for full briefing)
+```
+
+### Step 3: Provide Full Briefing (if requested)
+
+If the user selects "all" or if there's only one spec, provide a detailed briefing for each:
+
+1. **Spec Path & Phase**
+2. **Requirements Summary:** Key requirements from `requirements.md`
+3. **Design Decisions:** Major decisions from `design.md`
+4. **Task Status:** Completed, in-progress, blocked, pending
+5. **Execution Trail:** Last 3 entries from `execution.md`
+6. **Test Evidence:** Summary from `test-report.md` (if exists)
+7. **Validation Status:** PASS/WARN/FAIL from `validation-report.md` (if exists)
+8. **Next Actions:** Recommended next step based on current phase
+
+### Step 4: Recommend Next Command
+
+Based on the current phase, recommend the next command:
+
+- PROPOSE → `/akili-specify <spec-path>`
+- SPECIFY → `/akili-execute <spec-path>`
+- EXECUTE → `/akili-execute <spec-path>` (continue next task)
+- TEST → `/akili-test <spec-path>`
+- VALIDATE → `/akili-validate <spec-path>` or `/akili-archive <spec-path>`
+- ARCHIVE → `/akili-archive <spec-path>`
+
+## Output
+
+No files are created or modified. The command outputs a screen summary only.
+
+## When To Run
+
+- After accidentally closing Claude Code, OpenCode, or Antigravity
+- When switching between projects and need to remember where you left off
+- At the start of a new session to get a quick status overview
+- Before planning the next work session to see what's available
+
+## Error Handling
+
+- If `docs/specs/` does not exist, report that the project has no active specs and suggest running `/akili-constitution` or `/akili-propose`.
+- If `docs/specs/` is empty (only `archive/` exists), report that all specs are archived and suggest running `/akili-propose` for new work.
+- If a spec folder exists but has no readable files, report it as an incomplete spec and suggest running `/akili-specify <spec-path>`.

package/CHANGELOG.md

@@ -6,9 +6,30 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 ## [Unreleased]
 
+### Notes
+
+- No unreleased changes yet.
+
+## [2.4.1] - 2026-07-19
+
 ### Fixed
-- Changed the CLI behavior so that running `akili` with no arguments defaults to showing the `help` menu instead of launching the interactive `init` wizard. The wizard must now be explicitly invoked via `akili init` (or `npx akili-specs init`).
+- **`akili update` now updates the npm package:** Previously `akili update` only reinstalled files from the already-installed version. Now it detects the installation type (global, local, or npx), runs `npm install -g akili-specs@latest` or `npm install akili-specs@latest` accordingly, and then reinstalls files with `--force`.
+## [2.4.0] - 2026-07-19
+
+### Added
+- **`/akili-resume` command:** New session recovery command that scans all active specs under `docs/specs/` and presents a multi-spec dashboard with phase, progress bars, last action, blockers, and next command recommendation. If only one spec is active, goes directly to a detailed briefing. No arguments required.
 
+### Fixed
+- **Documentation drift corrections:** Added `/akili-audit` to README (Contents, Command Map, Auxiliary commands), `docs/commands/README.md` (Command Map, Source Files, Normal Sequence), and `docs/README.md` (Quick Flow). Created `docs/commands/akili-audit.md` reference page.
+- **`judgment-day` skill documentation:** Added `judgment-day` to README skills list, AGENTS.md skill usage, and CLAUDE.md skill usage. Created `docs/skills/judgment-day.md` reference page.
+- **Plan document rebranding:** Renamed `docs/plans/2026-05-26-multi-agent-sdd-orchestration-design.md` to `2026-05-26-multi-agent-akili-orchestration-design.md` to align with the v2.0.0 AKILI rebranding.
+## [2.3.0] - 2026-07-19
+
+### Added
+- **Auto-Update Checker:** The `akili` CLI now automatically checks the NPM registry in the background (zero dependencies, 1500ms timeout) to see if a newer version is available. If an update exists, it prominently displays a stylish banner reminding the user to update, ensuring teams always stay on the latest methodology release.
+
+### Fixed
+- Changed the CLI behavior so that running `akili` with no arguments defaults to showing the `help` menu instead of launching the interactive `init` wizard. The wizard must now be explicitly invoked via `akili init` (or `npx akili-specs init`).
 ## [2.2.2] - 2026-07-19
 
 ### Fixed

package/README.md

@@ -71,6 +71,8 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `akili-test.md`
   - `akili-validate.md`
   - `akili-archive.md`
+  - `akili-audit.md`
+  - `akili-resume.md`
   - `akili-seo.md`
 - `.claude/skills/`
   - `angular-developer`
@@ -87,6 +89,7 @@ AKILI-SPECS is a constitution-first, spec-driven methodology for AI-assisted dev
   - `gsap-scrolltrigger`
   - `gsap-timeline`
   - `gsap-utils`
+  - `judgment-day`
   - `nestjs-expert`
   - `product-manager-toolkit`
   - `react-doctor`
@@ -503,6 +506,8 @@ See the full [Command Reference](docs/commands/README.md) for detailed pages per
 | `/akili-test <spec-path>` | Adding or running test evidence | `test-report.md` with requirement-to-test traceability |
 | `/akili-validate <spec-path>` | Checking implementation against the spec | `validation-report.md` with pass, warning, failure, and remediation items |
 | `/akili-archive <spec-path>` | Closing completed work after validation | Archived spec folder under `docs/specs/archive/` with `archive-summary.md`, synced agent guides, CodeGraph re-index reminder |
+| `/akili-audit` | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
+| `/akili-resume` | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | `/akili-seo <site-domain>` | Auditing deployed SEO and Search Console state | `seo-setup-report.md`, `seo-audit-report.md` |
 
 ## How To Choose The Right Depth
@@ -676,6 +681,10 @@ See [OpenSpec Comparison](docs/openspec-comparison.md) for the current AKILI com
 
 ### Auxiliary commands
 
+- `/akili-audit` — Detect and report drift between the project's specifications (PRD, UX/UI Design, TRD) and the actual implementation. Produces `docs/specs/drift-report.md` with a conformance score, categorized discrepancies (High/Medium/Low), a conformance matrix, and recommended remediation paths. Run independently or after major implementation milestones.
+
+- `/akili-resume` — Resume work after a session break by scanning all active specs under `docs/specs/` and presenting a multi-spec dashboard. Shows current phase, progress bars, last action, blockers, and recommends the next command. If only one spec is active, goes directly to a detailed briefing. No arguments required.
+
 - `/akili-seo <site-domain>` — SEO setup & audit via Google Search Console. Verifies a domain through DNS TXT using a service account, adds the property to GSC, then audits index coverage, sitemaps, structured data, search analytics, server-side render, internal linking, and on-page SEO (titles, metas, headings, canonicals, hreflang) using the packaged `seo-audit` skill. Produces `seo-setup-report.md` and `seo-audit-report.md` under `docs/specs/seo/<domain>/`, including a copy-paste implementation prompt for fixing every High-severity finding.
 
   Dependencies bundled with this repo:

package/bin/akili.js

@@ -5,6 +5,8 @@ const os = require("os");
 const path = require("path");
 const { parseArgs } = require("util");
 
+const { execSync } = require("child_process");
+
 const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const SOURCE_CLAUDE = path.join(PACKAGE_ROOT, ".claude");
 const SOURCE_COMMANDS = path.join(SOURCE_CLAUDE, "commands");
@@ -76,7 +78,7 @@ Usage:
 
 Commands:
   install   Install commands, skills, and helper resources
-  update    Reinstall commands, skills, and helper resources
+  update    Update npm package to latest version and reinstall files
   doctor    Check whether expected files are installed
   list      List packaged commands, skills, and helper resources
   help      Show this help
@@ -382,6 +384,52 @@ function installTool(tool, args) {
   return { installed, skipped };
 }
 
+function detectInstallType() {
+  try {
+    const globalList = execSync("npm list -g akili-specs --depth=0 2>/dev/null", { encoding: "utf8" });
+    if (globalList.includes("akili-specs")) return "global";
+  } catch (e) {}
+
+  try {
+    const localList = execSync("npm list akili-specs --depth=0 2>/dev/null", { encoding: "utf8" });
+    if (localList.includes("akili-specs")) return "local";
+  } catch (e) {}
+
+  return "npx";
+}
+
+function runUpdate(args) {
+  const installType = detectInstallType();
+
+  console.log(`\n${colors.cyan}Detected installation type: ${installType}${colors.reset}`);
+
+  if (installType === "npx") {
+    console.log(`\n${colors.yellow}You are running via npx. No persistent installation to update.${colors.reset}`);
+    console.log(`To install globally: ${colors.cyan}npm install -g akili-specs${colors.reset}`);
+    console.log(`To install locally:  ${colors.cyan}npm install akili-specs${colors.reset}`);
+    return;
+  }
+
+  console.log(`\n${colors.yellow}Updating npm package...${colors.reset}`);
+
+  try {
+    if (installType === "global") {
+      execSync("npm install -g akili-specs@latest", { stdio: "inherit" });
+    } else {
+      execSync("npm install akili-specs@latest", { stdio: "inherit" });
+    }
+
+    console.log(`\n${colors.green}npm package updated successfully.${colors.reset}`);
+  } catch (e) {
+    console.error(`\n${colors.red}Failed to update npm package.${colors.reset}`);
+    process.exit(1);
+  }
+
+  console.log(`\n${colors.yellow}Reinstalling files with --force...${colors.reset}`);
+  args.force = true;
+  runInstall(args);
+}
+
 function runInstall(args) {
   let installed = 0;
   let skipped = 0;
@@ -522,6 +570,59 @@ function runDoctor(args) {
 }
 
 const readline = require("readline/promises");
+const https = require("https");
+const { version: currentVersion } = require("../package.json");
+
+function checkForUpdates() {
+  return new Promise((resolve) => {
+    const req = https.get("https://registry.npmjs.org/-/package/akili-specs/dist-tags", { timeout: 1500 }, (res) => {
+      if (res.statusCode !== 200) return resolve();
+      let data = "";
+      res.on("data", (chunk) => (data += chunk));
+      res.on("end", () => {
+        try {
+          const tags = JSON.parse(data);
+          const latestVersion = tags.latest;
+          if (latestVersion && latestVersion !== currentVersion) {
+            // simple semver check
+            const isNewer = latestVersion.localeCompare(currentVersion, undefined, { numeric: true, sensitivity: 'base' }) > 0;
+            if (isNewer) {
+              const border = `╭─────────────────────────────────────────────────────────────╮`;
+              const emptyLine = `│                                                             │`;
+              const msgLine1 = `│   ${colors.yellow}Update available!${colors.reset} ${colors.red}${currentVersion}${colors.reset} → ${colors.green}${latestVersion}${colors.reset}`;
+              const msgLine2 = `│   Run ${colors.cyan}npm install -g akili-specs${colors.reset} to update.`;
+              
+              // Pad to keep the box neat (very rudimentary padding, assumes specific length of colors)
+              // Just manually aligning for aesthetic since console length with escape codes is tricky
+              console.log(`\n${colors.yellow}${border}`);
+              console.log(`${emptyLine}`);
+              // 61 total chars inside. 
+              // "Update available! x.x.x -> y.y.y"
+              const rawStr1 = `   Update available! ${currentVersion} -> ${latestVersion}`;
+              const pad1 = " ".repeat(Math.max(0, 61 - rawStr1.length));
+              console.log(`│   ${colors.yellow}Update available!${colors.reset} ${colors.red}${currentVersion}${colors.reset} → ${colors.green}${latestVersion}${colors.reset}${pad1}│`);
+              
+              const rawStr2 = `   Run npm install -g akili-specs to update.`;
+              const pad2 = " ".repeat(Math.max(0, 61 - rawStr2.length));
+              console.log(`│   Run ${colors.cyan}npm install -g akili-specs${colors.reset} to update.${pad2}│`);
+              console.log(`${emptyLine}`);
+              console.log(`╰─────────────────────────────────────────────────────────────╯${colors.reset}\n`);
+            }
+          }
+          resolve();
+        } catch (e) {
+          resolve();
+        }
+      });
+    });
+
+    req.on("error", () => resolve());
+    req.on("timeout", () => {
+      req.destroy();
+      resolve();
+    });
+  });
+}
 
 async function runInteractiveInit() {
   const rl = readline.createInterface({
@@ -587,6 +688,8 @@ async function runInteractiveInit() {
 }
 
 async function main() {
+  await checkForUpdates();
+  
   const args = getArgs();
   
   if (args.command !== "help" && args.command !== "list" && args.command !== "init") {
@@ -601,9 +704,11 @@ async function main() {
 
   switch (args.command) {
     case "install":
-    case "update":
       runInstall(args);
       break;
+    case "update":
+      runUpdate(args);
+      break;
     case "doctor":
       runDoctor(args);
       break;

package/docs/README.md

@@ -26,6 +26,10 @@ Use this documentation when you want the human-facing reference. The installable
 /akili-archive <spec-path>
 ```
 
+Use `/akili-resume` at the start of any session to see a dashboard of all active specs and where each one stands.
+
+Use `/akili-audit` independently to detect drift between specs and codebase reality at any time.
+
 Use `/akili-seo <site-domain>` independently when you need Google Search Console setup and SEO audit reports.
 
 ## Documentation Map

package/docs/commands/README.md

@@ -13,6 +13,8 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 | [`/akili-test <spec-path>`](akili-test.md) | Proving behavior with test evidence | `test-report.md` |
 | [`/akili-validate <spec-path>`](akili-validate.md) | Auditing conformance before completion | `validation-report.md` |
 | [`/akili-archive <spec-path>`](akili-archive.md) | Closing completed work after validation | Archived spec folder with `archive-summary.md` |
+| [`/akili-audit`](akili-audit.md) | Detecting drift between specs and codebase reality | `docs/specs/drift-report.md` with conformance score and discrepancy matrix |
+| [`/akili-resume`](akili-resume.md) | Resuming work after a session break | Multi-spec dashboard with phase, progress, and next command recommendation |
 | [`/akili-seo <site-domain>`](akili-seo.md) | Setting up GSC ownership and SEO audit evidence | `seo-setup-report.md`, `seo-audit-report.md` |
 
 ## Normal Sequence
@@ -29,6 +31,8 @@ AKILI commands are installed as slash-command prompts for Claude Code and OpenCo
 
 You can skip `/akili-propose` for very small, obvious work. You should not skip validation before archiving unless the user explicitly accepts the risk.
 
+Run `/akili-audit` independently to detect drift between specs and codebase reality at any time.
+
 ## Source Files
 
 | Command | Source |
@@ -40,4 +44,6 @@ You can skip `/akili-propose` for very small, obvious work. You should not skip
 | `/akili-test` | `.claude/commands/akili-test.md` |
 | `/akili-validate` | `.claude/commands/akili-validate.md` |
 | `/akili-archive` | `.claude/commands/akili-archive.md` |
+| `/akili-audit` | `.claude/commands/akili-audit.md` |
+| `/akili-resume` | `.claude/commands/akili-resume.md` |
 | `/akili-seo` | `.claude/commands/akili-seo.md` |

package/docs/commands/akili-audit.md

@@ -0,0 +1,52 @@
+# `/akili-audit`
+
+Detect and report drift between the project's specifications (PRD, UX/UI Design, TRD) and the actual implementation in the codebase.
+
+## Usage
+
+```text
+/akili-audit
+```
+
+## Behavior
+
+The command performs a four-step audit:
+
+1. **Read Project Specifications** — reads `docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`, and any active specs in `docs/specs/`.
+2. **Scan Active Codebase** — extracts API surfaces, database schemas, UI components, modules, and dependencies using CodeGraph (if available) or standard file search.
+3. **Compare Documentation vs. Codebase Reality** — identifies discrepancies across five categories:
+   - Stale Specification (documented but missing in code)
+   - Undocumented Feature (in code but missing from docs)
+   - Visual/Design Token Mismatch
+   - Technical Constraints Violation
+   - Agent Guide Drift
+4. **Write Drift Report** — creates or updates `docs/specs/drift-report.md`.
+
+## Output
+
+```text
+docs/specs/drift-report.md
+```
+
+The report includes:
+
+- **Overall Conformance Score** (percentage)
+- **Executive Summary**
+- **Identified Discrepancies** categorized by priority (High / Medium / Low)
+- **Conformance Matrix** mapping spec sections to code reality
+- **Recommended Next Steps**
+
+## When To Run
+
+- After major implementation milestones
+- Before `/akili-archive` to verify spec alignment
+- When onboarding to an existing project to assess documentation health
+- Periodically to prevent specification rot
+
+## Skills
+
+`systematic-debugging` applies when discrepancies suggest implementation bugs rather than documentation gaps.
+
+## Source
+
+- `.claude/commands/akili-audit.md`

package/docs/commands/akili-resume.md

@@ -0,0 +1,99 @@
+# `/akili-resume`
+
+Resume work after a session break by scanning active specs and presenting a multi-spec dashboard briefing.
+
+## Usage
+
+```text
+/akili-resume
+```
+
+No arguments required. The command scans `docs/specs/` automatically.
+
+## Use When
+
+- After accidentally closing Claude Code, OpenCode, or Antigravity
+- When switching between projects and need to remember where you left off
+- At the start of a new session to get a quick status overview
+- Before planning the next work session to see what's available
+
+## Behavior
+
+The command performs a four-step scan:
+
+1. **Scan Active Specs** — lists all directories under `docs/specs/` (excluding `archive/`)
+2. **Determine Phase & Progress** — for each spec, identifies current phase (PROPOSE → SPECIFY → EXECUTE → TEST → VALIDATE → ARCHIVE), task progress, last action, and blockers
+3. **Present Dashboard** — shows a visual dashboard with progress bars and status for each active spec
+4. **Recommend Next Command** — suggests the next command based on current phase
+
+## Output
+
+No files are created or modified. The command outputs a screen summary only.
+
+### Single Spec
+
+If only one spec is active, goes directly to a detailed briefing:
+
+```text
+📋 Resuming: changes/add-remember-me
+
+Phase: EXECUTION
+Progress: ██████░░ 6/8 tasks done
+
+Last Action:
+  Task 6 PASS — Implementer completed cookie persistence
+
+Blocked: none
+
+Ready to continue? Next eligible task:
+  [ ] Task 7: Add remember-me checkbox to login form
+```
+
+### Multiple Specs
+
+If multiple specs are active, presents a dashboard:
+
+```text
+📋 AKILI Active Specs (3 open)
+
+1. changes/add-remember-me    [EXECUTION]  ██████░░ 6/8 tasks done
+   Last: Task 6 PASS — Implementer completed cookie persistence
+   Blocked: none
+
+2. admin/user-management      [SPECIFY]    ████░░░░ Design approved, tasks pending
+   Last: HITL menu — user approved design, pending task breakdown
+   Blocked: none
+
+3. bugfix/login-redirect      [VALIDATE]   ████████ 4/4 tasks done
+   Last: Validation report — 1 WARN (missing edge case test)
+   Blocked: none
+
+Which spec do you want to resume? (or "all" for full briefing)
+```
+
+## Phase Detection
+
+The command determines current phase by checking which files exist:
+
+- `proposal.md` → PROPOSE
+- `requirements.md` → SPECIFY
+- `tasks.md` → EXECUTE
+- `execution.md` with incomplete tasks → EXECUTE
+- `test-report.md` → TEST
+- `validation-report.md` → VALIDATE
+- All tasks `[x]` and validation PASS → ready for ARCHIVE
+
+## Next Command Recommendations
+
+Based on current phase:
+
+- PROPOSE → `/akili-specify <spec-path>`
+- SPECIFY → `/akili-execute <spec-path>`
+- EXECUTE → `/akili-execute <spec-path>` (continue next task)
+- TEST → `/akili-test <spec-path>`
+- VALIDATE → `/akili-validate <spec-path>` or `/akili-archive <spec-path>`
+- ARCHIVE → `/akili-archive <spec-path>`
+
+## Source
+
+- `.claude/commands/akili-resume.md`

package/docs/skills/judgment-day.md

@@ -0,0 +1,28 @@
+# `judgment-day`
+
+## Purpose
+
+Provides a blind adversarial dual-review framework for design decisions. Two independent "judges" evaluate a design without seeing each other's feedback, then findings are reconciled. Supports up to two scoped fix/re-judgment rounds.
+
+## Use When
+
+- Reviewing design decisions during `/akili-specify` before proceeding to tasks.
+- Evaluating architectural choices that need adversarial scrutiny.
+- When the design phase approval menu offers "Review Design" and the user selects it.
+
+## Core Rules
+
+- Two judges operate independently and cannot see each other's output.
+- Each judge produces structured findings with severity levels.
+- Findings are reconciled after both judges report.
+- A maximum of two fix/re-judgment rounds prevents infinite loops.
+- If judges detect issues that need correction, the user can choose to fix, skip, or re-scope.
+
+## Best Paired Commands
+
+- `/akili-specify` — design phase approval menu includes judgment-day as an explicit review option.
+- `/akili-validate` — when validation reveals design-level concerns that need adversarial review.
+
+## Source
+
+- `../../.claude/skills/judgment-day/SKILL.md`

package/docs/specs/drift-report.md

@@ -0,0 +1,99 @@
+# AKILI Drift Audit Report
+
+- **Date of Audit:** 2026-07-19
+- **Code Graph Used:** Yes (`.codegraph/` exists; config reviewed)
+- **Overall Conformance Score:** 82%
+
+## Executive Summary
+
+This repository (`sdd-jc-methodology`) packages the AKILI-SPECS methodology itself — it is not a project that *uses* AKILI. Therefore, the standard project-level specs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`, `docs/specs/`) do not exist and are not expected.
+
+The audit was adapted to evaluate **internal consistency**: whether the README, AGENTS.md, CLAUDE.md, docs hub, CHANGELOG, and `package.json` accurately describe the actual commands, skills, templates, scripts, and structure present in the repository.
+
+**Key findings:** one fully-implemented command (`/akili-audit`) is missing from all major documentation indexes, one skill (`judgment-day`) is absent from the skills inventory, and a plan document retains a pre-rebranding filename.
+
+## Identified Discrepancies
+
+### :red_circle: High Priority (Breaking/Critical)
+
+- **`/akili-audit` command exists but is undocumented in main references:**
+  The command file `.claude/commands/akili-audit.md` has existed since v0.4.0 and is referenced by `AGENTS.md`, `docs/flow.md`, `docs/model-routing.md`, and the CHANGELOG. However, it is completely absent from every user-facing index:
+  - **Affected Spec File (README):** [README.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/README.md)
+    - Missing from "Contents" section (line ~67-108, command list)
+    - Missing from "Command Map" table (line ~497-506)
+    - Missing from "Start Here" flow (line ~469-479)
+    - Missing from "Auxiliary commands" section (line ~677-684)
+  - **Affected Spec File (docs/commands/README.md):** [docs/commands/README.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/docs/commands/README.md)
+    - Missing from "Command Map" table (line 7-16)
+    - Missing from "Source Files" table (line 34-43)
+    - Missing from "Normal Sequence" flow (line 20-28)
+  - **Affected Spec File (docs/README.md):** [docs/README.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/docs/README.md)
+    - Missing from "Quick Flow" section (line 19-27)
+  - **Missing doc page:** `docs/commands/akili-audit.md` does not exist (every other command has one)
+  - **Remediation:** Add `/akili-audit` to all four indexes above and create `docs/commands/akili-audit.md` following the same format as the other command reference pages.
+
+### :yellow_circle: Medium Priority (Inconsistencies/Gaps)
+
+- **`judgment-day` skill exists but is missing from skills inventory:**
+  The skill `.claude/skills/judgment-day/SKILL.md` has existed since v0.9.0 and is referenced by `/akili-specify` and the README's "Methodology Contract" section. However:
+  - **Affected Spec File (README):** [README.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/README.md)
+    - Missing from "Contents" skills list (line ~76-99)
+  - **Affected Spec File (AGENTS.md):** [AGENTS.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/AGENTS.md)
+    - Not listed in "Skill Usage" section
+  - **Affected Spec File (CLAUDE.md):** [CLAUDE.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/CLAUDE.md)
+    - Not listed in "Skill Usage" section
+  - **Missing doc page:** `docs/skills/judgment-day.md` does not exist
+  - **Remediation:** Add `judgment-day` to the README skills list, AGENTS.md skill usage, CLAUDE.md skill usage, and create `docs/skills/judgment-day.md`.
+
+- **Plan document filename retains pre-rebranding "sdd" name:**
+  - **Affected Code File:** [docs/plans/2026-05-26-multi-agent-sdd-orchestration-design.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/docs/plans/2026-05-26-multi-agent-sdd-orchestration-design.md)
+  - **Affected Spec File (CHANGELOG):** [CHANGELOG.md](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/CHANGELOG.md) line 158 references `docs/plans/2026-05-26-multi-agent-akili-orchestration-design.md`
+  - The v2.0.0 rebranding changed all `/sdd-*` references to `/akili-*`, but this file was not renamed.
+  - **Remediation:** Rename to `2026-05-26-multi-agent-akili-orchestration-design.md` or update the CHANGELOG entry to match the actual filename.
+
+### :green_circle: Low Priority (Style/Cleanups)
+
+- **`.antigravitycli/` directory contains an undocumented UUID-named JSON file:**
+  - **Affected Code File:** [.antigravitycli/a20c06f4-5c78-46f1-9ae8-f79bd4313512.json](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/.antigravitycli/a20c06f4-5c78-46f1-9ae8-f79bd4313512.json)
+  - Not referenced in README, AGENTS.md, CLAUDE.md, or `.gitignore`.
+  - Likely a local artifact from Google Antigravity IDE that should not be committed.
+  - **Remediation:** Add `.antigravitycli/` to `.gitignore` or document its purpose. Remove the UUID file if it is a local artifact.
+
+- **CodeGraph config is over-provisioned for this repository:**
+  - **Affected Code File:** [.codegraph/config.json](file:///Users/jcadavid/Desktop/DEV/Desarrollos/sdd-jc-methodology/.codegraph/config.json)
+  - The `include` array lists 20+ language extensions (TypeScript, Go, Rust, Java, C#, Swift, Kotlin, Dart, etc.) but the repository only contains JavaScript (`bin/akili.js`, `scripts/*.js`) and Python (`scripts/gsc_verify.py`).
+  - Not an error, but unnecessarily broad for the repo's actual content.
+  - **Remediation:** Narrow `include` to `**/*.js`, `**/*.py`, and `**/*.md` for faster indexing.
+
+- **`package.json` `files` field omits release scripts:**
+  - `scripts/release.js` and `scripts/release-status.js` are not in the `files` array.
+  - This is **correct behavior** (they are development-only tools, not needed by end users), but worth noting for completeness.
+  - **Remediation:** No action needed.
+
+## Conformance Matrix
+
+| Spec Section | Code Reality Status | Alignment Status | Notes |
+| :--- | :--- | :--- | :--- |
+| Commands (`.claude/commands/`) | 9 commands exist | Drifted | `/akili-audit` exists but missing from README, docs/commands/README, and docs/README Quick Flow |
+| Skills (`.claude/skills/`) | 25 skills exist | Drifted | `judgment-day` missing from README skills list, AGENTS.md, and CLAUDE.md skill usage sections |
+| Templates (`.claude/templates/`) | 3 templates (leader, implementer, reviewer) | Aligned | All documented correctly in README and docs |
+| CLI (`bin/akili.js`) | Installer exists and works | Aligned | Documented in README, docs/cli.md, and package.json |
+| Scripts (`scripts/`) | 4 scripts exist | Aligned | `release.js`, `release-status.js`, `parse_tests.js`, `gsc_verify.py` all accounted for |
+| Documentation Hub (`docs/`) | Flow, CLI, Commands, Skills, Model Routing, OpenSpec | Drifted | Missing `docs/commands/akili-audit.md` and `docs/skills/judgment-day.md` |
+| Agent Guides (CLAUDE.md + AGENTS.md) | Root guides exist | Drifted | Both reference `/akili-audit` but skill usage sections omit `judgment-day` |
+| Package Metadata (`package.json`) | v2.3.0, files array, scripts | Aligned | `files` array correctly covers all distributable content |
+| CHANGELOG | Comprehensive history | Minor Drift | Plan document filename mismatch (sdd vs akili) |
+| GitHub Actions | `release-status.yml` workflow | Aligned | Matches `npm run release:status` documented in AGENTS.md |
+| CodeGraph Config | `.codegraph/config.json` | Aligned | Functional but over-provisioned |
+
+## Recommended Next Steps
+
+1. **Update README.md** — Add `/akili-audit` to the Contents list, Command Map table, and Auxiliary commands section.
+2. **Update docs/commands/README.md** — Add `/akili-audit` to the Command Map, Normal Sequence, and Source Files tables.
+3. **Create `docs/commands/akili-audit.md`** — Write a command reference page following the format of existing pages (e.g., `akili-seo.md`).
+4. **Update docs/README.md** — Add `/akili-audit` to the Quick Flow section.
+5. **Add `judgment-day` to skills inventories** — README Contents list, AGENTS.md Skill Usage, CLAUDE.md Skill Usage.
+6. **Create `docs/skills/judgment-day.md`** — Write a skill reference page following the format of existing pages.
+7. **Rename or reconcile plan document** — Either rename `2026-05-26-multi-agent-sdd-orchestration-design.md` to use `akili`, or update the CHANGELOG entry.
+8. **Add `.antigravitycli/` to `.gitignore`** — Prevent local IDE artifacts from being committed.
+9. **Optional: Narrow CodeGraph config** — Reduce `include` patterns to match the repo's actual languages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.2.2",
+  "version": "2.4.1",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {