akili-specs 2.12.0 → 2.13.1

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

@@ -37,6 +37,8 @@ Perform codebase analysis (preferring CodeGraph if `.codegraph/` exists, or util
 3. **UI Components & Pages:** Actual directory structure of frontend views, components, and design tokens.
 4. **Key Modules & Dependencies:** Registered packages, external integrations, and package manifest frameworks.
 
+**Delegation Thresholds (scout scan):** Apply the *Delegation Thresholds* from `.agents/leader.md` to this scan — when a single extraction above requires reading **4+ full source files**, delegate it to a scout/Explore subagent per area (API, schema, UI, modules) and judge drift from their conclusions in Step 2. CodeGraph lookups do not count toward the threshold. This keeps the T3 drift-judging context clean of raw file dumps.
+
 ### Step 2: Compare Documentation vs. Codebase Reality
 
 Audit for discrepancies, classifying findings under the following categories:

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

@@ -95,6 +95,8 @@ Also inspect the codebase to understand:
 
 Do not write generic placeholder documentation when the repository already contains enough context to infer a strong baseline.
 
+**Delegation Thresholds (scout research):** For legacy/existing-project analysis, apply the *Delegation Thresholds* from the packaged `leader.md` template — when inspecting the codebase requires reading **4+ full source files** for a single question (architecture survey, styling-token inventory, module-boundary mapping), spawn a scout/Explore subagent with fresh context and synthesize from its conclusions instead of reading everything inline. CodeGraph lookups (below) do not count toward the threshold.
+
 #### Existing Project CodeGraph Check
 
 For existing projects, prefer CodeGraph for repository analysis when available:
@@ -245,7 +247,7 @@ Create or enhance `docs/trd/trd.md` as the technical implementation blueprint.
 
 ### Step 6: Create or Enhance the Infrastructure Document
 
-Create or enhance `docs/infrastructure.md` as the deployment and hosting blueprint.
+Create or enhance `docs/infrastructure.md` as the environments blueprint — from the developer's laptop to PROD.
 
 The infrastructure shape derives from the TRD's robust-vs-lite tier decision (Step 5, `software-architect` skill) — never precedes it. Cite the tier decision and its ADR at the top of the document.
 
@@ -256,9 +258,30 @@ The infrastructure shape derives from the TRD's robust-vs-lite tier decision (St
 3. Deployment Strategy (e.g., CI/CD, Terraform, CDK)
 4. Network & Security Architecture
 5. Infrastructure Rules & Constraints
+6. Local Environment (the contract below)
 
 If this information is missing during the initial setup or discovery phase, explicitly ask the user for the intended infrastructure specifications before drafting this document.
 
+#### Step 6B: The Local Environment Contract
+
+Scaffold a `## Local Environment` section that captures how to start the project's local stack (database, backend, frontend). The methodology defines a **contract, not a tool** — Docker Compose is the recommended primary route, but the contract must always document a fallback for users without Docker:
+
+| Element | What to record |
+|---------|----------------|
+| Primary route (recommended) | e.g. `docker compose up -d` |
+| Fallback route (no Docker) | e.g. `npm run dev` per service + a local or cloud dev database |
+| Pre-check | e.g. `docker info` — on failure (daemon off, not installed), surface it and offer: start Docker, or use the fallback. Never block silently |
+| Seed / reset data | explicit commands |
+| Health check | how to verify the stack is up |
+| URLs / ports | frontend, backend, database |
+
+Mode-specific behavior:
+
+- **Legacy / Active:** derive the contract from evidence — existing `docker-compose*.yml`, `Makefile`, `package.json` scripts, README run instructions. Do not invent commands; ask the user to confirm anything ambiguous.
+- **Brand-new:** offer to scaffold a development compose file (db + backend + frontend) matching the TRD stack. If the user declines or has no Docker, record the native fallback as the primary route.
+
+**Boundary rule (record it in the section):** the local environment is **disposable** — agents may freely start, seed, and reset it to verify work. Deployments to cloud/PROD are **governed** — they follow this document's sections 1–5 (components, IaC, CI/CD defined at constitution time) and are never improvised by agents.
+
 ---
 
 ### Step 7: Create or Enhance General Setup Templates
@@ -300,6 +323,7 @@ The update should explain briefly:
 - Which skills should be used for common work in the project (the `## Skill Map` added in Step 8D)
 - Whether CodeGraph is initialized and how agents should use it for existing-project analysis
 - Which model to switch to per AKILI-SPECS phase (the `## Model Routing` registry added in Step 8C)
+- How to start the local stack: point at the `## Local Environment` contract in `docs/infrastructure.md` (Step 6B) — agents consult it instead of guessing start commands
 
 Preserve the repository's existing `CLAUDE.md` and `AGENTS.md` conventions and extend them.
 

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

@@ -57,6 +57,8 @@ If `.agents/` is missing, run `/akili-constitution` first to scaffold it. Do not
 
 The Leader does not write production code itself unless the rework loop is exhausted and the user has explicitly approved a fallback.
 
+**Delegation Thresholds:** the Leader's inline-vs-delegate boundary is quantified in `.agents/leader.md` → *Delegation Thresholds* (inline only for 1-file checks and puntual verifications; 4+ full-file reads → scout subagent; 2+ non-trivial file writes → Implementer; CodeGraph lookups don't count toward the read threshold). Apply it to your own research inside this command — e.g. investigating a Reviewer FAIL across many files is scout work, not Leader-inline work.
+
 **Communication economy:** load the `caveman` skill and apply its Scope Contract to all transient output in this command — inter-agent messages (Leader ↔ Implementer/Reviewer briefs, reports, feedback relays) at `full`, user-visible progress lines at `lite`. It never applies to `execution.md` audit entries, PR descriptions, HITL summaries, Pivot blockers, or verbatim evidence (Reviewer FAIL reports pass unchanged — the Structured Feedback rule wins).
 
 ---
