antigravity-ai-kit 3.1.0 → 3.2.0

package/.agent/workflows/plan.md

@@ -1,9 +1,9 @@
 ---
 description: Create implementation plan. Invokes planner agent for structured task breakdown.
-version: 2.1.0
+version: 2.2.0
 sdlc-phase: plan
 agents: [planner]
-skills: [plan-writing, brainstorming]
+skills: [plan-writing, brainstorming, plan-validation]
 commit-types: [docs]
 ---
 
@@ -55,14 +55,33 @@ commit-types: [docs]
    - Note dependencies and integration points
 
 3. **Create Plan**
-   - Break down the task into small, focused steps
+   - The loading engine provides `matchedDomains` and `mandatoryRules` — pass these to the planner agent
+   - Consult all mandatory rules (security, testing, coding-style, documentation, git-workflow) using the Rule Extraction Algorithm
+   - Classify task size: Trivial (1-2 files), Medium (3-10 files), Large (10+ files)
+   - Break down the task into right-sized steps with exact file paths (see plan-writing SKILL.md Principle 1)
    - Assign verification criteria to each step
    - Order tasks logically (dependencies first)
+   - Include cross-cutting concerns (security, testing, documentation) — ALWAYS, for ALL task sizes
+   - For Medium/Large tasks: invoke specialist synthesis (security-reviewer, tdd-guide, architect) per the Specialist Invocation Protocol
+   - Include domain-specific sections based on `matchedDomains` (see `domain-enhancers.md`)
    - Identify which agents are needed for multi-domain tasks
    - Save plan to `docs/PLAN-{task-slug}.md`
 
+// turbo
+3.5. **Validate Plan Quality**
+   - The planner performs self-validation using the `plan-validation` skill checklist:
+     1. Classify task size from file count and effort estimate
+     2. Schema compliance: verify all required Tier sections are present and populated
+     3. Cross-cutting verification: Security, Testing, Documentation sections are non-empty (or explicit "N/A — [reason]")
+     4. Specificity audit: every implementation step includes a file path
+     5. Score the plan against the rubric in `plan-schema.md`
+     6. Apply domain scoring: +2 bonus per matched domain with enhancer, -2 penalty per missing
+   - **Verdict**: Score >= 70% of tier max → PASS (present to user with score)
+   - **Revision**: Score < 70% → identify gaps, revise, re-validate (max 2 cycles, then present with warnings)
+   - The quality score is displayed alongside the plan for transparency
+
 4. **Present for Approval**
-   - Show the plan summary to the user
+   - Show the plan summary to the user with quality score
    - Wait for explicit approval before any implementation
 
 ---
@@ -122,20 +141,42 @@ Approve to start implementation with `/create` or `/enhance`.
 
 **REQUIRED:**
 - At least 3 clarifying questions before planning
+- Mandatory rule consultation before plan creation
 - Verification criteria for every task
+- Cross-cutting concerns (security, testing, documentation) in every plan
+- Plan validation against quality schema before presentation
 - User approval before implementation begins
 - Plan file saved in `docs/` with dynamic name
 
 ---
 
+## Post-Implementation Retrospective
+
+After the planned task is fully implemented and verified (reaches VERIFY phase), the `plan-complete` hook triggers a retrospective:
+
+1. **Trigger**: Workflow state transitions to VERIFY (or user runs `/retrospective` on a completed plan)
+2. **Data Source**: Compare `docs/PLAN-{slug}.md` against `git diff --name-only` from plan start
+3. **Execution**: Run the plan-retrospective protocol (`.agent/skills/plan-writing/plan-retrospective.md`)
+4. **Output**: Append one row to `.agent/contexts/plan-quality-log.md`
+5. **Feedback Loop**: Planner reads the quality log at planning time (Step 1, Requirements Analysis) to adjust estimates, predict surprise files, and weight risk categories
+
+This is non-blocking (severity: medium, onFailure: log). If skipped, no impact on current work, but future plan accuracy degrades.
+
+---
+
 ## Completion Criteria
 
 - [ ] Clarifying questions asked and answered
 - [ ] Codebase explored for relevant context
