spec-manager 0.1.0

package/AGENTS.md

@@ -0,0 +1,27 @@
+# spec-manager Workflow Capsule
+
+This file is the spec-manager skill-like entrypoint for Codex, OpenCode, and other `AGENTS.md`-compatible tools. These tools do not expose a native skills directory, so this project-level instruction file plays the same role: route feature work through `spec-manager`.
+
+This project uses `spec-manager` for local-first spec-driven development. Specs, tasks, decisions, changes, and audit data are stored as markdown/JSON files in the repository.
+
+## Mandatory Workflow
+
+- Feature work MUST go through `spec-manager`; do not jump directly from a user request to implementation code.
+- New or non-trivial work follows L1 PRD -> L2 Design -> L3 Impl -> Agent Task.
+- Never write implementation code unless the relevant L3 spec is `frozen`.
+- `draft -> confirmed` and `confirmed -> frozen` are user review actions. After writing spec content, stop and wait for explicit user approval.
+- Before creating a new spec, inspect existing specs and decisions with `spec-manager spec list` and `spec-manager decision list --topic <topic>`.
+- Before code edits, read the relevant frozen L3 spec and create/start an Agent Task.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
+## Common Commands
+
+```bash
+spec-manager project status
+spec-manager spec list
+spec-manager spec show <code> --include-content
+spec-manager decision list --topic <topic>
+spec-manager task list --topic <topic>
+```
+
+When the user asks for `/spec-manager <request>` or asks to use spec-manager, treat it as a request to follow this workflow.

package/CODEBUDDY.md