@@ -131,6 +133,7 @@ loop:
 - Re-read the requirements and scenarios covered by the task.
 - Identify the smallest safe change that satisfies the task.
 - Identify the verification command listed in the task.
+- **Environment-dependent verification:** if the verification needs a running stack (integration behavior, manual smoke, anything hitting the database or a live server), consult the `## Local Environment` contract in `docs/infrastructure.md` and run its **pre-check** now — before spawning the Implementer. If the primary route is unavailable (e.g. the Docker daemon is off), ask the user whether to start it or proceed via the contract's fallback route; pass the resolved start/health-check commands in the Implementer's brief. If no contract exists, note the gap and recommend `/akili-constitution` (Step 6B) after the run.
 
 #### 2.2 — Spawn Implementer
 
@@ -159,9 +162,18 @@ When the Implementer reports completion, the Leader:
    - the relevant slices of `requirements.md`, `design.md`, `trd.md`, and `docs/ux-ui/design.md`
    - the Implementer's verification evidence
 
+**Review lens modes (4R):** the Reviewer audits spec conformance (the gate) plus four advisory lenses — **readability, reliability, resilience, risk** — per `.agents/reviewer.md`. The mode is selected by the task's effort dial; there is no separate configuration:
+
+| Mode | When | Mechanics |
+|------|------|-----------|
+| **Lens checklist** (default) | Effort `low` / `medium` / `high` | The single Reviewer sweeps all four lenses; non-spec-violation findings return in an `ADVISORY` block. **Spec conformance remains the only PASS/FAIL gate** |
+| **Parallel lens reviewers** | Effort `xhigh` / `max`, or the task touches security, migrations, or data-loss surfaces | Spawn 2–4 lens-scoped Reviewers in parallel (each gets the same diff + one named lens + baseline spec conformance). Any lens may FAIL; the Leader adjudicates whether a lens FAIL is in-scope for the task **before** consuming a rework attempt |
+
+`ADVISORY` findings are recorded in `execution.md` with the task's entry and never trigger rework — the 3-attempt ceiling binds to spec conformance only.
+
 The Reviewer is read-only. It must conclude with either:
 
-- **`STATUS: PASS`** + a 1–2 sentence summary
+- **`STATUS: PASS`** + a 1–2 sentence summary (+ optional `ADVISORY` block with 4R lens findings)
 - **`STATUS: FAIL`** + a structured list of issues, each containing:
   1. **Discovered Issue** — what is incorrect or missing
   2. **Violated Rule** — the specific spec document and section violated
@@ -171,6 +183,7 @@ The Reviewer is read-only. It must conclude with either:
 #### 2.4 — Loop Guardrails
 
 - **Maximum Retries:** A hard ceiling of **3 rework attempts** per task. This prevents infinite loops and token waste.
+- **Advisory Never Gates:** `ADVISORY` (4R lens) findings are recorded in `execution.md` but never count as FAIL issues, never trigger rework, and never consume attempts. If an advisory finding is serious enough to block, the Reviewer must restate it as a spec-violation FAIL issue (or the Leader escalates it to the user as a potential spec gap via the Pivot Protocol).
 - **Fail-Fast (FATAL_FAIL):** If the Reviewer issues a `STATUS: FATAL_FAIL`, immediately HALT the loop, mark the task `[~]`, and trigger the Pivot Protocol. Do not consume remaining rework attempts.
 - **Structured Feedback:** On `FAIL`, pass the full Reviewer report unchanged to the next Implementer spawn. Do not paraphrase.
 - **Escalation on HALT:** After 3 failed attempts (or a FATAL_FAIL), mark the task `[~]`, log the full loop history in `execution.md`, and present the audit trail to the user for guidance.
@@ -228,6 +241,7 @@ Each task entry must record:
 - task ID and title
 - number of Implementer attempts run
 - for each attempt: files changed, Implementer verification command + result, Reviewer verdict + summary or full FAIL findings
+- any `ADVISORY` (4R lens) findings from the final Reviewer verdict, labeled as advisory
 - requirements covered
 - decisions made
 - issues encountered

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