-- [ ] Plan created with verifiable tasks
+- [ ] Mandatory rules consulted (security, testing, coding-style, documentation)
+- [ ] Plan created with verifiable tasks and exact file paths
+- [ ] Cross-cutting concerns addressed (security, testing, documentation)
+- [ ] Plan validated against quality schema (score >= 70% of tier max)
+- [ ] Domain-specific sections included for all matched domains
 - [ ] Plan saved to `docs/PLAN-{slug}.md`
 - [ ] User has reviewed and approved the plan
 - [ ] After approval: proceed to `/create` or `/enhance` for implementation
+- [ ] After implementation: retrospective logged to `plan-quality-log.md` (via plan-complete hook)
 
 ---
 
@@ -144,4 +185,7 @@ Approve to start implementation with `/create` or `/enhance`.
 - **Previous**: `/brainstorm` (explore options) · `/quality-gate` (validate approach)
 - **Next**: `/create` (scaffold new features) · `/enhance` (iterative development)
 - **Skill**: `.agent/skills/plan-writing/SKILL.md`
+- **Schema**: `.agent/skills/plan-writing/plan-schema.md`
+- **Domains**: `.agent/skills/plan-writing/domain-enhancers.md`
+- **Validation**: `.agent/skills/plan-validation/SKILL.md`
 - **Agent**: `planner` agent (see `.agent/agents/planner.md`)

package/README.md