@@ -0,0 +1,19 @@
+# Spec-Driven Development
+
+This repository uses `spec-manager`. CodeBuddy should follow the same workflow as `AGENTS.md` and use spec-manager commands for non-trivial work.
+
+- All feature work should go through `spec-manager`.
+- New work follows L1 PRD -> L2 Design -> L3 Impl -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- `confirm` and `freeze` are user review actions.
+
+## Commands
+
+```bash
+npm run build
+npm run lint
+npm test
+spec-manager project status
+```
+
+Use `src/cli/` for command registrations and `src/core/` for business logic.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,531 @@
+# spec-manager
+
+[![npm version](https://img.shields.io/npm/v/spec-manager)](https://www.npmjs.com/package/spec-manager)
+[![CI](https://github.com/loki-ai-ch/spec-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/loki-ai-ch/spec-manager/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Chinese version](readme_zh.md)
+
+**Local-first spec-driven development platform.** Pure markdown + git storage. No network, no MCP, no backend.
+
+---
+
+## What it does
+
+- **Four-layer funnel** — Requirements → Design → Implementation → Continuity, with human review gates at each layer
+- **L0/L1/L2/L3 spec hierarchy** — vision / PRD / design / implementation spec
+- **24 rules** with `applies_to` filtering — no need to load all 24 every time
+- **Status machine** `draft → confirmed → frozen → implemented`
+- **Agent Task lifecycle** — `create → start → step → complete`, steps in spec frontmatter; R5 blocks complete if steps are skipped
+- **Decision cards** with `what/why/affectedCriteria` + topic query
+- **Rule audit** with at-least-once local JSON accumulator
+- **Delta specs** (OpenSpec-style `changes/<name>/` with ADDED/MODIFIED/REMOVED/RENAMED + archive merge)
+- **Multi-agent setup** — one command installs Claude Code, Codex, OpenCode, and CodeBuddy instructions
+- **RFC 2119** keywords (SHALL/MUST/SHOULD) validation in acceptance criteria
+- **Incident tracking** — rule violations drive rule evolution
+
+> Full methodology: [docs/methodology.md](docs/methodology.md)
+
+## Install
+
+```bash
+# Clone and install globally
+git clone https://github.com/loki-ai-ch/spec-manager.git
+cd spec-manager
+npm install
+npm run build
+npm install -g .
+
+# Or run without installing
+npx spec-manager <command>
+```
+
+## AI Agent Setup
+
+spec-manager is agent-agnostic: the CLI stores the source of truth locally, and AI tools only need a workflow entrypoint that enforces the same rules. Built-in setup supports Claude Code, Codex, OpenCode, CodeBuddy, and other `AGENTS.md`-compatible agents.
+
+Not every tool has a native "skills" directory. spec-manager installs the closest equivalent for each platform: real skills where the platform supports them, and a project-level `AGENTS.md` workflow capsule where it does not.
+
+### Recommended
+
+```bash
+cd my-project
+spec-manager project init --name my-project
+spec-manager project agents --provider all
+```
+
+This writes:
+
+| Provider | spec-manager entrypoint | Files |
+|---|---|---|
+| Claude Code | Native skill | `CLAUDE.md`, `.claude/skills/spec-manager/` |
+| Codex | `AGENTS.md` workflow capsule, not a native skill | `AGENTS.md` |
+| OpenCode | `AGENTS.md` workflow capsule, not a native skill | `AGENTS.md` |
+| CodeBuddy | Native skill | `CODEBUDDY.md`, `.codebuddy/skills/spec-manager/` |
+
+Use a narrower install when needed:
+
+```bash
+spec-manager project agents --provider list
+spec-manager project agents --provider all --dry-run
+spec-manager project agents --provider codex,opencode
+spec-manager project agents --provider codebuddy --force
+```
+
+Use `--dry-run` to preview created, overwritten, and skipped files before touching the project.
+
+References: [Codex `AGENTS.md`](https://github.com/openai/codex/blob/main/docs/agents_md.md), [OpenCode rules](https://opencode.ai/docs/rules/), [CodeBuddy skills](https://www.codebuddy.ai/docs/cli/skills).
+
+For Codex CLI, do not look for a `skills` command or directory. Run Codex from the project root and it will read `AGENTS.md`. Ask it to "Use spec-manager ..." and the file acts as the spec-manager workflow entrypoint.
+
+### Manual install
+
+If you do not want to use the installer, copy the templates directly:
+
+```bash
+# Codex / OpenCode / AGENTS.md-compatible tools (skill-like workflow capsule)
+cp path/to/spec-manager/templates/agents/AGENTS.md my-project/AGENTS.md
+
+# Claude Code
+mkdir -p my-project/.claude/skills/spec-manager
+cp -r path/to/spec-manager/skill/* my-project/.claude/skills/spec-manager/
+cp -r path/to/spec-manager/rules my-project/.claude/skills/spec-manager/rules
+cp -r path/to/spec-manager/templates my-project/.claude/skills/spec-manager/templates
+cp path/to/spec-manager/templates/agents/CLAUDE.md my-project/CLAUDE.md
+
+# CodeBuddy
+mkdir -p my-project/.codebuddy/skills/spec-manager
+cp -r path/to/spec-manager/skill/subskills my-project/.codebuddy/skills/spec-manager/subskills
+cp -r path/to/spec-manager/rules my-project/.codebuddy/skills/spec-manager/rules
+cp -r path/to/spec-manager/templates my-project/.codebuddy/skills/spec-manager/templates
+cp path/to/spec-manager/templates/agents/CODEBUDDY.md my-project/CODEBUDDY.md
+cp path/to/spec-manager/templates/agents/codebuddy-skill/SKILL.md my-project/.codebuddy/skills/spec-manager/SKILL.md
+```
+
+### Start iterating
+
+```bash
+# Claude Code / CodeBuddy skill:
+/spec-manager add user authentication feature
+
+# Codex / OpenCode / other AGENTS.md agents:
+Use spec-manager to add user authentication feature.
+```
+
+The AI will follow the L1→L2→L3→Task pipeline with human review gates at each layer. See [rules/](rules/) for the full 24-rule set.
+
+## Quick start
+
+```bash
+cd my-project
+spec-manager project init --name my-project
+spec-manager project agents --provider all
+spec-manager spec new L1 --topic auth --title "User authentication"  # auto-generates auth-L1
+# write the body to ./l1.md, then:
+spec-manager spec update auth-L1 --content ./l1.md \
+  --ai-summary "OAuth 2.0 + JWT, 3 endpoints" --change-summary "Initial L1"
+# wait for user review
+spec-manager spec confirm <code>
+# L2/L3 follow the same shape: spec new L2 --parent <L1 code>
+```
+
+Or use an AI agent configured with spec-manager:
+
+```bash
+/spec-manager add user authentication feature
+```
+
+## Easier workflows
+
+For day-to-day use, these helper commands reduce command memorization:
+
+```bash
+spec-manager project doctor                 # check setup, agent files, skill assets, placeholders, audit
+spec-manager flow status --topic auth       # show L1/L2/L3/Task progress and the next command
+spec-manager guide "add user auth"          # print the next useful step for a request
+spec-manager new feature --topic auth "User authentication"
+spec-manager approve auth-L1                # draft→confirmed, or L3 confirmed→frozen
+spec-manager run auth-L3.1.1 --plan ./plan.json
+spec-manager template L1 --title "User authentication" > l1.md
+```
+
+Long-form commands remain available; the shortcuts only wrap the same rules and state machine.
+
+| Command | Use it when | What it gives you |
+|---|---|---|
+| `project doctor` | You are unsure whether the project is ready | Setup checks plus concrete fix commands |
+| `flow status` | You need to know where a topic is blocked | L1/L2/L3/Task state and the next command |
+| `guide` | You have a request but do not know which command starts it | The next useful step without changing files |
+| `new feature` | You want the fastest safe way to start an L1 | Creates the L1 shell and prints the next update command |
+| `approve` | The user has explicitly approved a spec | Advances `draft→confirmed` or `L3 confirmed→frozen` |
+| `run` | A frozen L3 is ready to execute | Creates and starts the task from a plan file |
+| `template` | You need a draft file for L1/L2/L3 or `agent-plan` | Prints or writes the bundled template |
+
+Examples:
+
+```bash
+spec-manager project doctor
+spec-manager flow status --topic auth
+spec-manager template L2 --title "Invoice module" --output l2.md
+spec-manager guide "add billing export"
+```
+
+## Usage scenarios
+
+### 1. Quick fix (typo / one-line change)
+
+```bash
+spec-manager spec show <code> --include-content     # read current spec
+# edit the file directly, then:
+spec-manager spec update <code> --content ./fixed.md --ai-summary "fix typo in AC-2" --change-summary "typo fix"
+```
+
+### 2. Research (browse existing specs)
+
+```bash
+spec-manager spec list                               # all specs
+spec-manager spec list --level L1 --status confirmed  # filtered
+spec-manager spec show <code>                         # metadata only (R19)
+spec-manager decision list --topic auth               # decision history
+```
+
+### 3. Full feature (L1 → L2 → L3 → Task)
+
+```bash
+spec-manager spec new L1 --topic billing --title "Billing system"
+spec-manager spec update <l1-code> --content ./l1.md --ai-summary "..." --change-summary "init"
+spec-manager spec confirm <l1-code>                   # user reviews
+
+spec-manager spec new L2 --topic billing --title "Invoice module" --parent <l1-code>
+spec-manager spec update <l2-code> --content ./l2.md --ai-summary "..." --change-summary "init"
+spec-manager spec confirm <l2-code>
+
+spec-manager spec new L3 --topic billing --title "PDF generation" --parent <l2-code>
+spec-manager spec update <l3-code> --content ./l3.md --ai-summary "..." --change-summary "init"
+spec-manager spec confirm <l3-code>
+spec-manager spec freeze <l3-code>                    # frozen → can create task
+
+spec-manager task create <l3-code> --plan ./plan.json --auto-confirm
+spec-manager task start T-001
+spec-manager task step T-001 --no 1 --status succeeded --output-json '{"summary":"..."}'
+spec-manager task complete T-001                      # cascades L3→L2→L1
+```
+
+### 4. Delta change (modify shipped spec)
+
+```bash
+spec-manager change new add-2fa --description "Add 2FA"
+# edit changes/add-2fa/proposal.md + deltas/<code>.md
+spec-manager change archive add-2fa                  # applies & archives
+```
+
+### 5. Postmortem (incident review)
+
+```bash
+spec-manager incident new --severity high --rule R5 --spec <code>
+# fill in .spec-manager/incidents/INC-*.md
+spec-manager incident list
+```
+
+## Tutorial — end-to-end feature
+
+A realistic walk-through of taking a feature from idea to shipped code, using a "user authentication" feature as the running example. Each step maps to one CLI invocation plus a human review gate.
+
+### 1. Initialize the project
+
+```bash
+mkdir my-project && cd my-project
+git init
+spec-manager project init --name my-project
+```
+
+This creates `.spec-manager/` (config + audit + incidents). Add `.spec-manager/audit.json` to `.gitignore` if you don't want the audit log in commits — or commit it, your call.
+
+### 2. Write an L1 PRD (what & why)
+
+```bash
+spec-manager spec new L1 --topic auth --title "User authentication"
+# → outputs: code auth-L1, file specs/auth/auth-L1.md
+```
+
+Before writing the L1 body, the agent should ask 3-4 PRE-WRITE questions (see `templates/L1-prd.md`): who is the user, what's the success metric, what's explicitly out of scope, and — if there's an active decision card on this topic — whether the new spec is consistent with it (`spec-manager decision list --topic auth`).
+
+Then write the L1 body to a draft file and update:
+
+```bash
+cat > /tmp/auth-l1.md <<'EOF'
+# User authentication — L1 PRD
+
+## Background
+... (user stories, MoSCoW ranking, acceptance criteria, scope boundaries)
+
+EOF
+
+spec-manager spec update auth-L1 \
+  --content /tmp/auth-l1.md \
+  --ai-summary "OAuth 2.0 + JWT, 3 endpoints: /login /refresh /me" \
+  --change-summary "Initial L1"
+```
+
+`update` automatically runs warning-only validation (required sections + RFC 2119 keywords). **Don't advance the status yet** — `update` leaves it as `draft`.
+
+### 3. Confirm the L1 (user approval gate)
+
+```bash
+spec-manager spec confirm auth-L1
+# status: draft → confirmed
+```
+
+The user reviews the L1 body (`spec show auth-L1 --include-content`) and approves. Only then do you proceed to L2.
+
+### 4. Write an L2 design (how)
+
+L2s are scoped 1:1 or 1:2 against their L1, split by module boundary, not feature. Each L2 must bind to a parent L1.
+
+```bash
+spec-manager spec new L2 --topic auth --title "OAuth 2.0 backend design" --parent auth-L1
+# → outputs: code auth-L2.1
+
+# write L2 body (technical approach, module boundaries, interface contracts, L3 breakdown)
+cat > /tmp/auth-l2.md <<'EOF'
+# OAuth 2.0 backend design — L2
+
+## Approach
+...
+
+## Interface contract
+| Endpoint | Method | Input | Output | Error codes |
+|---|---|---|---|---|
+| /login | POST | {email, password} | {accessToken, refreshToken} | 401 |
+
+## L3 breakdown
+| L3 code | Scope | Prerequisite |
+|---|---|---|
+| auth-L3.1.1-jwt | JWT signing module | none |
+| auth-L3.1.2-refresh | Refresh token module | auth-L3.1.1-jwt implemented |
+EOF
+
+spec-manager spec update auth-L2.1 \
+  --content /tmp/auth-l2.md \
+  --ai-summary "JWT sign/verify, refresh rotation, 3 endpoints" \
+  --change-summary "Initial L2"
+```
+
+User reviews → `spec confirm auth-L2.1`.
+
+### 5. Write L3 implementation specs (precise steps)
+
+```bash
+spec-manager spec new L3 --topic auth --title "JWT signing module" --parent auth-L2.1 --desc jwt
+# → outputs: code auth-L3.1.1-jwt
+```
+
+L3 is where implementation precision lives: file paths, function signatures, planJson steps. Build the planJson as a separate file:
+
+```bash
+cat > /tmp/jwt-plan.json <<'EOF'
+{
+  "coveredSpecs": ["auth-L3.1.1-jwt"],
+  "steps": [
+    {"stepNo": 1, "stepType": "mcp_tool", "name": "Read parent L2 + sibling L1 historical spec, confirm no duplicate implementation"},
+    {"stepNo": 2, "stepType": "mcp_tool", "name": "Create src/auth/jwt.ts implementing signJwt(payload, secret, ttl)"},
+    {"stepNo": 3, "stepType": "mcp_tool", "name": "Create src/auth/__tests__/jwt.test.ts covering sign + verify + expiry"},
+    {"stepNo": 4, "stepType": "mcp_tool", "name": "Verify: pnpm test src/auth/jwt.test.ts reports 0 failures"}
+  ]
+}
+EOF
+
+# validate the planJson before committing to the L3
+spec-manager spec validate-plan /tmp/jwt-plan.json
+
+# write L3 body referencing the plan
+cat > /tmp/jwt-l3.md <<'EOF'
+# JWT signing module — L3
+
+## Goal
+Implements the "JWT signing" part of auth-L2.1's deliverables 1/2/3.
+
+## Implementation steps
+See /tmp/jwt-plan.json (4 steps; the last step must be a verification).
+EOF
+
+spec-manager spec update auth-L3.1.1-jwt \
+  --content /tmp/jwt-l3.md \
+  --ai-summary "signJwt/verifyJwt functions + unit tests + 4-step planJson" \
+  --change-summary "Initial L3"
+```
+
+L3 needs two confirmations: `spec confirm auth-L3.1.1-jwt`, then `spec freeze auth-L3.1.1-jwt`. `frozen` is the prerequisite for creating an Agent Task.
+
+### 6. Create and run the Agent Task
+
+```bash
+spec-manager task create auth-L3.1.1-jwt --plan /tmp/jwt-plan.json --auto-confirm
+# → outputs: taskId T-001, file specs/auth/tasks/auth-L3.1.1-jwt-T-001.json
+
+spec-manager task start T-001 --spec auth-L3.1.1-jwt
+# step 1
+spec-manager task step T-001 --spec auth-L3.1.1-jwt --no 1 --type mcp_tool --name "Context gathering" \
+  --status succeeded --output-json '{"summary":"read L2 + L1","read":["auth-L2.1"]}' --latency 1200
+# ... repeat for each step
+
+spec-manager task complete T-001 --spec auth-L3.1.1-jwt
+# → L3 status: frozen → implemented
+# → if all L3 children of L2 are implemented: L2 cascades to implemented
+# → if all L2 children of L1 are implemented: L1 cascades to implemented
+```
+
+`task step` is the per-step report (with required `outputJson` per R15); `task complete` triggers the cascade — it never goes the other way (R2).
+
+### 7. Record a decision card (R18: L1 implemented)
+
+Once the L1 is `implemented`, you MUST record at least one decision card capturing the key what/why:
+
+```bash
+spec-manager decision create auth-L1 \
+  --topic auth \
+  --what "Adopt JWT over session" \
+  --why "Stateless scaling, easier to share identity across services" \
+  --criteria "AC-1,AC-2"
+# → outputs: DC-001
+```
+
+`task complete` automatically prints an R18 checklist for any L1 that just cascaded to `implemented` — for each, it shows whether a decision card already exists and the exact CLI commands to create one (and `audit hit R18` to record the check).
+
+```text
+⚠ R18 (decision cards): these L1s just cascaded to implemented — verify a card exists:
+  ✗ auth-L1 [auth] — pending
+    spec-manager decision create auth-L1 \
+      --topic auth --what "..." --why "..." --criteria AC-1,AC-2
+    spec-manager audit hit R18 --spec auth-L1
+  ✓ billing-L1 [billing] — 2 cards (active: 2)
+    spec-manager audit hit R18 --spec billing-L1
+```
+
+**Query decisions** by topic or by AC reference (AC-7 — track which requirements have changed and why):
+
+```bash
+spec-manager decision list --topic auth
+# ● DC-001 [auth]  Adopt JWT over session {AC-1,AC-2}
+# ● DC-002 [auth]  Use refresh-token rotation
+
+spec-manager decision list --criteria AC-1 --include-all
+# ● DC-001 [auth]  Adopt JWT over session
+# ○ DC-003 [auth]  Switch to PASETO (superseded by DC-005)
+# ◐ DC-004 [auth]  Skip refresh-token (partial — see INC-20260604-001)
+```
+
+**Lifecycle** — three states, one transition path:
+
+| From | To | Command | When |
+|---|---|---|---|
+| active | superseded | `decision supersede DC-001 --by DC-005` | new decision fully replaces old |
+| active | partial | `decision set-partial DC-004 --reason "INC-...:AC-3 assumption no longer holds"` | part of the decision is no longer valid |
+| (any) | (deleted) | `decision delete DC-001` | only if `active`; otherwise recover first |
+
+**Edit** a card's `what`/`why`/`affectedCriteria` without changing its status:
+
+```bash
+spec-manager decision update DC-001 \
+  --what "Adopt JWT with short TTL + refresh-token rotation" \
+  --criteria "AC-1,AC-2,AC-3"
+```
+
+Use the [template](templates/decision.md) when writing the body manually (the CLI auto-renders this format).
+
+### 8. Modify an existing spec (delta change)
+
+When you need to change an already-shipped spec, use a change proposal — never edit the spec body directly:
+
+```bash
+spec-manager change new add-2fa --description "Add 2FA two-factor authentication"
+# → creates changes/add-2fa/ (proposal.md + deltas/ + specs/)
+
+# 1. edit changes/add-2fa/proposal.md (why + scope + risk)
+# 2. write changes/add-2fa/deltas/<code>.md with ## MODIFIED Requirements
+# 3. if ADDED, drop a placeholder at changes/add-2fa/specs/<topic>/<code>/<code>.md
+
+spec-manager change archive add-2fa
+# applies RENAMED→REMOVED→MODIFIED→ADDED in order, then moves changes/add-2fa/ to archive/
+```
+
+This gives you a full audit trail: who proposed what, when, and what the spec looked like before the change.
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `spec-manager project init --name X` | Initialize `.spec-manager/` |
+| `spec-manager project status` | Project overview (specs by level, recent activity) |
+| `spec-manager spec list [--level L1] [--topic X] [--status draft]` | List specs (filterable) |
+| `spec-manager spec show <code> [--include-content]` | View spec; default is narrow (metadata only, R19) |
+| `spec-manager spec update <code> --content F --ai-summary S --change-summary R` | Write spec body |
+| `spec-manager spec confirm \| freeze \| implement <code>` | Advance status (human-triggered) |
+| `spec-manager spec validate <code>` | Re-run warning-only validation |
+| `spec-manager spec add-relation <code> --target T --type based_on\|supersedes\|implements\|references` | Cross-spec reference |
+| `spec-manager task create \| start \| step \| complete \| fail \| list \| show` | Agent Task lifecycle |
+| `spec-manager decision create \| list \| show \| update \| set-partial \| supersede \| delete` | Decision cards (R18) |
+| `spec-manager change new \| archive \| list \| show` | Delta spec workflow |
+| `spec-manager incident new \| list` | Rule violation tracking |
+| `spec-manager audit hit \| report \| show` | Local rule audit |
+
+Get full help any time: `spec-manager <command> --help`.
+
+## File layout
+
+Specs are stored flat — dotted codes (`auth-L2.1`, `auth-L3.1.1-jwt`) encode the hierarchy, so no nested directories are needed. `decisions/` and `tasks/` live at the topic level.
+
+```
+my-project/
+├── .spec-manager/
+│   ├── config.yaml
+│   ├── audit.json
+│   └── incidents/
+├── specs/<topic>/
+│   ├── <L1-code>-<date>.md
+│   ├── <L2-code>-<date>.md
+│   ├── <L3-code>[-desc]-<date>.md
+│   ├── decisions/               # R18: L1 implemented → decision cards
+│   │   └── DC-001.md
+│   └── tasks/                   # R3: L3 frozen → agent tasks
+│       └── <specCode>-T-001.json
+├── changes/<name>/
+│   ├── proposal.md
+│   ├── deltas/<code>.md
+│   └── specs/<topic>/<code>/<code>.md  # ADDED placeholder
+└── archive/<name>/               # merged changes
+```
+
+Spec codes follow `<topic>-L<N>[.<M>][-desc]` (e.g. `auth-L1`, `auth-L2.1`, `auth-L3.1.1-jwt`): the code self-documents the hierarchy — no need to trace parent directories. `spec new` auto-generates the code when `--code` is omitted. Use `--desc` to add a ≤15 char suffix for readability.
+
+## Documentation
+
+- [docs/methodology.md](docs/methodology.md) — the public-facing methodology
+
+## Architecture
+
+```
+spec-manager/
+├── src/                    TypeScript CLI source
+│   ├── cli/                command implementations
+│   ├── core/               spec IO, validation, state machine
+│   └── schemas/            Zod schemas
+├── templates/              L0/L1/L2/L3/proposal/decision/incident markdown
+├── rules/                  24 markdown rules with YAML frontmatter
+├── skill/                  Agent skill content (SKILL.md + 12 subskills)
+├── docs/                   public docs
+└── examples/               migration examples
+```
+
+## Design choices
+
+- **Markdown + YAML frontmatter** over JSON or DB: git-friendly, human-readable, diff-able
+- **Atomic file writes** (temp + rename) prevent half-written specs
+- **Narrow view by default** (`spec show` returns metadata only, R19) — saves context
+- **Warning-only validation** — never throws on content quality issues (per R22, R13); R22 blocks confirm/freeze if content is still placeholder
+- **Local rule audit** — JSON file with at-least-once pending queue (no network to fail)
+- **No DAG, strict tree** — L1→L2→L3→Task linear; delta changes are separate concept
+
+## License
+
+MIT

package/dist/cli/audit.d.ts

@@ -0,0 +1,10 @@
+/**
+ * audit 子命令：
+ *   session start [--session-id ID] [--topic T]
+ *   hit <ruleId> [--spec S] [--task T]
+ *   report
+ *   show [--rule R1]
+ */
+import { Command } from 'commander';
+export declare function registerAuditCommands(program: Command): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/cli/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/cli/audit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqD5D"}

package/dist/cli/audit.js

@@ -0,0 +1,62 @@
+/**
+ * audit 子命令：
+ *   session start [--session-id ID] [--topic T]
+ *   hit <ruleId> [--spec S] [--task T]
+ *   report
+ *   show [--rule R1]
+ */
+import { randomBytes } from 'node:crypto';
+import { getPaths } from '../core/paths.js';
+import { hit, report, showSummary, startSession, RULE_ID_RE } from '../core/audit.js';
+export function registerAuditCommands(program) {
+    const audit = program
+        .command('audit')
+        .description('规则合规审计（at-least-once 语义，本地存档）');
+    audit
+        .command('session')
+        .description('启动一个 audit session（不调也能 hit，sessionId 自动生成）')
+        .option('--session-id <id>', '自定义 session ID')
+        .option('--topic <topic>', '绑定 topic')
+        .action((opts) => {
+        const paths = getPaths();
+        const sessionId = opts.sessionId ?? `sess-${randomBytes(4).toString('hex')}`;
+        const state = startSession(paths, { sessionId, topic: opts.topic });
+        console.log(`✓ Audit session started: ${state.sessionId}`);
+        if (state.topic)
+            console.log(`  topic: ${state.topic}`);
+        console.log(`  file: ${paths.auditFile}`);
+    });
+    audit
+        .command('hit <ruleId>')
+        .description('递增某条规则的命中计数（at-least-once: 总是写 pending）')
+        .option('--spec <specCode>', '关联的 spec code')
+        .option('--task <taskCode>', '关联的 task code')
+        .action((ruleId, opts) => {
+        if (!RULE_ID_RE.test(ruleId)) {
+            console.error(`✗ ruleId 格式非法: ${ruleId}（必须 /^R([1-9]|1[0-9]|2[0-4])$/）`);
+            process.exit(2);
+        }
+        const paths = getPaths();
+        const state = hit({ paths, ruleId, specCode: opts.spec, taskCode: opts.task });
+        console.log(`✓ ${ruleId} hit (count: ${state.rules[ruleId]})`);
+        console.log(`  pending: ${state.pending.filter(e => !e.reported).length} unreported`);
+    });
+    audit
+        .command('report')
+        .description('flush pending 队列 → 本地 archive')
+        .action(() => {
+        const paths = getPaths();
+        const result = report(paths);
+        console.log(`✓ Audit reported: ${result.markedReported} entries → archive`);
+        console.log(`  remaining pending: ${result.remaining}`);
+    });
+    audit
+        .command('show')
+        .description('查看 audit 摘要（24 条规则 + pending 数量）')
+        .option('--rule <ruleId>', '只看一条规则')
+        .action((opts) => {
+        const paths = getPaths();
+        console.log(showSummary(paths, { ruleId: opts.rule }));
+    });
+}
+//# sourceMappingURL=audit.js.map