@nlaprell/shipit 1.0.0

package/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+## Project: ShipIt
+
+This repository implements an AI-native Software Development Life Cycle optimized for AI agent teams rather than human limitations.
+
+> **Note:** For quick start and usage instructions, see [README.md](./README.md)
+
+## Definition of Done
+
+A feature/bugfix is "done" when ALL of these pass:
+
+- [ ] All tests pass (`pnpm test`)
+- [ ] Lint + typecheck pass (`pnpm lint && pnpm typecheck`)
+- [ ] New/changed behavior has corresponding tests
+- [ ] Public APIs are documented
+- [ ] Intent acceptance criteria all checked
+- [ ] No unresolved security findings
+- [ ] Rollback plan documented
+
+## Conventions
+
+### Code Style
+
+- TypeScript strict mode enabled
+- ESLint + Prettier enforced via pre-commit hooks
+- Prefer configuration over custom code
+
+### Development Process
+
+- **Tests before implementation** (Spec → Tests → Code)
+- All assumptions must be explicit
+- Check `_system/do-not-repeat/` before proposing designs
+- Small, reviewable diffs preferred
+
+### Forbidden Patterns
+
+- No `any` type (use `unknown` if needed)
+- No `eval()`
+- No `innerHTML` (use safe DOM methods)
+- No circular dependencies
+
+## Agent System
+
+This repo uses an AI-native SDLC. Key directories (agent-visible):
+
+| Directory                             | Purpose                                                                                                                                                                                                                                  |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `work/intent/`                        | Planned work (features, bugs, tech-debt); templates/ for kind-specific (API, frontend, infra, bugfix, refactor). New templates must include required fields from \_TEMPLATE.md (Type, Status, Motivation, Acceptance, etc.).             |
+| `work/workflow-state/`                | Current execution state (flat for single intent; per-intent dirs when multiple intents active — see [workflow-state-layout.md](./_system/architecture/workflow-state-layout.md) and [parallel-workflow.md](./docs/parallel-workflow.md)) |
+| `_system/architecture/CANON.md`       | System boundaries and constraints                                                                                                                                                                                                        |
+| `_system/architecture/invariants.yml` | Machine-verifiable constraints                                                                                                                                                                                                           |
+| `_system/do-not-repeat/`              | Failed approaches (don't rediscover)                                                                                                                                                                                                     |
+| `_system/drift/`                      | Entropy monitoring                                                                                                                                                                                                                       |
+| `work/roadmap/`                       | Planning views (now, next, later)                                                                                                                                                                                                        |
+| `_system/behaviors/`                  | Procedures and policies (release, issue tracking)                                                                                                                                                                                        |
+| `.override/`                          | User customizations (rules, commands, scripts, config) that persist across framework upgrades. NEVER touched by `shipit upgrade`.                                                                                                        |
+| `tests/test-project/`                 | Internal test project for framework validation (gitignored). Created by `scripts/init-project.sh` for `/test_shipit` command.                                                                                                            |
+
+`_system/artifacts/SYSTEM_STATE.md` is generated by `scripts/generate-system-state.sh` and read by the Steward. `_system/artifacts/usage.json` holds token/cost entries per phase/intent (aggregate only; no prompt or response content). Record with `pnpm usage-record`; view with `pnpm usage-report` or `/status`. `_system/artifacts/confidence-calibration.json` stores stated confidence vs actual outcome per verification; view with `pnpm calibration-report` or `/calibration-report`.
+
+**Calibration:** How well stated confidence matches reality. The report shows (a) calibration error (MAE) and Brier score, (b) success rate by confidence bin (well-calibrated: e.g. 0.8–0.9 bin has ~85% success), (c) over/under-confidence summary. **Improve calibration:** Lower stated confidence when uncertain; tune analysis/Steward prompts to output more accurate confidence; use `calibration-report --fail-on-threshold 0.2` in CI to catch drift. Optional alert: script warns when recent high-confidence decisions have <50% success.
+
+**Full directory map:** See [\_system/architecture/CANON.md](./_system/architecture/CANON.md) Directory Boundaries and [docs/DIRECTORY_STRUCTURE.md](./docs/DIRECTORY_STRUCTURE.md).
+
+## Human Interrupts Required For
+
+Humans intervene **ONLY** at these gates:
+
+| Gate                  | When                                        |
+| --------------------- | ------------------------------------------- |
+| **Plan Approval**     | Before implementation starts                |
+| **High-Risk Changes** | Auth, payments, permissions, infra, PII     |
+| **Kill/Rollback**     | Kill criteria triggered or major regression |
+
+**Rollback safety:** Use `/rollback <intent-id>` for guided rollback. High-risk steps (force, drop, delete, migration down, production, auth, secret) are **display only** — run manually. No automatic force-push or data deletion. Run rollback for one intent at a time.
+| **Product Judgment** | Subjective UX/taste/value tradeoffs |
+
+**Response time expectation:** Minutes (real-time collaboration)
+
+## Slash Commands
+
+| Command        | Purpose                             |
+| -------------- | ----------------------------------- |
+| `/ship`        | Run full SDLC workflow (Phases 1-6) |
+| `/new_intent`  | Create a new intent file            |
+| `/verify`      | Run verification phase only         |
+| `/kill`        | Kill an intent with rationale       |
+| `/drift_check` | Calculate drift metrics             |
+
+### Commands and scripts
+
+- **Slash command files** live in `.cursor/commands/` and use **underscores** in filenames (e.g. `init_project.md`, `drift_check.md`).
+- **Command manifest:** The full list of slash commands, pnpm scripts, and categories lives in `scripts/command-manifest.yml`. Run `/help` (or `pnpm help`) to see the list; help output is built from the manifest.
+- **Executable scripts** live in `scripts/` and use **hyphens** (e.g. `init-project.sh`, `fix-intents.sh`). New scripts should source `scripts/lib/common.sh` (error handling, colors) or `scripts/lib/intent.sh` (intent resolution); see `scripts/README.md`.
+- **Multiple active intents:** When more than one intent is active, pass intent-id explicitly (e.g. `/ship F-001`, `/verify F-002`). "Current" for a session is the intent-id passed to the last command or the single intent in `work/workflow-state/active.md`. See [docs/parallel-workflow.md](./docs/parallel-workflow.md).
+- Prefer **`pnpm run <script>`** when a script exists: pnpm script names use hyphens. Examples: `/fix` → `pnpm fix`, `/help` → `pnpm help`, `/verify` → `pnpm verify`, `/drift_check` → `pnpm drift-check`, `/new_intent` → `pnpm new-intent`. See `package.json` scripts for the full list.
+
+## Truth Hierarchy
+
+When facts conflict, agents MUST know which source wins. This prevents 30–40% of "AI confusion" bugs.
+
+**Truth Stack (highest to lowest precedence):**
+
+1. **Runtime behavior** — What the system actually does
+2. **Tests** — Executable assertions
+3. **Invariants** — Hard constraints that must never be violated
+4. **Specs** — Formal requirements
+5. **Architecture canon** — CANON.md boundaries
+6. **Comments** — Human annotations in code
+7. **Human opinion** — Always last
+
+> **Rule:** If tests contradict comments, tests win. If runtime contradicts tests, that's a bug to fix—runtime is truth, tests are intent.
+
+## Risk Levels
+
+| Level      | Domains                                    | Review         |
+| ---------- | ------------------------------------------ | -------------- |
+| **High**   | Auth, payments, permissions, infra, PII    | Human required |
+| **Medium** | New dependencies, API changes, performance | AI review      |
+| **Low**    | Docs, refactors, tests, internal tooling   | Automerge      |

package/README.md

@@ -0,0 +1,264 @@
+<p align="center">
+  <img src="shipit.png" width="240" alt="ShipIt logo">
+</p>
+
+# ShipIt 🚀
+
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/NJLaPrell/ShipIt/releases/tag/v1.0.0)
+[![npm](https://img.shields.io/npm/v/@nlaprell/shipit.svg)](https://www.npmjs.com/package/@nlaprell/shipit)
+[![Test results](https://img.shields.io/badge/test%20results-see%20ISSUES-green.svg)](./tests/ISSUES.md)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> **Stop optimizing for humans. Start optimizing for AI.**
+
+An SDLC built for AI-assisted development: state in files, tests as truth, gates instead of meetings. Replaces handoffs and docs with executable truth and state-anchored workflows. **Production ready** — CLI-first; see [tests/ISSUES.md](./tests/ISSUES.md) for validation.
+
+**Repository:** [github.com/NJLaPrell/ShipIt](https://github.com/NJLaPrell/ShipIt)
+
+## Table of Contents
+
+- [1. Quick Start](#1-quick-start)
+- [2. Prerequisites](#2-prerequisites)
+- [3. What You Get](#3-what-you-get)
+- [4. Core Workflow](#4-core-workflow)
+- [5. The Problem & The Solution](#5-the-problem--the-solution)
+- [6. Installation](#6-installation)
+- [7. Key Concepts](#7-key-concepts)
+- [8. Commands Reference](#8-commands-reference)
+- [9. Documentation & Help](#9-documentation--help)
+- [10. FAQ](#10-faq)
+- [11. License](#11-license)
+
+---
+
+## 1. Quick Start
+
+Get from zero to a running project in under two minutes. Steps 3–4 run in **Cursor** or **VS Code** as slash commands.
+
+### 1.1 Install
+
+```bash
+npm install -g @nlaprell/shipit
+# Or: npx @nlaprell/shipit init
+```
+
+### 1.2 Create a new project (or attach to existing)
+
+```bash
+# New project
+create-shipit-app my-awesome-app
+
+# Existing project
+cd my-existing-app && shipit init
+```
+
+You’ll be prompted for tech stack (TypeScript/Node, Python, Other), project description, and high-risk domains.
+
+### 1.3 Open in editor and run first commands
+
+1. Open the project in **Cursor** or **VS Code**.
+2. In the editor, run:
+   - `/scope-project "Build a todo app with auth"` — AI-assisted feature breakdown, generates intents and runs release plan + roadmap.
+   - `/ship F-001` — Runs the full 5-phase workflow (analysis → plan → tests → code → verify → release).
+
+That’s it. The framework drives the rest with progress indicators and gates.
+
+---
+
+## 2. Prerequisites
+
+- **Node.js 20+**
+- **Cursor** or **VS Code** (with ShipIt extension for VS Code). See [Using ShipIt in VS Code](docs/vscode-usage.md).
+- **Git**
+
+---
+
+## 3. What You Get
+
+After `create-shipit-app` or `shipit init`, your project has:
+
+- **`project.json`** — Project metadata and ShipIt version.
+- **`work/intent/`** — Features, bugs, tech-debt as markdown (F-001.md, etc.).
+- **`work/workflow-state/`** — Active phase and per-intent state (see [parallel workflow](docs/parallel-workflow.md)).
+- **`work/roadmap/`** — now / next / later triage.
+- **`work/release/`** — Release plan (what ships when).
+- **`scripts/`** — Framework scripts (verify, fix, status, workflow-orchestrator, etc.).
+- **`.cursor/`** — Slash commands and rules (or equivalent for VS Code).
+- **`_system/`** — Architecture (CANON, invariants), artifacts, behaviors, security, drift. **Do not edit.** Upgraded via `shipit upgrade` only.
+- **`.override/`** — Your customizations (rules, commands, scripts, config); never touched by upgrade.
+
+**Do not edit** `_system/` — framework internals. Use `.override/` for customizations.
+
+Optional: **`dashboard-app/`** — Web dashboard; run with `pnpm dashboard`.
+
+Full tree and planning outputs: [docs/DIRECTORY_STRUCTURE.md](./docs/DIRECTORY_STRUCTURE.md).
+
+---
+
+## 4. Core Workflow
+
+One path: **Install CLI → create or init project → open in editor → scope → ship.**
+
+| Phase           | Commands                                                                                      |
+| --------------- | --------------------------------------------------------------------------------------------- |
+| **Setup**       | CLI: `create-shipit-app` or `shipit init`. Editor: `/scope-project`, `/status`, `/dashboard`. |
+| **Planning**    | `/new_intent`, `/generate-release-plan`, `/generate-roadmap`, `/fix`.                         |
+| **Execution**   | `/ship <id>`, `/verify <id>`, `/status`.                                                      |
+| **Maintenance** | `shipit upgrade`, `/rollback <id>`, `/kill <id>`, `/drift_check`, `/deploy`.                  |
+
+Slash commands run in Cursor or VS Code. Full phase details: [AGENTS.md](./AGENTS.md#workflow).
+
+<details>
+<summary><strong>Detailed workflow diagram</strong></summary>
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         ShipIt Workflow                                  │
+└─────────────────────────────────────────────────────────────────────────┘
+
+SETUP PHASE
+    ├─ create-shipit-app <name>  or  shipit init   (CLI)
+    ├─ /scope-project "Description"  →  intents, release plan, roadmap
+    └─ /status, /dashboard
+
+PLANNING PHASE
+    ├─ /new_intent  →  /generate-release-plan  →  /generate-roadmap
+    └─ /fix  (auto-fix intent issues)
+
+EXECUTION PHASE
+    ├─ /ship <id>  →  [1] Analysis  →  [2] Plan  →  [3] Tests  →  [4] Code  →  [5] Verify  →  Release
+    ├─ /verify <id>, /status
+    └─ /rollback <id>, /kill <id>
+
+MAINTENANCE
+    ├─ shipit upgrade  (backup in ._shipit_backup/)
+    ├─ /drift_check, /deploy
+    └─ /test_shipit (framework E2E)
+```
+
+</details>
+
+---
+
+## 5. The Problem & The Solution
+
+**The problem:** Traditional SDLC assumes humans are the bottleneck. AI agents need state files, executable tests, explicit gates, and do-not-repeat ledgers — not meetings and handoffs. Most failures are unstated assumptions and ambiguous truth, not coding errors.
+
+**The solution:** ShipIt optimizes for **what counts as truth**: tests and invariants over docs, state in files over meetings, explicit gates over tribal knowledge. Add adversarial verification, intent ledger in `work/intent/`, drift detection, and context-aware suggestions. How the 7 agents (Steward, PM, Architect, Implementer, QA, Security, Docs) work together: [AGENTS.md](./AGENTS.md).
+
+---
+
+## 6. Installation
+
+### 6.1 For app developers
+
+See [Quick Start](#1-quick-start) for the full flow. Quick reference:
+
+| Action             | Command                                           |
+| ------------------ | ------------------------------------------------- |
+| Install CLI        | `npm install -g @nlaprell/shipit`                |
+| New project        | `create-shipit-app my-app`                        |
+| Attach to existing | `cd my-app && shipit init`                        |
+| Upgrade framework  | `shipit upgrade` (backs up to `._shipit_backup/`) |
+| Check installation | `shipit check`                                    |
+
+No global install: `npx @nlaprell/shipit init` from your project root. Full options: [docs/CLI_REFERENCE.md](./docs/CLI_REFERENCE.md).
+
+### 6.2 From source (contributors)
+
+**pnpm** is used when developing the framework itself:
+
+```bash
+git clone https://github.com/NJLaPrell/ShipIt.git
+cd ShipIt
+pnpm install
+pnpm test && pnpm test:cli && pnpm test:shipit -- --clean
+# Optional: pnpm validate-cursor  or  pnpm validate-vscode
+```
+
+See [docs/CONTRIBUTING.md](./docs/CONTRIBUTING.md).
+
+### 6.3 User customizations (`.override/`)
+
+Put customizations in `.override/rules/`, `.override/commands/`, `.override/scripts/`, `.override/config/`. They are **never** touched by `shipit upgrade`. [docs/USER_OVERRIDES_DESIGN.md](./docs/USER_OVERRIDES_DESIGN.md).
+
+---
+
+## 7. Key Concepts
+
+- **Intent ledger** — All work lives in `work/intent/` as markdown with executable acceptance criteria, confidence scores, invariants, kill criteria, and rollback plan. Use `/fix` to auto-fix common issues. Templates: [AGENTS.md](./AGENTS.md) and `work/intent/templates/`.
+- **Tests first** — The workflow enforces Spec → Tests → Code. QA writes tests (they fail); Implementer writes code (tests pass). No production code before tests.
+- **Truth hierarchy** — When facts conflict: runtime behavior > tests > invariants > specs > architecture > comments > opinion. [AGENTS.md](./AGENTS.md).
+- **High-risk gates** — Auth, payments, permissions, infrastructure, PII require human approval before implementation.
+
+**More:** GitHub integration, usage/cost, security allowlist, confidence calibration → [AGENTS.md](./AGENTS.md).
+
+---
+
+## 8. Commands Reference
+
+**CLI:** `shipit init | upgrade | check | create | list-backups | restore` — see [docs/CLI_REFERENCE.md](./docs/CLI_REFERENCE.md).
+
+**Editor (slash commands):**
+
+| Category        | Commands                                                                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Setup**       | `create-shipit-app` / `shipit init`, `/scope-project`, `/status`, `/dashboard`                                                                  |
+| **Planning**    | `/new_intent`, `/generate-release-plan`, `/generate-roadmap`, `/fix`, `/pr`, `/create-pr`, `/create-intent-from-issue`, `/risk`, `/revert-plan` |
+| **Execution**   | `/ship <id>`, `/verify <id>`, `/rollback <id>`, `/kill <id>`                                                                                    |
+| **Maintenance** | `/drift_check`, `/deploy`, `/test_shipit`                                                                                                       |
+| **Utility**     | `/help`, `/suggest`, `/dashboard`, `/usage-record`, `/usage-report`, `/calibration-report`                                                      |
+
+All slash commands are in [.cursor/commands/](./.cursor/commands/). Scripts: `pnpm run <script>` (e.g. `pnpm fix`, `pnpm verify`). Headless/VS Code: [docs/headless-mode.md](./docs/headless-mode.md), [docs/vscode-usage.md](./docs/vscode-usage.md).
+
+---
+
+## 9. Documentation & Help
+
+- [docs/CLI_REFERENCE.md](./docs/CLI_REFERENCE.md) — All CLI commands and options
+- [docs/LIMITATIONS.md](./docs/LIMITATIONS.md) — What ShipIt doesn’t do, when not to use
+- [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) — Exit codes, common issues, rollback
+- [docs/EXAMPLES.md](./docs/EXAMPLES.md) — New project, existing project, upgrade, CI
+- [docs/PILOT_GUIDE.md](./docs/PILOT_GUIDE.md) — Step-by-step first feature
+- [docs/DIRECTORY_STRUCTURE.md](./docs/DIRECTORY_STRUCTURE.md) — Project layout
+- [docs/STABILITY.md](./docs/STABILITY.md) — Stable vs experimental APIs
+- [AGENTS.md](./AGENTS.md) — Roles, workflow, conventions
+- [CHANGELOG.md](./CHANGELOG.md) — Version history
+
+---
+
+## 10. FAQ
+
+**Q: How do I install ShipIt?**  
+A: `npm install -g @nlaprell/shipit`. Then `create-shipit-app <name>` or `shipit init`. [CLI_REFERENCE](./docs/CLI_REFERENCE.md).
+
+**Q: Can I use ShipIt with an existing project?**  
+A: Yes. Run `shipit init` in the project root. It merges framework files and package.json. [EXAMPLES](./docs/EXAMPLES.md).
+
+**Q: How do I upgrade?**  
+A: `shipit upgrade`. Backups go to `._shipit_backup/`. Use `--dry-run` first. [TROUBLESHOOTING](./docs/TROUBLESHOOTING.md#after-a-failed-or-unwanted-shipit-upgrade).
+
+**Q: Will upgrade overwrite my changes?**  
+A: Framework-owned files are updated (with backup). App code and non-framework paths are not. Use `.override/` for customizations so they’re never touched.
+
+**Q: How do I customize Cursor/VS Code rules?**  
+A: Add files under `.override/rules/`. [USER_OVERRIDES_DESIGN](./docs/USER_OVERRIDES_DESIGN.md).
+
+**Q: Do I need to understand all 7 agents?**  
+A: No. Use the commands; agents run during `/ship`. [AGENTS.md](./AGENTS.md) for depth.
+
+**Q: What about deployment?**  
+A: `/deploy` runs readiness checks; actual deployment is your pipeline. See [LIMITATIONS](./docs/LIMITATIONS.md).
+
+**Q: Where do I get help?**  
+A: [TROUBLESHOOTING](./docs/TROUBLESHOOTING.md), [GitHub Issues](https://github.com/NJLaPrell/ShipIt/issues).
+
+---
+
+## 11. License
+
+MIT. See [CHANGELOG.md](./CHANGELOG.md) for version history.
+
+---
+
+**Next:** Once you’ve created a project, open it in Cursor or VS Code, run `/scope-project "your goal"`, then `/ship F-001`. Full walkthrough: [docs/PILOT_GUIDE.md](./docs/PILOT_GUIDE.md).

package/_system/architecture/CANON.md

@@ -0,0 +1,159 @@
+# Architecture Canon
+
+> **This document is the authoritative source for system architecture.**
+> Code that violates this canon is illegal. Update this document before implementing violations.
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         ShipIt System                       │
+├─────────────────────────────────────────────────────────────┤
+│  Intent Layer        │  Execution Layer    │  Verification  │
+│  ─────────────────   │  ────────────────   │  ───────────── │
+│  work/intent/        │  work/workflow-state/ │  CI/CD       │
+│  work/roadmap/       │  .cursor/rules/     │  Tests         │
+│  _system/do-not-repeat/ │ .cursor/commands/ │  Linting      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Boundaries
+
+### Layer Responsibilities
+
+| Layer              | Responsibility               | Cannot Do                  |
+| ------------------ | ---------------------------- | -------------------------- |
+| **Intent**         | Define WHAT to build         | Specify HOW to implement   |
+| **Architecture**   | Define HOW systems connect   | Write production code      |
+| **Implementation** | Write code that passes tests | Change architecture        |
+| **Verification**   | Prove correctness            | Weaken acceptance criteria |
+
+### Directory Boundaries
+
+**Full map:** See [docs/DIRECTORY_STRUCTURE.md](../../docs/DIRECTORY_STRUCTURE.md) for a quick reference.
+
+| Directory                | Purpose                                                                                                                                        | Owner              | Modification Rules                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------- |
+| `work/intent/`           | Planned work (features, bugs, tech-debt)                                                                                                       | PM, Steward        | Anyone can propose; Steward approves                              |
+| `_system/architecture/`  | System boundaries, invariants, schemas, ADRs                                                                                                   | Architect, Steward | Requires ADR for changes                                          |
+| `work/workflow-state/`   | Current execution state (phases, status, assumptions). Layout: flat or per-intent; see [workflow-state-layout.md](./workflow-state-layout.md). | All agents         | Append-only during execution; consumers must support both layouts |
+| `_system/do-not-repeat/` | Failed approaches (abandoned designs, bad patterns, rejected libs)                                                                             | All agents         | Append-only; never delete                                         |
+| `/src/`                  | Production source code                                                                                                                         | Implementer        | Must follow approved plan                                         |
+| `/tests/`                | Test code, fixtures, run logs, process docs (see tests/README.md)                                                                              | QA, Implementer    | Tests before implementation                                       |
+| `_system/artifacts/`     | Generated files (SYSTEM_STATE.md, dependencies.md, confidence-calibration.json)                                                                | Scripts            | Regenerated by generate-\* and verify scripts                     |
+| `work/release/`          | Generated release plan (ordered intents by release target)                                                                                     | Scripts            | Regenerated by generate-release-plan.sh                           |
+| `work/roadmap/`          | Planning views (now, next, later triage)                                                                                                       | Scripts            | Regenerated by generate-roadmap.sh                                |
+| `/scripts/`              | Shell scripts for workflow, generation, validation, deploy                                                                                     | All                | Add with approval; follow lib/ for shared code                    |
+| `_system/security/`      | Audit allowlist, security config                                                                                                               | Security, Steward  | Append-only for allowlist                                         |
+| `_system/behaviors/`     | Procedures and policies (release, issue tracking, platform work)                                                                               | All                | Document how we work                                              |
+| `_system/reports/`       | Generated reports (mutation, coverage, etc.)                                                                                                   | Scripts            | Regenerated; often gitignored                                     |
+| `_system/golden-data/`   | Replay validation test data for regression testing                                                                                             | QA                 | Append-only; capture known-good inputs/outputs                    |
+| `/projects/`             | Initialized ShipIt projects (from /init-project)                                                                                               | Scripts            | Contents gitignored; .gitkeep only committed                      |
+| `_system/drift/`         | Entropy baselines and metrics                                                                                                                  | Scripts            | Regenerated by drift-check.sh                                     |
+| `/.cursor/`              | Cursor config (commands/, rules/, agents/)                                                                                                     | All                | Commands and rules are first-class; version controlled            |
+
+## Allowed Dependencies
+
+### External Dependencies
+
+| Category     | Allowed            | Forbidden                  |
+| ------------ | ------------------ | -------------------------- |
+| **Runtime**  | Node.js LTS        | Experimental Node features |
+| **Language** | TypeScript 5.x     | JavaScript (must be TS)    |
+| **Testing**  | Vitest, fast-check | Jest (use Vitest instead)  |
+| **Linting**  | ESLint, Prettier   | TSLint (deprecated)        |
+| **Build**    | esbuild, tsup      | Webpack (too complex)      |
+
+### Internal Dependencies
+
+```
+┌──────────────┐
+│    /src/     │
+├──────────────┤
+│   domain/    │ ← Pure business logic, no I/O
+│   services/  │ ← Orchestration, uses domain
+│   adapters/  │ ← External integrations
+│   utils/     │ ← Shared utilities
+└──────────────┘
+
+Allowed: domain ← services ← adapters
+         utils can be used by any layer
+Forbidden: domain → services (no upward deps)
+           circular dependencies
+```
+
+## Forbidden Patterns
+
+### Code Patterns
+
+| Pattern               | Reason              | Alternative                 |
+| --------------------- | ------------------- | --------------------------- |
+| `any` type            | Defeats type safety | Use `unknown` + type guards |
+| `eval()`              | Security risk       | Use safe alternatives       |
+| `innerHTML`           | XSS vulnerability   | Use textContent or DOM APIs |
+| `console.log` in prod | Leaks info          | Use structured logger       |
+| Circular imports      | Architectural smell | Refactor dependencies       |
+
+### Architectural Patterns
+
+| Pattern              | Reason          | Alternative           |
+| -------------------- | --------------- | --------------------- |
+| God objects          | Unmaintainable  | Single responsibility |
+| Deep inheritance     | Fragile         | Composition           |
+| Global mutable state | Race conditions | Dependency injection  |
+| Magic strings        | Typo-prone      | Constants/enums       |
+
+## Performance Budgets
+
+| Metric      | Budget  | Measurement       |
+| ----------- | ------- | ----------------- |
+| p95 latency | < 200ms | API response time |
+| p99 latency | < 500ms | API response time |
+| Memory      | < 512MB | Process RSS       |
+| Bundle size | < 1MB   | Production build  |
+| Test suite  | < 60s   | Full test run     |
+
+## Security Requirements
+
+### Authentication & Authorization
+
+- All endpoints require authentication except: `/health`, `/metrics`
+- Use principle of least privilege
+- Session tokens expire after 24h max
+- Refresh tokens require re-authentication after 7 days
+
+### Data Handling
+
+- PII must be encrypted at rest
+- Secrets never logged
+- All user input validated and sanitized
+- SQL queries must use parameterized statements
+
+### High-Risk Domains (Require Human Approval)
+
+- 🔐 Authentication changes
+- 💰 Payment processing
+- 🔑 Permission/RBAC changes
+- 🏗️ Infrastructure changes
+- 📋 PII handling changes
+
+## Schema Compatibility
+
+- Database migrations must be backward compatible for 3 versions
+- API changes must maintain backward compatibility
+- Breaking changes require deprecation period (minimum 1 version)
+
+## ADR Log
+
+Architecture Decision Records are stored in `_system/architecture/ADR-###.md`.
+
+| ADR     | Decision                       | Date       |
+| ------- | ------------------------------ | ---------- |
+| ADR-001 | Use TypeScript + Node.js       | 2026-01-12 |
+| ADR-002 | Use Vitest over Jest           | 2026-01-12 |
+| ADR-003 | Prefer config over custom code | 2026-01-12 |
+
+---
+
+_Last updated: 2026-02-04_
+_Approved by: Steward_

package/_system/architecture/invariants.yml

@@ -0,0 +1,87 @@
+# Invariants Configuration
+# These constraints are enforced via ESLint, TypeScript, and CI checks
+# See README.md and AGENTS.md for more details on the invariants system
+
+version: 1
+
+# Security invariants - enforced via ESLint + custom CI
+security:
+  - id: no_pii_unencrypted
+    description: PII must be encrypted at rest
+    enforcement: ci_test
+
+  - id: all_endpoints_authenticated
+    description: All endpoints require auth except health/metrics
+    exceptions:
+      - '/health'
+      - '/metrics'
+      - '/api/v1/public/*'
+    enforcement: ci_test
+
+  - id: secrets_never_logged
+    description: Secrets and tokens must never appear in logs
+    enforcement: eslint_no_console_in_prod
+
+# Code quality invariants - enforced via ESLint
+code_quality:
+  - id: no_explicit_any
+    description: No 'any' type allowed
+    enforcement: '@typescript-eslint/no-explicit-any'
+
+  - id: no_eval
+    description: No eval() calls
+    enforcement: 'no-eval'
+
+  - id: no_inner_html
+    description: No innerHTML assignments
+    enforcement: 'no-unsanitized/property'
+
+  - id: no_circular_deps
+    description: No circular dependencies
+    enforcement: 'import/no-cycle'
+
+# Performance invariants - enforced via CI benchmarks
+performance:
+  p95_latency_ms: 200
+  p99_latency_ms: 500
+  max_memory_mb: 512
+  max_bundle_size_kb: 1024
+  max_test_duration_s: 60
+
+# Data invariants - enforced via CI tests
+data:
+  schema_backward_compat_versions: 3
+  require_idempotent_writes: true
+  require_migration_rollback: true
+
+# Architecture invariants - enforced via ESLint import rules
+architecture:
+  max_import_depth: 5
+  forbidden_patterns:
+    - pattern: 'any'
+      reason: 'Defeats type safety'
+    - pattern: 'eval('
+      reason: 'Security vulnerability'
+    - pattern: '.innerHTML'
+      reason: 'XSS vulnerability'
+    - pattern: 'console.log'
+      context: 'src/**'
+      reason: 'Use structured logger'
+
+# Success metrics - tracked in drift/metrics.md
+success_metrics:
+  test_pass_rate_minimum: 99.5
+  code_coverage_minimum: 80
+  max_cyclomatic_complexity: 10
+  max_file_lines: 500
+
+# ESLint rule mapping (for reference)
+# These map invariants to actual ESLint configuration
+eslint_mapping:
+  '@typescript-eslint/no-explicit-any': 'error'
+  '@typescript-eslint/ban-types': 'error'
+  'no-eval': 'error'
+  'import/no-cycle': 'error'
+  'no-console':
+    - 'error'
+    - allow: ['warn', 'error']