@@ -82,6 +82,7 @@ When the spec is a **bug** — the proposal's Document Control says `Type: Bug`,
    - Also read `docs/specs/kaizen-log.md` if it exists — ONLY the `## Active Lessons` table (skip `## Entries`).
 5. Respect the repository's current package layout and naming conventions instead of assuming a fixed stack.
 6. **CodeGraph over full reads:** If `.codegraph/` exists, use `codegraph_search` and `codegraph_context` to inspect relevant code paths instead of reading full source files or using generic `grep`/`glob`. This drastically reduces input tokens.
+7. **Delegation Thresholds (scout research):** Beyond the constitutional docs above, apply the *Delegation Thresholds* from `.agents/leader.md` to source-code exploration in every Explore step of this command — if answering a design question requires reading **4+ full source files**, spawn a scout/Explore subagent with fresh context and consume its conclusions instead of reading the files inline. CodeGraph lookups (rule 6) do not count toward the threshold.
 
 ---
 

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

@@ -100,6 +100,7 @@ The Leader decides the count from the spec's depth and the independence of the s
 
 1. Partition the work into concrete **suites**: backend unit, frontend unit, integration, E2E — only those the spec actually needs.
 2. For each suite, assemble a **context slice**: the target requirements + scenarios, the negative/strict rules to assert, the repo test command, and the relevant skills.
+   - **Integration/E2E suites additionally get the `## Local Environment` contract** from `docs/infrastructure.md` (start, seed/reset, health-check commands and URLs) so Testers never guess how to bring the stack up. Run the contract's **pre-check at planning time** — if the primary route is unavailable (e.g. Docker daemon off), resolve it with the user (start it, or use the fallback route) before spawning suites, not mid-suite. If no contract exists, note the gap in the test report and recommend `/akili-constitution` (Step 6B).
 3. Apply the **Deployment Rule** to decide inline vs delegated, and parallel vs sequential.
 4. **Select each suite's skills as Leader — you own the decision, not a fixed list.** The spec's task skills and the project's `## Skill Map` (root `AGENTS.md`/`CLAUDE.md`) are your **defaults, not a pass-through**: judge each suite's actual nature and augment, narrow, or override them (conditional skills like `systematic-debugging` for failure-heavy suites or `ui-ux-pro-max` for UI-heavy E2E; stack skills come from the Skill Map). When you deviate from the spec's list, record a one-line reason in the test report's Summary.
 5. **Set each suite's effort** (the *Effort dial* in `## Model Routing`, orthogonal to the tier): default `medium` for a T2 Tester, `low` for a trivial single-assertion suite, `xhigh` for complex integration/concurrency suites, `max` for correctness-critical coverage. Where the tool exposes a per-spawn effort knob, set it; otherwise steer depth in the suite's context slice. Never `max` a cheaper tier — escalate the tier instead.

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

@@ -87,6 +87,8 @@ Prefer the commands defined by the repo rather than assuming a fixed stack.
 
 If no command exists, record the gap and recommend the smallest useful command to add.
 
+**Environment boot smoke (optional):** when `docs/infrastructure.md` has a `## Local Environment` contract and the spec's behavior warrants it, boot the stack per the contract (pre-check first; fallback route if the primary is unavailable) and confirm the health check passes. Record boot failure as **FAIL**, a missing contract as a **WARN** gap recommending `/akili-constitution` (Step 6B).
+
 ### Phase 4: Requirement Coverage Verification
 
 For every requirement in `requirements.md`, verify:
@@ -122,6 +124,8 @@ Check for:
 - accessibility and responsive behavior for UI work
 - security and authorization boundaries for protected flows
 
+**4R lens sweep (advisory):** Sweep the implementation through the four execution review lenses — **readability, reliability, resilience, risk** (see `.agents/reviewer.md`). Findings that are not spec violations are reported as **advisory** notes in the validation report (they inform remediation and future specs, but only spec violations drive PASS/WARN/FAIL). Also carry forward any unresolved `ADVISORY` findings recorded in `execution.md` so they surface in the report instead of dying in the audit trail.
+
 ### Phase 6: Design Conformance
 
 Compare the implementation against the module design and the constitutional docs where relevant.
@@ -144,7 +148,7 @@ The report must include:
 4. File Existence
 5. Build Integrity
 6. Requirement Coverage
-7. Linting & Code Quality
+7. Linting & Code Quality (including 4R advisory findings, labeled as advisory)
 8. Design Conformance
 9. Test Evidence Summary
 10. Agent Guide / Constitution Impact

package/.claude/templates/leader.md

@@ -49,6 +49,23 @@ Your sole responsibility is to coordinate execution of an approved spec by orche
 
 ---
 