@@ -1,13 +1,13 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-3.1.0-blue)
+![version](https://img.shields.io/badge/version-3.2.0-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![AI Agents](https://img.shields.io/badge/AI%20Agents-19-purple)
-![Skills](https://img.shields.io/badge/Skills-31-orange)
+![Skills](https://img.shields.io/badge/Skills-32-orange)
 ![Commands](https://img.shields.io/badge/Commands-31-red)
 ![Workflows](https://img.shields.io/badge/Workflows-14-teal)
-![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-21-blueviolet)
-![Tests](https://img.shields.io/badge/Tests-261%20passing-brightgreen)
+![Runtime Modules](https://img.shields.io/badge/Runtime%20Modules-29-blueviolet)
+![Tests](https://img.shields.io/badge/Tests-327%20passing-brightgreen)
 ![Checklists](https://img.shields.io/badge/Checklists-3-yellow)
 
 <p align="center">
@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>21-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>31 skills</b>, and <b>14 workflows</b> — all backed by <b>261 tests</b> and governance-first principles.
+  Antigravity AI Kit is a <b>Trust-Grade AI development framework</b> with a <b>29-module runtime engine</b>, <b>19 specialized agents</b>, <b>31 commands</b>, <b>32 skills</b>, and <b>14 workflows</b> — all backed by <b>327 tests</b> and governance-first principles.
 </p>
 
 <p align="center">
@@ -38,8 +38,8 @@
 - [Architecture](#%EF%B8%8F-architecture-overview)
 - [Agents](#-agents-19)
 - [Commands](#%EF%B8%8F-commands-31)
-- [Skills](#%EF%B8%8F-skills-31)
-- [Runtime Engine](#%EF%B8%8F-runtime-engine-21-modules)
+- [Skills](#%EF%B8%8F-skills-32)
+- [Runtime Engine](#%EF%B8%8F-runtime-engine-29-modules)
 - [Workflows](#-workflows-14)
 - [Operating Constraints](#%EF%B8%8F-operating-constraints)
 - [Session Management](#-session-management)
@@ -56,14 +56,14 @@
 | Feature           | Count | Description                                                            |
 | :---------------- | :---- | :--------------------------------------------------------------------- |
 | 🤖 **AI Agents**  | 19    | Specialized roles (Mobile, DevOps, Database, Security, Performance...) |
-| 🛠️ **Skills**     | 31    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
+| 🛠️ **Skills**     | 32    | Domain knowledge modules (API, Testing, MCP, Architecture, Docker...) |
 | ⌨️ **Commands**   | 31    | Slash commands for every development workflow                          |
 | 🔄 **Workflows**  | 14    | Process templates (/create, /debug, /deploy, /test...)                 |
-| ⚙️ **Runtime**    | 21    | Runtime engine modules (governance, reputation, self-healing...)       |
+| ⚙️ **Runtime**    | 29    | Runtime engine modules (governance, reputation, self-healing...)       |
 | ✅ **Checklists** | 3     | Quality gates (session-start, session-end, pre-commit)                 |
 | ⚖️ **Rules**      | 8     | Modular governance constraints (coding, security, testing, git, docs, sprint)  |
-| 🔗 **Hooks**      | 6     | Event-driven automation (runtime + git-hook enforcement)               |
-| 🧪 **Tests**      | 261   | Unit, structural, and security tests (25 test files)                   |
+| 🔗 **Hooks**      | 7     | Event-driven automation (runtime + git-hook enforcement)               |
+| 🧪 **Tests**      | 327   | Unit, structural, integration, and security tests (32 test files)      |
 
 ---
 
@@ -71,7 +71,7 @@
 
 - **🔒 Trust-Grade Governance**: `/explore → /plan → /work → /review` — Each iteration builds context
 - **🤖 Multi-Agent System**: 19 specialized agents that collaborate (Mobile Developer, DevOps, Database Architect, Sprint Orchestrator...)
-- **⚙️ Runtime Engine**: 21 modules enforcing workflow transitions, task governance, agent reputation, self-healing, and marketplace
+- **⚙️ Runtime Engine**: 29 modules enforcing workflow transitions, task governance, agent reputation, self-healing, and marketplace
 - **📦 Context as Artifact**: Persistent markdown files for plans, specs, and decisions
 - **🔄 Continuous Learning**: PAAL cycle extracts patterns from every session
 - **🛡️ Security First**: Built-in secret detection, vulnerability scanning, and compliance checks
@@ -128,47 +128,45 @@ ag-kit scan       # Security scan
 
 ## 🏗️ Architecture Overview
 
-```mermaid
-graph TB
-    subgraph "User Interface Layer"
-        CMD["Slash Commands<br/>31 commands"]
-        WF["Workflows<br/>14 templates"]
-    end
-
-    subgraph "Intelligence Layer"
-        IR[Intelligent Router]
-        WS[Workflow State Machine]
-        CB[Context Budget Engine]
-        LR[Loading Rules]
-    end
-
-    subgraph "Agent Layer"
-        CORE["Core Agents<br/>Planner, Architect, Reviewer"]
-        DOMAIN["Domain Agents<br/>Mobile, Frontend, Backend, DB, DevOps"]
-        SUPPORT["Support Agents<br/>Security, Perf, Docs, Explorer"]
-        AUTO["Autonomy Agents<br/>Sprint Orchestrator, Reliability Engineer"]
-    end
-
-    subgraph "Skill Layer"
-        ORCH["Orchestration Skills<br/>Routing, Parallel, Modes"]
-        OPER["Operational Skills<br/>Verification, Learning, Budget"]
-        DOM["Domain Skills<br/>API, Arch, Testing, Security, MCP"]
-    end
-
-    subgraph "Governance Layer"
-        RULES["rules.md<br/>Immutable Constraints"]
-        HOOKS["hooks.json<br/>6 Event Hooks"]
-        MANIFEST["manifest.json<br/>Integrity Verification"]
-    end
-
-    CMD --> IR
-    WF --> WS
-    IR --> CORE & DOMAIN & SUPPORT & AUTO
-    WS --> IR
-    CB --> LR
-    LR --> IR
-    CORE & DOMAIN & SUPPORT & AUTO --> ORCH & OPER & DOM
-    ORCH & OPER & DOM --> RULES & HOOKS & MANIFEST
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                    USER INTERFACE LAYER                              │
+│  ┌─────────────────────────┐  ┌─────────────────────────┐          │
+│  │  Slash Commands (31)    │  │  Workflows (14)         │          │
+│  └────────────┬────────────┘  └────────────┬────────────┘          │
+├───────────────┼────────────────────────────┼────────────────────────┤
+│               ▼         INTELLIGENCE LAYER ▼                        │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
+│  │ Intelligent      │  │ Workflow State   │  │ Context Budget   │  │
+│  │ Router           │  │ Machine          │  │ Engine           │  │
+│  └────────┬─────────┘  └──────────────────┘  └──────────────────┘  │
+├───────────┼────────────────────────────────────────────────────────-┤
+│           ▼              AGENT LAYER (19)                            │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
+│  │ Core Agents      │  │ Domain Agents    │  │ Support Agents   │  │
+│  │ Planner          │  │ Mobile Dev       │  │ Security         │  │
+│  │ Architect        │  │ Frontend         │  │ Performance      │  │
+│  │ Code Reviewer    │  │ Backend          │  │ Docs, Explorer   │  │
+│  │ TDD Specialist   │  │ DB, DevOps       │  │ Knowledge        │  │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
+├───────────┼─────────────────────┼─────────────────────┼────────────┤
+│           ▼              SKILL LAYER (32)              ▼            │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
+│  │ Orchestration    │  │ Operational      │  │ Domain Skills    │  │
+│  │ Routing, Modes   │  │ Verification     │  │ API, Testing     │  │
+│  │ Parallel Agents  │  │ Learning, Budget │  │ Security, MCP    │  │
+│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
+├───────────┼─────────────────────┼─────────────────────┼────────────┤
+│           ▼           GOVERNANCE LAYER                 ▼            │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
+│  │ rules/ (8)       │  │ hooks.json       │  │ manifest.json    │  │
+│  │ Governance       │  │ 7 Event Hooks    │  │ Integrity Check  │  │
+│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
+├─────────────────────────────────────────────────────────────────────┤
+│                    RUNTIME ENGINE (29 modules)                      │
+│  workflow-engine · session-manager · task-governance                │
+│  agent-reputation · self-healing · marketplace · + 15 more         │
+└─────────────────────────────────────────────────────────────────────┘
 ```
 
 ### How It Works: The Autonomy Engine
@@ -188,7 +186,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | **REVIEW** | Code review (human or Copilot) | Review approved |
 | **DEPLOY** | Production deployment | Deployment checklist complete |
 
-**Intelligent Routing**: The kit analyzes your request keywords and automatically loads the right agents and skills (max 4 agents + 6 skills per session to stay within context budgets).
+**Intelligent Routing**: The kit analyzes your request keywords (including implicit security triggers like "login", "payment", "upload") and automatically loads the right agents and skills (max 4 agents + 8 skills per session to stay within context budgets). Planning workflows use protected budget enforcement — mandatory skills survive trimming even when over budget.
 
 ---
 
@@ -228,7 +226,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 
 | Agent                    | Role                              | Triggers                      |
 | :----------------------- | :-------------------------------- | :---------------------------- |
-| **Planner**              | Task breakdown, Socratic analysis | plan, breakdown, requirements |
+| **Planner**              | Multi-agent plan synthesis, tiered quality schema, specialist coordination | plan, breakdown, requirements |
 | **Sprint Orchestrator**  | Sprint planning, velocity         | sprint, roadmap, velocity     |
 | **Reliability Engineer** | SRE, production readiness         | reliability, SLA, monitoring  |
 
@@ -304,7 +302,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 
 ---
 
-## 🛠️ Skills (31)
+## 🛠️ Skills (32)
 
 ### Operational Skills (5)
 
@@ -343,7 +341,7 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | `git-workflow`         | Branching, commits              |
 | `i18n-localization`    | Internationalization patterns   |
 
-### Development Skills (9)
+### Development Skills (10)
 
 | Skill                   | Purpose                 |
 | :---------------------- | :---------------------- |
@@ -353,15 +351,16 @@ EXPLORE → PLAN → IMPLEMENT → VERIFY → REVIEW → DEPLOY
 | `deployment-procedures` | CI/CD, rollback         |
 | `performance-profiling` | Core Web Vitals         |
 | `brainstorming`         | Socratic discovery      |
-| `plan-writing`          | Structured planning     |
+| `plan-writing`          | Structured planning with tiered quality schema |
+| `plan-validation`       | Quality gate with completeness scoring |
 | `shell-conventions`     | PowerShell/Bash conventions |
 | `ui-ux-pro-max`         | Premium UI/UX design system |
 
 ---
 
-## ⚙️ Runtime Engine (21 Modules)
+## ⚙️ Runtime Engine (29 Modules)
 
-Antigravity AI Kit v3.1.0 includes a **full runtime engine** built across 4 phases — all using Node.js built-ins with zero external dependencies.
+Antigravity AI Kit v3.2.0 includes a **full runtime engine** built across 4 phases — all using Node.js built-ins with zero external dependencies.
 
 ### Phase 1 — Foundation Hardening
 
@@ -379,7 +378,7 @@ Antigravity AI Kit v3.1.0 includes a **full runtime engine** built across 4 phas
 |:---|:---|
 | `workflow-persistence` | Persistent state + checkpoints |
 | `agent-registry` | Agent contract validation |
-| `loading-engine` | Keyword matching + context budget |
+| `loading-engine` | Keyword matching + implicit triggers + context budget |
 | `hook-system` | Event-driven lifecycle hooks |
 | `task-model` | Task CRUD with status tracking |
 
@@ -616,16 +615,16 @@ antigravity-ai-kit/
 ├── .agent/                    # Core AI Kit
 │   ├── agents/               # 19 specialized agents
 │   ├── commands/             # 31 slash commands
-│   ├── skills/               # 31 capability modules
+│   ├── skills/               # 32 capability modules
 │   ├── workflows/            # 14 process templates
 │   ├── engine/               # Autonomy Engine (state machine, loading rules, configs)
-│   ├── hooks/                # 6 event hooks (runtime + git-hook)
+│   ├── hooks/                # 7 event hooks (runtime + git-hook)
 │   ├── rules/                # 8 modular governance rules
 │   ├── checklists/           # Verification checklists (3)
 │   ├── templates/            # ADR, feature-request, bug-report templates
 │   ├── decisions/            # Architecture Decision Records
 │   └── manifest.json         # Machine-readable capability registry
-├── lib/                       # Runtime Engine (21 modules)
+├── lib/                       # Runtime Engine (29 modules)
 │   ├── workflow-engine.js    # State machine enforcement
 │   ├── task-governance.js    # Locking, audit trail, decision timeline
 │   ├── agent-reputation.js   # Score tracking & rankings
@@ -634,8 +633,8 @@ antigravity-ai-kit/
 │   └── + 16 more modules     # Identity, plugins, hooks, registry...
 ├── bin/                       # CLI (ag-kit)
 ├── create-antigravity-app/    # Project scaffolder (separate npm package)
-├── tests/                     # Test suites (261 tests, 25 files)
-│   ├── unit/                 # 21 module tests
+├── tests/                     # Test suites (327 tests, 32 files)
+│   ├── unit/                 # Module tests (loading-engine, self-healing, plugins...)
 │   ├── structural/           # Inventory + schema validation
 │   └── security/             # Injection scan + leakage detection
 ├── docs/                      # MkDocs documentation site
@@ -712,7 +711,7 @@ Want to use Antigravity AI Kit in your project? The **[Contributor Guide](https:
 - Context-driven development from [Google Conductor](https://developers.googleblog.com/en/conductor-introducing-context-driven-development-for-gemini-cli/)
 - Hook concepts from [everything-claude-code](https://github.com/affaan-m/everything-claude-code)
 
-_Antigravity AI Kit v3.1.0 extends these foundations with a 21-module runtime engine, Trust-Grade governance, session management, and 100+ capabilities._
+_Antigravity AI Kit v3.2.0 extends these foundations with a 29-module runtime engine, Trust-Grade governance, session management, and 100+ capabilities._
 
 ---
 

package/bin/ag-kit.js

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const VERSION = '3.0.0';
+const VERSION = require('../package.json').version;
 const AGENT_FOLDER = '.agent';
 
 // ANSI colors
@@ -71,6 +71,7 @@ ${colors.bright}Usage:${colors.reset}
   ag-kit market info <name> Get marketplace plugin details
   ag-kit market install <n> Install from marketplace
   ag-kit heal [--file <f>]  Detect and diagnose CI failures
+  ag-kit health             Run aggregated health check
   ag-kit --help             Show this help message
   ag-kit --version          Show version
 
@@ -524,16 +525,28 @@ const options = {
   file: null,
 };
 
-// Parse --path option
+// Parse --path option with traversal protection (H-7: use path.resolve boundary check)
 const pathIndex = args.indexOf('--path');
 if (pathIndex !== -1 && args[pathIndex + 1]) {
-  options.path = args[pathIndex + 1];
+  const resolvedPath = path.resolve(args[pathIndex + 1]);
+  const cwd = process.cwd();
+  if (!resolvedPath.startsWith(cwd + path.sep) && resolvedPath !== cwd) {
+    log('Error: --path must resolve within current working directory', 'red');
+    process.exit(1);
+  }
+  options.path = resolvedPath;
 }
 
-// Parse --file option
+// Parse --file option with traversal protection (H-7: use path.resolve boundary check)
 const fileIndex = args.indexOf('--file');
 if (fileIndex !== -1 && args[fileIndex + 1]) {
-  options.file = args[fileIndex + 1];
+  const resolvedFile = path.resolve(args[fileIndex + 1]);
+  const cwdForFile = process.cwd();
+  if (!resolvedFile.startsWith(cwdForFile + path.sep) && resolvedFile !== cwdForFile) {
+    log('Error: --file must resolve within current working directory', 'red');
+    process.exit(1);
+  }
+  options.file = resolvedFile;
 }
 
 // Execute command
@@ -567,6 +580,14 @@ switch (command) {
     cliCmd.healCommand(process.cwd(), { file: options.file, apply: options.apply });
     break;
   }
+  case 'health': {
+    const cliHealth = require('../lib/cli-commands');
+    const result = cliHealth.healthCommand(process.cwd());
+    if (!result.healthy) {
+      process.exit(1);
+    }
+    break;
+  }
   case '--version':
   case '-v':
     console.log(VERSION);

package/lib/agent-registry.js

@@ -14,7 +14,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const AGENT_DIR = '.agent';
+const { AGENT_DIR } = require('./constants');
 const AGENTS_SUBDIR = 'agents';
 const MANIFEST_FILE = 'manifest.json';
 
@@ -153,7 +153,14 @@ function validateAgent(agentName, projectRoot) {
  */
 function validateAllAgents(projectRoot) {
   const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { total: 0, valid: 0, invalid: 0, agents: [] };
+  }
+
   const agents = manifest.capabilities?.agents?.items || [];
 
   const results = agents.map((agent) => validateAgent(agent.name, projectRoot));
@@ -175,7 +182,14 @@ function validateAllAgents(projectRoot) {
  */
 function loadRegistry(projectRoot) {
   const manifestPath = path.join(projectRoot, AGENT_DIR, MANIFEST_FILE);
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return { agents: [], totalCount: 0 };
+  }
+
   const agents = manifest.capabilities?.agents?.items || [];
 
   return {

package/lib/agent-reputation.js

@@ -15,8 +15,8 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 
-const AGENT_DIR = '.agent';
-const ENGINE_DIR = 'engine';
+const { AGENT_DIR, ENGINE_DIR } = require('./constants');
+const { writeJsonAtomic } = require('./io');
 const REPUTATION_FILE = 'reputation.json';
 
 /** Score bounds */
@@ -95,15 +95,7 @@ function loadReputationData(projectRoot) {
  */
 function writeReputationData(projectRoot, data) {
   const filePath = resolveReputationPath(projectRoot);
-  const dir = path.dirname(filePath);
-
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  const tempPath = `${filePath}.tmp`;
-  fs.writeFileSync(tempPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-  fs.renameSync(tempPath, filePath);
+  writeJsonAtomic(filePath, data);
 }
 
 /**