{"_id":"@agent-stack2/guardian","_rev":"2-744ecd7386f8f8858b7f2a5ffd41832a","name":"@agent-stack2/guardian","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agent-stack2/guardian","version":"0.1.0","keywords":["agent-stack","code-review","validation","mcp","coding-agents"],"author":{"name":"jsalvadorlpz"},"license":"MIT","_id":"@agent-stack2/guardian@0.1.0","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"bin":{"agent-guardian":"dist/cli.js"},"dist":{"shasum":"9d0b2c539fa21af77ff8aee37b4a1be2a6094587","tarball":"https://registry.npmjs.org/@agent-stack2/guardian/-/guardian-0.1.0.tgz","fileCount":159,"integrity":"sha512-J9q8ambI3uGcfOlpzuZ+GO0qtEk0uhaL0M902qlMYkhRIHJwksAu7eWr3UY+jql7E6lluW2lnahOCmWUSR0Rsw==","signatures":[{"sig":"MEUCIQDQ0hUS9AtOsp90a9MRzym2RDGzs4jaXhMETdkSe0Zv+AIgcKTZE7CzmBiV7N6WA9t7KXLRXKocDgDHG3K2/zM5FaA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":667679},"main":"./dist/server.js","type":"module","_from":"file:agent-stack2-guardian-0.1.0.tgz","types":"./dist/server.d.ts","engines":{"node":">=18.0.0"},"scripts":{"test":"vitest run","build":"tsc","clean":"rm -rf dist","start":"node dist/server.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"_resolved":"/tmp/ab04cd58cd458f6b9175d8b818502e40/agent-stack2-guardian-0.1.0.tgz","_integrity":"sha512-J9q8ambI3uGcfOlpzuZ+GO0qtEk0uhaL0M902qlMYkhRIHJwksAu7eWr3UY+jql7E6lluW2lnahOCmWUSR0Rsw==","repository":{"url":"git+https://github.com/jsalvadorlpz/agent-stack.git","type":"git","directory":"packages/guardian"},"_npmVersion":"10.8.2","description":"Automated code review and validation layer for agent-produced changes","directories":{},"_nodeVersion":"20.20.1","dependencies":{"zod":"^3.24.4","@agent-stack2/token-gate":"0.1.0","@modelcontextprotocol/sdk":"^1.12.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.1","typescript":"^5.8.3","@types/node":"^22.15.3"},"_npmOperationalInternal":{"tmp":"tmp/guardian_0.1.0_1774196718143_0.6451935493415266","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agent-stack2/guardian","version":"0.2.0","description":"Automated code review and validation layer for agent-produced changes","license":"MIT","author":{"name":"jsalvadorlpz"},"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/guardian"},"homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"keywords":["agent-stack","code-review","validation","mcp","coding-agents"],"type":"module","main":"./dist/server.js","bin":{"agent-guardian":"dist/cli.js"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.1","zod":"^3.24.4","@agent-stack2/token-gate":"0.1.0"},"devDependencies":{"@types/node":"^22.15.3","typescript":"^5.8.3","vitest":"^3.1.1"},"scripts":{"build":"tsc","start":"node dist/server.js","test":"vitest run","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_id":"@agent-stack2/guardian@0.2.0","types":"./dist/server.d.ts","_integrity":"sha512-jp1YSPECXx406NT8Tx7F+97e89PT/5CPzKPMoHz63ip4Xz7CLftJftDDso6iLez0MifyL+3AS90B0jPKRLfx+A==","_resolved":"/tmp/d862d6aea7d589c5e913a8849668225a/agent-stack2-guardian-0.2.0.tgz","_from":"file:agent-stack2-guardian-0.2.0.tgz","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-jp1YSPECXx406NT8Tx7F+97e89PT/5CPzKPMoHz63ip4Xz7CLftJftDDso6iLez0MifyL+3AS90B0jPKRLfx+A==","shasum":"3f57449a2b40b0e001af42bd2b7748fa9a0a7c6a","tarball":"https://registry.npmjs.org/@agent-stack2/guardian/-/guardian-0.2.0.tgz","fileCount":91,"unpackedSize":340103,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCd+vGRC/08N2rxj/jJ1PixLffxpn8ktXXPj7blnXt45gIhANbAIGhjJxoxz0IlaAypOQOMMRIkZeZbsoB+UwJuLwoQ"}]},"_npmUser":{"name":"josepsalvador","email":"josep100998@gmail.com"},"directories":{},"maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/guardian_0.2.0_1774460989150_0.774085634095296"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T16:25:18.039Z","modified":"2026-03-25T17:49:49.454Z","0.1.0":"2026-03-22T16:25:18.328Z","0.2.0":"2026-03-25T17:49:49.296Z"},"bugs":{"url":"https://github.com/jsalvadorlpz/agent-stack/issues"},"author":{"name":"jsalvadorlpz"},"license":"MIT","homepage":"https://github.com/jsalvadorlpz/agent-stack#readme","keywords":["agent-stack","code-review","validation","mcp","coding-agents"],"repository":{"type":"git","url":"git+https://github.com/jsalvadorlpz/agent-stack.git","directory":"packages/guardian"},"description":"Automated code review and validation layer for agent-produced changes","maintainers":[{"name":"josepsalvador","email":"josep100998@gmail.com"}],"readme":"# Agent Guardian\n\nAgent Guardian is the pre-commit review layer for coding agents.\n\nIts job is not to be a generic lint bundle. Its job is to answer the questions\nan agent actually needs answered before it keeps going:\n\n- Did my diff leak a secret?\n- Did I introduce a risky dependency or break a public export?\n- Did I add generated junk, oversized artifacts, or suspicious code patterns?\n- Is this change safe enough to continue, or should I stop and fix it now?\n\nThe long-term goal is a deterministic, diff-first safety layer that agents run\nconstantly during implementation, not just at the end.\n\n## Product thesis\n\nStrong coding agents do not fail only because they cannot write code. They also\nfail because they move too quickly through risky changes without a reliable\nreview loop.\n\nTraditional linting and SAST tools are not enough:\n\n- they often scan the whole repo instead of the actual change surface\n- they produce noise from pre-existing debt\n- they are not designed for agent handoffs or session continuity\n- they rarely answer the operational question: \"should I keep going right now?\"\n\nAgent Guardian exists to provide that loop.\n\n## What \"good\" looks like\n\nIn the ideal flow:\n\n1. An agent edits code.\n2. Agent Guardian reviews the staged, unstaged, and untracked change surface.\n3. It returns a compact verdict with precise blocking findings.\n4. The agent fixes critical issues before handing off or committing.\n5. Important findings and decisions are recorded into Agent Memory.\n6. The next agent resumes with both implementation context and review context.\n\nThe next session should not need to rediscover the same obvious risks.\n\n## Current status\n\nThe current implementation already has a useful nucleus:\n\n- deterministic checks for secrets, dependencies, API surface, complexity, patterns, and large files\n- a TypeScript CLI and MCP server\n- schema validation with `zod`\n- unit tests around the current heuristics\n- local `.mcp.json` wiring into the rest of Agent Toolkit\n\nBut it is not yet the definitive product.\n\nThe dogfood demo proves the full loop works end to end:\n\n```bash\nnpm run demo:dogfood\n```\n\nSee [docs/DEMO.md](docs/DEMO.md) for details on the demo scenario and how to\nuse Guardian in Claude Code and Codex workflows.\n\nRecent completions (AG-201 through AG-205):\n\n- untracked files are now reviewed alongside staged and unstaged changes\n- findings are diff-aware — only changed lines are flagged, not legacy debt\n- every built check is individually callable through MCP\n- review config persists to `.guardian.json` at the repo root with deep-merge layering\n- config discovery uses `git rev-parse --show-toplevel` — works from any subdirectory\n- partial config updates preserve sibling fields (deep merge, not shallow replace)\n- accepted debt can be suppressed via deterministic baseline entries\n- review outcomes are automatically recorded into local `.agent-memory`\n- review fingerprints include full finding identity (file, line, message, severity)\n  so materially different outcomes are never falsely deduplicated\n- active-task resolution is deterministic: exactly one active task required,\n  multiple active tasks cause an explicit skip rather than arbitrary selection\n- deduplication prevents identical consecutive events; clean passes after warnings/fails\n  are recorded as verification events\n- memory write failures never block or corrupt the review result\n\nRecent completions (AG-207 through AG-211):\n\n- dependency delta analysis scoped to the change surface with optional audit enrichment\n- SARIF 2.1.0 output for CI code-scanning upload (`--format sarif`)\n- review-comment JSON output for PR annotation adapters (`--format review-comments`)\n- CLI `--format text|json|sarif|review-comments` and `--output <path>` flags\n- coordinator-aware `preflight_edit` MCP tool that checks for overlapping claims\n- barrel-file and re-export aware API surface modeling (`export *`, `export { } from`)\n- explicit verdict/policy profiles: advisory, balanced, strict\n\n## Docs\n\n- [ROADMAP.md](ROADMAP.md) - product roadmap and delivery phases\n- [PAIN-POINTS.md](PAIN-POINTS.md) - the concrete agent failures this tool must remove\n- [docs/IDEAL-GUARDIAN.md](docs/IDEAL-GUARDIAN.md) - what the finished product should feel like\n- [docs/BACKLOG.md](docs/BACKLOG.md) - execution order for the next implementation slices\n- [docs/DEMO.md](docs/DEMO.md) - dogfood demo: how to run it, what it proves\n\n## Relationship to Agent Memory\n\n`agent-memory-kit` stores durable execution context.\n\n`agent-guardian` should eventually store durable review context:\n\n- what risk was found\n- what was fixed or waived\n- what remains open\n- what patterns keep recurring across sessions\n\nAs of AG-205, `reviewChanges()` automatically records review outcomes into the\nlocal `.agent-memory` directory. The adapter discovers the active task, writes\nstructured events with provenance, and deduplicates identical consecutive\nresults. Memory write failures are handled gracefully and never block the\nreview result.\n\n## Development workflow\n\nThis repo uses Agent Memory in local mode via `.mcp.json`.\n\nOn a fresh clone or empty memory directory:\n\n```powershell\nnpm run bootstrap:memory\n```\n\nRecommended workflow for every serious iteration:\n\n1. `boot_context()`\n2. Read `README.md`, `ROADMAP.md`, `PAIN-POINTS.md`, and `docs/`\n3. If memory is empty or unresolved, run `npm run bootstrap:memory`\n4. Execute the next task from [docs/BACKLOG.md](docs/BACKLOG.md)\n5. Record decisions, blockers, and verification in memory\n6. Run `npm run verify`\n7. `finalize_node(summary=\"...\")`\n\nTreat memory as mandatory for product and architecture work. If the repo\ndirection changed and memory stayed silent, the next agent starts colder than it\nshould.\n\n## Current status\n\nThe core Guardian hardening sequence (AG-201 through AG-206) is complete:\n\n- `AG-201` trustworthy diff collection\n- `AG-202` diff-aware findings\n- `AG-203` full MCP tool coverage\n- `AG-204` persistent config and baselines\n- `AG-205` memory-backed review recording\n- `AG-206` end-to-end dogfood demo\n\nPain-point closure sequence:\n\n- `AG-207` dependency delta analysis ✓\n- `AG-208` SARIF / review-comment output ✓\n- `AG-209` coordinator-aware guarded actions ✓\n- `AG-210` barrel/re-export API surface modeling ✓\n- `AG-211` verdict / policy profiles ✓\n\nAll planned work items are complete. Agent Guardian is feature-complete.\n\n## Long-term promise\n\nThe real promise is not \"more checks.\"\n\nIt is:\n\n\"Give coding agents a fast, trustworthy review loop that catches costly\nmistakes before those mistakes become commits, handoffs, or production bugs.\"\n","readmeFilename":"README.md"}