+## 📏 Delegation Thresholds (inline vs. delegate)
+
+This table is the methodology's single source of truth for when an orchestrating agent works inline versus spawning a subagent. It applies to you in `/akili-execute` and `/akili-test`, and to the orchestrating session in research-heavy commands (`/akili-constitution`, `/akili-specify`, `/akili-audit`). The goal: the orchestrator's context stays clean for judgment — a "mega agent" that reads everything, writes everything, and reviews itself pollutes its own context and lowers quality.
+
+| Situation | Action |
+|-----------|--------|
+| 1 file, a quick check, `git status`, a puntual verification | **Inline** — do it yourself |
+| Research requires reading **4+ full files** | **Spawn a scout** (Explore-type subagent) with fresh context; consume its conclusions, not the file dumps |
+| Writing **2+ non-trivial files** | **Spawn an Implementer** (inside the triad this is always the rule; the threshold makes it explicit outside it) |
+| Tests / builds | **Subagent** (`/akili-test` Deployment Rule governs suite-level inline exceptions) |
+| Review of a diff / PR | **Fresh-context Reviewer**, diff-only input — never review your own work |
+| Multiple writers at once | Only for fully independent tasks (different files/domains); use isolated worktrees where the tool supports them |
+
+**CodeGraph exception:** in codegraph-enabled projects, `codegraph_search` / `codegraph_context` / `codegraph_callers` lookups do **not** count toward the 4-file threshold — targeted graph lookups are precisely how the orchestrator avoids bulk file reads. The threshold counts full-file reads.
+
+---
+
 ## 🔁 Orchestration Sequence (per task)
 
 1. Load spec and constitution context.

package/.claude/templates/reviewer.md

@@ -21,6 +21,14 @@ Your sole responsibility is to perform an independent, objective audit of the gi
 3.  **Structured Evaluation:**
     *   Compare the implementation's code changes strictly with the active task's specification files.
     *   Ensure all automated verification checks run by the Implementer are valid and passed cleanly.
+4.  **4R Review Lenses (advisory layer):**
+    *   After the spec-conformance audit, sweep the diff through four lenses:
+        *   **Readability** — can the next maintainer follow this without reconstructing the author's head? Naming, structure, idiom match with the surrounding code.
+        *   **Reliability** — error paths, edge cases, unhandled rejections, resource cleanup.
+        *   **Resilience** — behavior under partial failure: timeouts, retries, bad input, concurrent access.
+        *   **Risk** — security exposure, data loss potential, migration hazards, blast radius of a mistake.
+    *   **Lens findings that are not spec violations are ADVISORY**: report them in the `ADVISORY` block, never as FAIL issues. They inform the Leader and land in `execution.md`; they do not gate the task and never consume a rework attempt. A lens finding that *is* a spec violation (e.g. the TRD mandates an error-handling pattern the diff ignores) belongs in the FAIL issues list as usual.
+    *   When the Leader spawns you with a **single named lens** (parallel lens-review mode, high-effort tasks), audit only that lens plus baseline spec conformance, and say so in your summary.
 
 ---
 
@@ -33,6 +41,8 @@ If the code completely matches the spec, has zero drift, and passes all tests:
 ```text
 STATUS: PASS
 SUMMARY: (Brief 1-2 sentence description of why it passes)
+ADVISORY: (Optional — 4R lens findings that are worth recording but are not spec violations.
+Each line: LENS: finding + suggested improvement. Omit the block when there are none.)
 ```
 
 ### Option B: FAIL
@@ -43,6 +53,8 @@ ISSUES:
 1.  **Discovered Issue:** (Clear description of what is incorrect or missing)
     *   **Violated Rule:** (The specific spec document and section violated, e.g. docs/ux-ui/design.md#L45)
     *   **Remediation Suggestion:** (Actionable explanation of how the Implementer must fix this)
+ADVISORY: (Optional — same format as in PASS. Advisory items are NOT issues: the Implementer
+is not required to address them and the Leader must not count them toward rework.)
 ```
 
 ### Option C: FATAL_FAIL (Fail-Fast)

package/CHANGELOG.md

@@ -10,6 +10,21 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.13.1] - 2026-07-24
+
+### Added
+
+- **Local Environment contract — the constitutional baseline now captures how to start the local stack.** `/akili-constitution` Step 6 evolves `docs/infrastructure.md` from a deployment-only blueprint into an environments blueprint (laptop → PROD): new **Step 6B** scaffolds a `## Local Environment` section as a **contract, not a tool** — Docker Compose as the recommended primary route plus a mandatory no-Docker fallback, a pre-check (e.g. `docker info`; on failure offer to start Docker or use the fallback, never block silently), seed/reset commands, health check, and URLs/ports. Legacy projects derive the contract from evidence (compose files, `package.json` scripts); brand-new projects are offered a dev compose scaffold. The section records the **boundary rule**: the local environment is disposable (agents may start/seed/reset it freely) while cloud/PROD deployments stay governed by the blueprint's components/IaC/CI-CD sections and are never improvised by agents. Consumers: `/akili-execute` Step 2.1 (environment-dependent verification consults the contract and runs the pre-check before spawning the Implementer), `/akili-test` Phase 1 (integration/E2E context slices carry the contract; pre-check resolves at planning time, not mid-suite), `/akili-validate` Phase 3 (optional boot smoke — boot failure FAIL, missing contract WARN), and the Step 8 root guides point agents at the contract. Design recorded in `docs/plans/2026-07-24-local-environment-contract.md`.
+## [2.13.0] - 2026-07-24
+
+### Added
+
+- **Delegation Thresholds — quantified inline-vs-delegate rules for orchestrating agents.** New *Delegation Thresholds* section in the packaged `leader.md` persona (single source of truth): inline only for 1-file checks and puntual verifications; research reading **4+ full files** → spawn a scout/Explore subagent; writing **2+ non-trivial files** → Implementer; tests/builds → subagent; diff review → fresh-context Reviewer; parallel writers only for fully independent tasks. CodeGraph lookups explicitly do **not** count toward the read threshold. Referenced from `/akili-execute` (Leader's own research), `/akili-specify` (Explore steps), `/akili-constitution` (legacy-project analysis), and `/akili-audit` (codebase scan, per-area scouts). Inspired by the convergent `gentle-ai` orchestrator→minion pattern; design recorded in `docs/plans/2026-07-24-delegation-thresholds-review-lenses.md`.
+- **4R execution review lenses (readability, reliability, resilience, risk) — advisory layer on the Reviewer.** The packaged `reviewer.md` persona now sweeps the diff through four lenses after the spec-conformance audit; findings that are not spec violations return in a new `ADVISORY` block that is recorded in `execution.md` but **never gates**: spec conformance remains the only PASS/FAIL gate, and advisory findings never consume rework attempts (new *Advisory Never Gates* guardrail in `/akili-execute`). Mode is selected by the existing effort dial — single Reviewer with lens checklist by default; **parallel lens-scoped Reviewers** at `xhigh`/`max` effort or on security/migration/data-loss surfaces, with the Leader adjudicating lens FAIL scope before consuming an attempt. `/akili-validate` Phase 5 runs the same 4R sweep as advisory report content and carries forward unresolved `ADVISORY` findings from `execution.md`.
+
+### Fixed
+
+- **`akili update` now works for pnpm installations.** The updater previously hardcoded npm: detection probed only `npm list`, so a `pnpm add -g akili-specs` install was misdetected as an ephemeral npx run and told to reinstall with npm (and would have created a duplicate npm-managed copy). `detectInstallType()` now probes both npm and pnpm trees (preferring the manager that invoked the process via `npm_config_user_agent`), the update runs the matching command (`pnpm add -g akili-specs@latest` / local equivalent), and the post-update changelog resolution uses the owning manager's `root`. README and `docs/cli.md` document the pnpm equivalents (`pnpm dlx`, `pnpm add -g` + one-time `pnpm setup`).
 ## [2.12.0] - 2026-07-24
 
 ### Changed

package/README.md

@@ -138,6 +138,8 @@ Run the `init` command to launch the interactive setup wizard, which will ask yo
 npx akili-specs init
 ```
 
+> **Using pnpm?** Every `npx akili-specs …` command in this guide works as `pnpm dlx akili-specs …`. The package lives on the npm registry, which pnpm consumes directly — no extra setup for one-off runs.
+
 **Manual Installation via Flags:**
 
 Install without `--tool` — the installer **auto-detects targets already installed on disk**
@@ -246,6 +248,15 @@ akili install --tool opencode
 akili doctor --tool opencode
 ```
 
+With pnpm (requires a one-time `pnpm setup` so `PNPM_HOME` is on your `PATH`):
+
+```bash
+pnpm add -g akili-specs
+akili install
+```
+
+`akili update` detects which package manager owns the installation (npm or pnpm) and runs the matching update command.
+
 ### Install Paths
 
 Default targets:

package/bin/akili.js

@@ -476,26 +476,41 @@ function installTool(tool, args) {
   return { rootPath, installed, overwritten, skipped, cleaned };
 }
 
+// Package managers to probe, preferring the one that invoked this process
+// (npm/pnpm/yarn set npm_config_user_agent when running bins via npx / pnpm dlx / exec).
+function packageManagerOrder() {
+  const ua = process.env.npm_config_user_agent || "";
+  return ua.startsWith("pnpm") ? ["pnpm", "npm"] : ["npm", "pnpm"];
+}
+
+// Detect how akili-specs is installed: { type: "global" | "local" | "npx", pm: "npm" | "pnpm" }.
+// pnpm keeps its own global tree, so each manager must be probed separately.
 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) {}
+  const managers = packageManagerOrder();
 
-  try {
-    const localList = execSync("npm list akili-specs --depth=0 2>/dev/null", { encoding: "utf8" });
-    if (localList.includes("akili-specs")) return "local";
-  } catch (e) {}
+  for (const pm of managers) {
+    try {
+      const globalList = execSync(`${pm} list -g akili-specs --depth=0 2>/dev/null`, { encoding: "utf8" });
+      if (globalList.includes("akili-specs")) return { type: "global", pm };
+    } catch (e) {}
+  }
 
-  return "npx";
+  for (const pm of managers) {
+    try {
+      const localList = execSync(`${pm} list akili-specs --depth=0 2>/dev/null`, { encoding: "utf8" });
+      if (localList.includes("akili-specs")) return { type: "local", pm };
+    } catch (e) {}
+  }
+
+  return { type: "npx", pm: managers[0] };
 }
 
 // Resolve the installed akili-specs package directory (global or local) after an update.
 // Returns the absolute path to the package root, or null if it cannot be found.
-function resolveInstalledPackageDir(installType) {
+function resolveInstalledPackageDir(install) {
   try {
     const root = execSync(
-      installType === "global" ? "npm root -g 2>/dev/null" : "npm root 2>/dev/null",
+      install.type === "global" ? `${install.pm} root -g 2>/dev/null` : `${install.pm} root 2>/dev/null`,
       { encoding: "utf8" }
     ).trim();
     if (root) {
@@ -592,32 +607,39 @@ function printUpdateChangeSummary(packageDir, fromVersion, toVersion) {
 }
 
 function runUpdate(args) {
-  const installType = detectInstallType();
+  const install = detectInstallType();
 
-  console.log(`\n${colors.cyan}Detected installation type: ${installType}${colors.reset}`);
+  console.log(
+    `\n${colors.cyan}Detected installation type: ${install.type}${install.type === "npx" ? "" : ` (${install.pm})`}${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}`);
+  if (install.type === "npx") {
+    console.log(`\n${colors.yellow}You are running via a package runner (npx / pnpm dlx). No persistent installation to update.${colors.reset}`);
+    console.log(`To install globally: ${colors.cyan}npm install -g akili-specs${colors.reset} or ${colors.cyan}pnpm add -g akili-specs${colors.reset}`);
+    console.log(`To install locally:  ${colors.cyan}npm install akili-specs${colors.reset} or ${colors.cyan}pnpm add akili-specs${colors.reset}`);
     return;
   }
 
   // Capture the version before updating so we can show what changed afterward.
   const versionBefore = currentVersion;
 
-  console.log(`\n${colors.yellow}Updating npm package...${colors.reset}`);
+  console.log(`\n${colors.yellow}Updating package via ${install.pm}...${colors.reset}`);
+
+  const updateCommand =
+    install.pm === "pnpm"
+      ? install.type === "global"
+        ? "pnpm add -g akili-specs@latest"
+        : "pnpm add akili-specs@latest"
+      : install.type === "global"
+        ? "npm install -g akili-specs@latest"
+        : "npm install akili-specs@latest";
 
   try {
-    if (installType === "global") {
-      execSync("npm install -g akili-specs@latest", { stdio: "inherit" });
-    } else {
-      execSync("npm install akili-specs@latest", { stdio: "inherit" });
-    }
+    execSync(updateCommand, { stdio: "inherit" });
 
-    console.log(`\n${colors.green}npm package updated successfully.${colors.reset}`);
+    console.log(`\n${colors.green}Package updated successfully via ${install.pm}.${colors.reset}`);
   } catch (e) {
-    console.error(`\n${colors.red}Failed to update npm package.${colors.reset}`);
+    console.error(`\n${colors.red}Failed to update package (ran: ${updateCommand}).${colors.reset}`);
     process.exit(1);
   }
 
@@ -628,18 +650,19 @@ function runUpdate(args) {
   // After reinstalling, read the freshly installed version and show the changelog
   // between the old and new versions. The running process still has the old code
   // loaded, so we read version + CHANGELOG from the installed package on disk.
-  const packageDir = resolveInstalledPackageDir(installType);
+  const packageDir = resolveInstalledPackageDir(install);
   const versionAfter = packageDir ? readInstalledVersion(packageDir) : null;
   printUpdateChangeSummary(packageDir, versionBefore, versionAfter);
 
   console.log(`\n${colors.cyan}${"─".repeat(56)}${colors.reset}`);
   console.log(`${colors.cyan}Update Summary${colors.reset}`);
+  const installLabel = `${install.type} install via ${install.pm}`;
   if (versionAfter && versionAfter !== versionBefore) {
-    console.log(`  Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installType} install)`);
+    console.log(`  Package: ${versionBefore} → ${colors.green}${versionAfter}${colors.reset} (${installLabel})`);
   } else if (versionAfter) {
-    console.log(`  Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installType} install)`);
+    console.log(`  Package: already up to date at ${colors.green}v${versionAfter}${colors.reset} (${installLabel})`);
   } else {
-    console.log(`  Package: updated from v${versionBefore} (${installType} install; new version could not be read)`);
+    console.log(`  Package: updated from v${versionBefore} (${installLabel}; new version could not be read)`);
   }
   const updatedTools = args.resolvedTools || selectedTools(args);
   console.log(`  Files: reinstalled with --force for ${updatedTools.join(", ")}${args.autoDetected ? " (auto-detected)" : ""} (see Install Summary above)`);

package/docs/cli.md

@@ -42,6 +42,8 @@ npm install -g akili-specs
 akili install --tool all
 ```
 
+pnpm works everywhere npm does: `pnpm dlx akili-specs …` for one-off runs, `pnpm add -g akili-specs` for a global install (after a one-time `pnpm setup`).
+
 To install directly into the local project workspace instead of globally, use the `--local` flag:
 
 ```bash
@@ -54,7 +56,7 @@ akili install --tool both --local
 |---|---|
 | `akili init` | Interactive setup wizard for installation |
 | `akili install` | Install commands, skills, and helper resources |
-| `akili update` | Update the npm package to the latest version, reinstall files, and print a changelog summary of what changed |
+| `akili update` | Update the package to the latest version (via the package manager that owns the install — npm or pnpm), reinstall files, and print a changelog summary of what changed |
 | `akili list` | List packaged commands, skills, and helper resources |
 | `akili doctor` | Check whether expected files are installed |
 | `akili help` | Show help |

package/docs/plans/2026-07-24-delegation-thresholds-review-lenses.md

@@ -0,0 +1,79 @@
+# Proposal: Delegation Thresholds + Execution Review Lenses
+
+**Status:** Implemented (2026-07-24) — shipped in the release following v2.12.0; see `CHANGELOG.md` → Unreleased
+**Date:** 2026-07-24
+**Author:** Leader session (reviewed against `gentle-ai` orchestrator→minion pattern)
+
+Adopt two practices observed in a convergent SDD methodology (`gentle-ai` / `sdd-orchestrator`) that AKILI-SPECS currently lacks: **quantified inline-vs-delegate thresholds** for the orchestrating agent, and **concrete review lenses (4R)** layered onto the execution Reviewer. Both are additive — no existing gate, loop guardrail, or persona contract changes.
+
+## Decision summary
+
+| # | Change | Where it lands | Risk |
+|---|--------|----------------|------|
+| 1 | Delegation Thresholds rule block | `.claude/templates/leader.md`, `/akili-execute`, `/akili-specify`, `/akili-constitution`, `/akili-audit` | Low — codifies existing instinct as numbers |
+| 2 | 4R review lenses (readability, reliability, resilience, risk) | `.claude/templates/reviewer.md`, `/akili-execute` Step 2.3, `/akili-validate` | Low–medium — widens Reviewer scope; mitigated by keeping spec-conformance as the only blocking gate by default |
+
+## 1. Delegation Thresholds
+
+### Problem
+
+The Leader triad in `/akili-execute` always delegates, but the methodology gives no numeric guidance for the orchestrator's *own* work in research-heavy commands (`/akili-constitution`, `/akili-specify`, `/akili-audit`). Today the orchestrating agent reads everything inline, polluting its context — exactly the "mega agente leyendo todo" anti-pattern.
+
+### Proposed rule block
+
+Add a shared **Delegation Thresholds** section (single source of truth in `.claude/templates/leader.md`, referenced — not copied — by the commands):
+
+| Situation | Action |
+|-----------|--------|
+| 1 file, quick check, `git status`, puntual verification | Inline — do it yourself |
+| Research requires reading **4+ files** | Spawn a scout/Explore subagent with fresh context; consume its conclusions, not the file dumps |
+| Writing **2+ non-trivial files** | Spawn an Implementer (already the rule inside `/akili-execute`; now explicit everywhere) |
+| Tests/builds | Subagent (`/akili-test` already complies) |
+| Review of a diff/PR | Fresh-context Reviewer, diff-only input (already the rule; restated here for completeness) |
+| Parallel writers | Only for fully independent tasks; isolated worktrees if the tool supports them (existing Step 1.4 rule, unchanged) |
+
+### Rationale
+
+- Cheap, actionable heuristic: the agent doesn't have to judge "is my context getting big?" — it counts files.
+- CodeGraph note: in codegraph-enabled projects, a `codegraph_context`/`codegraph_search` lookup does **not** count toward the 4-file threshold — that is precisely what the graph is for. The threshold counts full-file reads.
+
+## 2. Execution Review Lenses (4R)
+
+### Problem
+
+The execution Reviewer audits **spec conformance** only. That is stronger than a generic reviewer on traceability, but mono-lens: a diff can pass spec conformance while being unreadable, fragile, or risky. `judgment-day` covers multi-perspective review, but only at design time (`/akili-specify`), not at execution time.
+
+### Proposed design
+
+Two modes, selected by the existing **effort dial** — no new configuration surface:
+
+| Mode | When | Mechanics |
+|------|------|-----------|
+| **Lens checklist** (default) | Effort `low`/`medium`/`high` | The single Reviewer's brief adds a 4R checklist — readability, reliability, resilience, risk — reported as advisory findings. **Spec conformance remains the only PASS/FAIL gate.** 4R findings that are not spec violations go to `execution.md` as `ADVISORY`, never trigger a rework attempt |
+| **Parallel lens reviewers** | Effort `xhigh`/`max`, or task tagged security/migration/data-loss | Spawn 2–4 lens-scoped Reviewers in parallel (each gets the diff + one lens). Any lens may return FAIL; the Leader adjudicates whether a lens FAIL is in-scope for the task before consuming a rework attempt |
+
+### Guardrails (why this won't bloat the loop)
+
+- Advisory findings never consume rework attempts — the 3-attempt ceiling still binds to spec conformance only.
+- Parallel mode is opt-in via the effort dial, which the Leader already sets per task; no default token-cost increase.
+- The Reviewer stays read-only and diff-only; lenses change *what it looks for*, not *what it receives*.
+
+## Out of scope
+
+- No change to `judgment-day` (design-time review is already multi-perspective).
+- No change to the rework loop structure, FATAL_FAIL, or Pivot Protocol.
+- No new agent personas — lenses are briefs, not files.
+
+## Implementation checklist
+
+- [x] Add **Delegation Thresholds** section to `.claude/templates/leader.md` (source of truth).
+- [x] Reference the thresholds from `/akili-execute` (Multi-Agent Triad section), `/akili-specify`, `/akili-constitution`, `/akili-audit` (research steps).
+- [x] Add 4R lens checklist + `ADVISORY` output contract to `.claude/templates/reviewer.md`.
+- [x] Update `/akili-execute` Step 2.3 with the two-mode lens table and effort-dial trigger.
+- [x] Update `/akili-validate` to include 4R advisory reporting in its final audit (Phase 5 sweep + report section 7).
+- [x] `CHANGELOG.md` → `Unreleased` entry (methodology change → next release is **minor**).
+- [ ] Smoke: run `/akili-execute` on a sample spec and confirm ADVISORY findings land in `execution.md` without consuming attempts (pending first real-project run).
+
+## Next step
+
+Live-fire smoke on the next real `/akili-execute` run, then release as part of the next **minor** version.

package/docs/plans/2026-07-24-local-environment-contract.md

@@ -0,0 +1,53 @@
+# Proposal: Local Environment Contract
+
+**Status:** Implemented (2026-07-24) — see `CHANGELOG.md` → Unreleased
+**Date:** 2026-07-24
+**Author:** Leader session
+
+Add a **Local Environment contract** to the constitutional baseline: a tool-agnostic section in `docs/infrastructure.md` that captures how to start the project's local stack (database, backend, frontend) — with Docker Compose as the recommended primary route and a documented no-Docker fallback. Agents (Implementer, Tester, validators) consume the contract instead of guessing start commands from `package.json`.
+
+## Decision summary
+
+| # | Decision | Rationale |
+|---|----------|-----------|
+| 1 | The methodology defines a **contract, not a tool** | Docker Compose is the recommended primary route, but not every user has Docker (or has it running); the contract always documents a fallback |
+| 2 | Lives in `docs/infrastructure.md` as `## Local Environment` | The doc evolves from "deployment blueprint" to "environments blueprint — laptop to PROD"; one home, no new file |
+| 3 | Pre-check before use, never block | `docker info` fails (daemon off / not installed) → tell the user and offer: start Docker, or use the fallback route |
+| 4 | Local is disposable; cloud is governed | Agents may freely start/reset the local environment; deployments to cloud/PROD follow the existing infrastructure blueprint (TRD tier → components → ADR) and are **never improvised by agents** |
+| 5 | No `/akili-deploy` automation for now | Deploys are high-risk; the governed blueprint + checklist yields more than premature automation |
+
+## The contract (scaffolded shape)
+
+| Element | Example |
+|---------|---------|
+| Primary route (recommended) | `docker compose up -d` |
+| Fallback route (no Docker) | `npm run dev` + local Postgres or a cloud dev database |
+| Pre-check | `docker info` — on failure, surface it and use/offer the fallback |
+| Seed / reset data | explicit commands |
+| Health check | how to know the stack is up |
+| URLs / ports | frontend, backend, database |
+
+## Where it lands
+
+| Surface | Change |
+|---------|--------|
+| `/akili-constitution` Step 6 | Scaffold `## Local Environment` into `docs/infrastructure.md`; legacy mode derives it from evidence (existing compose files, `package.json` scripts); brand-new mode offers to scaffold a dev compose file; states the local-vs-cloud boundary rule |
+| `/akili-constitution` Step 8 | Root guides briefly point agents at the contract |
+| `/akili-execute` Step 2.1 | Tasks whose verification needs a running environment consult the contract + run the pre-check before spawning the Implementer |
+| `/akili-test` Phase 1 | Integration/E2E suites get the contract in their context slice; pre-check happens at planning, not mid-suite |
+| `/akili-validate` Phase 3 | Build Integrity may include an environment boot smoke per the contract |
+
+## Out of scope
+
+- No changes to the cloud/PROD sections of `docs/infrastructure.md` (Step 6 structure items 1–5 unchanged).
+- No `/akili-deploy` command.
+- No requirement that projects adopt Docker — the contract is satisfied by any documented primary + fallback pair.
+
+## Implementation checklist
+
+- [x] `/akili-constitution` Step 6: `## Local Environment` scaffold + legacy derivation + dev-compose offer + boundary rule.
+- [x] `/akili-constitution` Step 8: root-guide reference to the contract.
+- [x] `/akili-execute` Step 2.1: consult contract + pre-check for environment-dependent verification.
+- [x] `/akili-test` Phase 1: contract in integration/E2E context slices.
+- [x] `/akili-validate` Phase 3: optional boot smoke.
+- [x] `CHANGELOG.md` → Unreleased.

package/package.json

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