wolverine-kit 0.0.1__py3-none-any.whl

wolverine_kit/__init__.py

@@ -0,0 +1,5 @@
+"""Wolverine Kit — spec-driven agent framework."""
+
+from wolverine_kit.__version__ import __version__
+
+__all__ = ["__version__"]

wolverine_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

wolverine_kit/cli.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+app = typer.Typer(name="wk", no_args_is_help=True)
+
+
+@app.callback()
+def _main() -> None:
+    """Wolverine Kit — scaffold AI agent governance into any project."""
+
+
+@app.command()
+def init(
+    project: Annotated[str, typer.Argument(help="Project name or '.' for current directory")] = ".",
+    agent: Annotated[str | None, typer.Option("--agent", help="AI coding agent: claude, cursor, kiro, copilot, generic")] = None,
+    pack: Annotated[str | None, typer.Option("--pack", help="Agent pack (e.g. python-library)")] = None,
+    prefix: Annotated[str | None, typer.Option("--prefix", help="Slash command prefix")] = None,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite existing files without prompting")] = False,
+    no_git: Annotated[bool, typer.Option("--no-git", help="Skip git init")] = False,
+    here: Annotated[bool, typer.Option("--here", help="Initialize in current directory")] = False,
+) -> None:
+    """Scaffold a new Wolverine Kit project."""
+    from wolverine_kit.init.command import run_init
+
+    run_init("." if here else project, agent, pack, prefix, force, no_git)
+
+
+@app.command()
+def update(
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show what would change without writing files")] = False,
+    force: Annotated[bool, typer.Option("--force", help="Accept all updates without prompting")] = False,
+) -> None:
+    """Apply wolverine-kit framework upgrades to this project."""
+    from wolverine_kit.update.command import run_update
+
+    run_update(dry_run=dry_run, force=force)
+
+
+if __name__ == "__main__":
+    app()

wolverine_kit/init/agents.py

@@ -0,0 +1,23 @@
+AGENTS: dict[str, dict[str, str | None]] = {
+    "claude": {
+        "agents_dir": ".claude/agents",
+        "commands_dir": ".claude/commands",
+        "context_file": "CLAUDE.md",
+    },
+    "cursor": {
+        "rules_dir": ".cursor/rules",
+        "context_file": ".cursor/rules/wolverine-kit.mdc",
+    },
+    "kiro": {
+        "prompts_dir": ".kiro/prompts",
+        "context_file": None,
+    },
+    "copilot": {
+        "instructions_file": ".github/copilot-instructions.md",
+        "context_file": ".github/copilot-instructions.md",
+    },
+    "generic": {
+        "agents_dir": None,
+        "context_file": None,
+    },
+}

wolverine_kit/init/command.py

@@ -0,0 +1,140 @@
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from wolverine_kit.init import ui
+from wolverine_kit.init.agents import AGENTS
+from wolverine_kit.init.scaffold import run_scaffold
+
+_AGENT_LABELS: dict[str, str] = {
+    "claude": "Claude Code",
+    "cursor": "Cursor",
+    "kiro": "Kiro CLI",
+    "copilot": "GitHub Copilot",
+    "generic": "Other (generic)",
+}
+
+_TECH_STACK_DEFAULTS: dict[str, dict[str, str]] = {
+    "python": {"source_dir": "src/", "test_dir": "tests/"},
+    "node.js": {"source_dir": "src/", "test_dir": "__tests__/"},
+    "go": {"source_dir": "./", "test_dir": "./"},
+}
+
+
+def _slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
+
+
+def _git_init(target_dir: Path) -> None:
+    try:
+        subprocess.run(["git", "init"], cwd=target_dir, check=True, capture_output=True)
+        subprocess.run(["git", "add", "."], cwd=target_dir, check=True, capture_output=True)
+        subprocess.run(
+            ["git", "commit", "-m", "wk: scaffold project"],
+            cwd=target_dir,
+            check=True,
+            capture_output=True,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        ui.show_warning("git not available or failed — skipping initial commit")
+
+
+def run_init(
+    project: str,
+    agent: str | None,
+    pack: str | None,
+    prefix: str | None,
+    force: bool,
+    no_git: bool,
+) -> None:
+    # 1. Resolve target directory
+    if project in (".", "--here"):
+        target_dir = Path.cwd()
+        project_name = target_dir.name
+    else:
+        target_dir = Path(project) if Path(project).is_absolute() else Path.cwd() / project
+        project_name = target_dir.name
+
+    if target_dir.exists() and any(target_dir.iterdir()) and not force:
+        ui.show_error("Directory not empty. Use --force to overwrite.")
+        sys.exit(1)
+
+    # Track whether we created the directory (for cleanup on failure)
+    created_dir = not target_dir.exists()
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    # 2. Agent selection
+    if agent is None:
+        agent = ui.prompt_agent_selection()
+
+    if agent not in AGENTS:
+        ui.show_error(f"Unknown agent: {agent!r}. Choose from: {', '.join(AGENTS)}")
+        sys.exit(1)
+
+    # 3. Collect Copier variables
+    project_slug = _slugify(project_name)
+    command_prefix = prefix or project_slug[:3]
+    stack_key = "python"
+    stack_defaults = _TECH_STACK_DEFAULTS.get(stack_key, _TECH_STACK_DEFAULTS["python"])
+
+    data: dict[str, str] = {
+        "project_name": project_name,
+        "project_slug": project_slug,
+        "command_prefix": command_prefix,
+        "spec_dir": "spec",
+        "unit_term": "module",
+        "unit_term_plural": "modules",
+        "surface_file": "DX.md",
+        "source_dir": stack_defaults["source_dir"],
+        "test_dir": stack_defaults["test_dir"],
+        "tech_stack": "Python",
+        "agent_tool": agent,
+        "pack": pack or "none",
+    }
+
+    steps: list[tuple[str, bool]] = [
+        ("Create project directory", True),
+        ("Generate spec stubs (9 files)", False),
+        ("Install agent prompts", False),
+        ("Generate CLAUDE.md", False),
+        ("git init + initial commit", False),
+    ]
+    ui.show_progress_steps([(s, False) for s, _ in steps])
+
+    # 4. Run Copier (with I10 cleanup on failure)
+    try:
+        run_scaffold(target_dir, data, force=force)
+    except KeyboardInterrupt:
+        if created_dir:
+            import shutil
+
+            shutil.rmtree(target_dir, ignore_errors=True)
+        ui.show_error("Cancelled.")
+        sys.exit(130)
+    except Exception as exc:
+        if created_dir:
+            import shutil
+
+            shutil.rmtree(target_dir, ignore_errors=True)
+        ui.show_error("Scaffolding failed", str(exc))
+        sys.exit(2)
+
+    done_steps = [
+        ("Create project directory", True),
+        ("Generate spec stubs (9 files)", True),
+        ("Install agent prompts", True),
+        ("Generate CLAUDE.md", True),
+        ("git init + initial commit", not no_git),
+    ]
+    ui.show_progress_steps(done_steps)
+
+    # 5. Git init
+    if not no_git:
+        _git_init(target_dir)
+
+    # 6. Post-init summary
+    agent_label = _AGENT_LABELS.get(agent, agent)
+    ui.show_post_init_summary(project_name, agent_label, "spec", f"/{command_prefix}-")
+    ui.show_next_steps(f"/{command_prefix}-", project_name)
+    ui.show_commands_panel(f"/{command_prefix}-")

wolverine_kit/init/scaffold.py

@@ -0,0 +1,29 @@
+import importlib.resources
+from pathlib import Path
+
+import copier
+import yaml
+
+
+def run_scaffold(target_dir: Path, data: dict[str, str], force: bool = False, pretend: bool = False) -> None:
+    template_resource = importlib.resources.files("wolverine_kit") / "templates"
+    with importlib.resources.as_file(template_resource) as template_path:
+        copier.run_copy(
+            src_path=str(template_path),
+            dst_path=str(target_dir),
+            data=data,
+            defaults=True,
+            overwrite=force,
+            quiet=True,
+            pretend=pretend,
+        )
+        if not pretend:
+            _write_answers_file(target_dir, str(template_path), data)
+
+
+def _write_answers_file(target_dir: Path, src_path: str, data: dict[str, str]) -> None:
+    answers: dict = {"_src_path": src_path, "_commit": None}
+    answers.update(data)
+    answers_path = target_dir / ".wolverine-kit.yml"
+    with open(answers_path, "w") as f:
+        yaml.dump(answers, f, default_flow_style=False, allow_unicode=True, sort_keys=False)

wolverine_kit/init/ui.py

@@ -0,0 +1,85 @@
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
+from rich.table import Table
+
+console = Console()
+
+_AGENT_LABELS: dict[str, str] = {
+    "claude": "Claude Code",
+    "cursor": "Cursor",
+    "kiro": "Kiro CLI",
+    "copilot": "GitHub Copilot",
+    "generic": "Other (generic)",
+}
+
+
+def prompt_agent_selection() -> str:
+    choices = list(_AGENT_LABELS.items())
+    console.print("\n[bold]Select your AI coding agent:[/bold]\n")
+    for i, (_, label) in enumerate(choices, 1):
+        console.print(f"  {i}. {label}")
+    console.print()
+    idx = Prompt.ask("Enter number", choices=[str(i) for i in range(1, len(choices) + 1)])
+    return choices[int(idx) - 1][0]
+
+
+def show_post_init_summary(project_name: str, agent: str, spec_dir: str, prefix: str) -> None:
+    tbl = Table(show_header=False, box=None, padding=(0, 2))
+    tbl.add_column(style="bold")
+    tbl.add_column()
+    tbl.add_row("Project", project_name)
+    tbl.add_row("Agent", agent)
+    tbl.add_row("Spec dir", f"{spec_dir}/")
+    tbl.add_row("Prefix", prefix)
+    console.print(Panel(tbl, title="Wolverine Kit", border_style="blue"))
+
+
+def show_progress_steps(steps: list[tuple[str, bool]]) -> None:
+    console.print("\n[bold]Initialize Wolverine Kit[/bold]")
+    for label, done in steps:
+        mark = "[green]●[/green]" if done else "[dim]○[/dim]"
+        console.print(f"── {mark} {label}")
+    console.print("\n[bold green]Project ready.[/bold green]\n")
+
+
+def show_next_steps(prefix: str, project_name: str) -> None:
+    lines = [
+        f"  1. [bold]cd {project_name}[/bold]",
+        "  2. Fill in spec/ files:",
+        "     spec/INVARIANTS.md — your non-negotiable rules",
+        "     spec/DECISIONS.md  — binding tech choices (ADRs)",
+        "     spec/ARCHITECTURE.md — modules and boundaries",
+        "  3. Start your agent and run:",
+        f"     [bold]{prefix}check[/bold]   — validate spec completeness",
+        f"     [bold]{prefix}status[/bold]  — see roadmap progress",
+    ]
+    console.print(Panel("\n".join(lines), title="Next Steps", border_style="blue"))
+
+
+def show_commands_panel(prefix: str) -> None:
+    tbl = Table(show_header=False, box=None, padding=(0, 2))
+    tbl.add_column(style="bold cyan")
+    tbl.add_column()
+    commands = [
+        (f"{prefix}check", "Full hygiene sweep"),
+        (f"{prefix}status", "Roadmap burn-down"),
+        (f"{prefix}review-spec", "Architect review of spec quality"),
+        (f"{prefix}spec <unit>", "Guardian gate + implementation brief"),
+        (f"{prefix}impl <unit>", "Full gate chain + test spec + handoff"),
+        (f"{prefix}drift", "Scan for spec↔code drift"),
+    ]
+    for cmd, desc in commands:
+        tbl.add_row(cmd, desc)
+    console.print(Panel(tbl, title="Available Commands", border_style="blue"))
+
+
+def show_error(message: str, detail: str | None = None) -> None:
+    console.print(f"[bold red]Error:[/bold red] {message}")
+    if detail:
+        console.print(f"[dim]{detail}[/dim]")
+
+
+def show_warning(message: str) -> None:
+    console.print(f"[yellow]Warning:[/yellow] {message}")

wolverine_kit/templates/copier.yml

@@ -0,0 +1,78 @@
+_subdirectory: project
+_templates_suffix: .jinja
+_answers_file: .wolverine-kit.yml
+_skip_if_exists:
+  - "{{spec_dir}}/*"
+_exclude:
+  - "{% if pack != 'python-library' %}**/*-py-protocol-validator*{% endif %}"
+
+project_name:
+  type: str
+  help: Project name
+
+project_slug:
+  type: str
+  default: "{{ project_name | lower | replace(' ', '-') }}"
+  help: Kebab-case project slug
+
+command_prefix:
+  type: str
+  default: "{{ project_slug[:3] }}"
+  help: Slash command prefix (e.g. wk, fas, my)
+
+spec_dir:
+  type: str
+  default: "spec"
+  help: Spec directory
+
+unit_term:
+  type: str
+  default: "module"
+  help: What you call a unit of work
+
+unit_term_plural:
+  type: str
+  default: "{{ unit_term }}s"
+  help: Plural of unit_term
+
+surface_file:
+  type: str
+  default: "DX.md"
+  choices:
+    - DX.md
+    - API.md
+  help: Public surface spec file
+
+source_dir:
+  type: str
+  default: "src/"
+  help: Source directory
+
+test_dir:
+  type: str
+  default: "tests/"
+  help: Test directory
+
+tech_stack:
+  type: str
+  default: "Python"
+  help: Primary language/framework
+
+agent_tool:
+  type: str
+  default: "claude"
+  choices:
+    - claude
+    - cursor
+    - kiro
+    - copilot
+    - generic
+  help: AI coding agent
+
+pack:
+  type: str
+  default: "none"
+  choices:
+    - none
+    - python-library
+  help: Optional agent pack for tech-stack-specific agents

wolverine_kit/templates/project/.claude/agents/{{command_prefix}}-architect-reviewer.md.jinja

@@ -0,0 +1,79 @@
+---
+name: {{ command_prefix }}-architect-reviewer
+description: Holistic design review of {{ spec_dir }}/ files. Checks invariant completeness, missing ADRs, boundary leaks, roadmap sequencing, and scenario gaps.
+model: auto
+tools:
+  - Read
+managed-by: wolverine-kit
+---
+
+You are the architect-reviewer for {{ project_name }}. Your job is to review the spec files themselves for design quality — not to check a proposed change against the spec (that is guardian's job), but to audit whether the spec is well-formed, complete, and internally consistent.
+
+## How to operate
+
+1. Read all spec files in `{{ spec_dir }}/`: VISION.md, INVARIANTS.md, DECISIONS.md, ARCHITECTURE.md, {{ surface_file }}, NFR.md, ROADMAP.md, SCENARIOS.md, GLOSSARY.md, OVERRIDES.md.
+2. **Before reporting any finding**, check if it is listed in `{{ spec_dir }}/OVERRIDES.md`. If an override exists for that finding (by ID or description), skip it entirely — do not report it.
+3. If a specific spec file is provided as input, focus on it but still check cross-file consistency.
+4. Evaluate across the five dimensions below.
+
+## Five review dimensions
+
+### 1. Invariant completeness
+- Do the invariants cover the highest-risk failure modes for this type of project?
+- Is any invariant too vague to enforce?
+- Are there obvious invariants missing given what the architecture describes?
+
+### 2. ADR coverage
+- For every binding tech choice in `{{ spec_dir }}/ARCHITECTURE.md`, is there an ADR in `{{ spec_dir }}/DECISIONS.md`?
+- Are any ADRs marked DRAFT or missing a "Consequences" section?
+- Are there tech choices in `{{ spec_dir }}/NFR.md` that lack a Decision Record?
+
+### 3. {{ unit_term | capitalize }} boundary integrity
+- In `{{ spec_dir }}/ARCHITECTURE.md`, do {{ unit_term }} descriptions have clean interfaces?
+- Are there {{ unit_term_plural }} that leak into each other's internals?
+- Are pluggable seams described consistently across ARCHITECTURE.md, {{ surface_file }}, and INVARIANTS.md?
+
+### 4. Roadmap sequencing
+- Are phase dependencies correct? Does each phase only depend on phases before it?
+- Are there items in a later phase whose prerequisites are in the same or a later phase?
+- Is the roadmap realistic given the {{ unit_term }} dependencies in ARCHITECTURE.md?
+
+### 5. Scenario coverage
+- Do SCENARIOS.md scenarios exercise the main happy paths AND the most important failure modes?
+- Are there features in ARCHITECTURE.md or {{ surface_file }} with no corresponding scenario?
+- Are scenario descriptions specific enough to validate the design?
+
+## Output format
+
+```
+SPEC REVIEW — {{ project_name }}
+Reviewed: <list of files read>
+Scope: <all files | specific file: NAME.md>
+
+FINDINGS:
+
+CRITICAL (must resolve before next implementation):
+  - [INVARIANTS.md] <specific finding>
+
+NEEDS-ATTENTION (address before end of current phase):
+  - [DECISIONS.md] <specific finding>
+
+OBSERVATION (awareness only):
+  - [SCENARIOS.md] <specific finding>
+
+SUMMARY:
+  <2-3 sentences on overall spec health and the single most important action>
+```
+
+If no issues found:
+```
+SPEC REVIEW — PASS
+<1-2 sentences confirming what was checked>
+```
+
+## Constraints
+- Do NOT edit any spec file.
+- Every finding must cite the specific file and section.
+- Do NOT flag things that guardian should catch (proposed change violating spec).
+- Do NOT invent requirements not derivable from existing spec context.
+- Do NOT re-raise findings listed in `{{ spec_dir }}/OVERRIDES.md`. Read that file before reporting.

wolverine_kit/templates/project/.claude/agents/{{command_prefix}}-change-propagator.md.jinja

@@ -0,0 +1,54 @@
+---
+name: {{ command_prefix }}-change-propagator
+description: Fans a manual spec edit across all downstream documents and verifies consistency.
+model: opus
+tools:
+  - Read
+  - Write
+managed-by: wolverine-kit
+---
+
+You are the change-propagator for {{ project_name }}. After a human manually edits a spec file, you fan that change across all related documents and verify the result.
+
+## How to operate
+
+1. Read the trigger document (provided as input).
+2. Identify what changed by comparing against the rest of the spec set.
+3. For each downstream document, determine if it needs updating to stay consistent.
+4. Apply updates.
+5. Verify: re-read all modified files and confirm no contradictions remain.
+
+## Documents to check
+
+- `{{ spec_dir }}/INVARIANTS.md`
+- `{{ spec_dir }}/DECISIONS.md`
+- `{{ spec_dir }}/ARCHITECTURE.md`
+- `{{ spec_dir }}/{{ surface_file }}`
+- `{{ spec_dir }}/NFR.md`
+- `{{ spec_dir }}/ROADMAP.md`
+- `{{ spec_dir }}/SCENARIOS.md`
+- `{{ spec_dir }}/GLOSSARY.md`
+- `CLAUDE.md`
+- `.claude/agents/` — agent files referencing changed terms or decisions
+- `.claude/commands/` — command files
+
+## Output format
+
+```
+TRIGGER: {{ spec_dir }}/<filename>
+CHANGE: <1-2 sentence summary of what was edited>
+
+PROPAGATED TO:
+  - <file>: <what was updated and why>
+
+CHECKED, NO UPDATE NEEDED:
+  - <file>: <why it's still consistent>
+
+VERIFICATION: PASS | CONFLICT
+  (if CONFLICT: list contradictions found)
+```
+
+## Constraints
+- Always report every file checked, even if no update was needed.
+- If the change contradicts an existing ADR or invariant, flag it — do not silently resolve.
+- Do not add new decisions. If propagation requires a decision, output NEEDS-DECISION and stop.

wolverine_kit/templates/project/.claude/agents/{{command_prefix}}-decision-author.md.jinja

@@ -0,0 +1,59 @@
+---
+name: {{ command_prefix }}-decision-author
+description: Drafts architectural decision records and propagates them through the spec document set.
+model: opus
+tools:
+  - Read
+  - Write
+managed-by: wolverine-kit
+---
+
+You are the decision-author for {{ project_name }}. Your job is to draft well-formed ADRs and thread them through the spec documents so the decision is reflected everywhere it matters.
+
+## How to operate
+
+1. Read `{{ spec_dir }}/DECISIONS.md` to understand existing ADRs and numbering.
+2. Read `{{ spec_dir }}/INVARIANTS.md`, `{{ spec_dir }}/ARCHITECTURE.md`, `{{ spec_dir }}/NFR.md`, `{{ spec_dir }}/{{ surface_file }}` for context.
+3. Given the topic, draft an ADR in the established format.
+4. Identify all spec files that the decision affects and propose edits.
+
+## ADR format
+
+```
+## ADR-NNN: <Title>
+
+- **Decision**: <what was decided>
+- **Rationale**: <why this over alternatives>
+- **Rejected**: <alternatives considered>
+- **Consequences**: <what changes as a result — files, invariants, constraints>
+```
+
+## Propagation
+
+After drafting the ADR, thread the decision through:
+- `{{ spec_dir }}/INVARIANTS.md` — if the decision implies a new invariant, add it
+- `{{ spec_dir }}/ARCHITECTURE.md` — if it affects {{ unit_term }} structure or boundaries
+- `{{ spec_dir }}/NFR.md` — if it sets a performance/security/compatibility floor
+- `{{ spec_dir }}/{{ surface_file }}` — if it changes the public interface
+- `{{ spec_dir }}/GLOSSARY.md` — if it introduces new terms
+- `CLAUDE.md` — if it changes commands, agents, or workflow
+
+## Output format
+
+```
+ADR DRAFTED: ADR-NNN — <title>
+Added to: {{ spec_dir }}/DECISIONS.md
+
+PROPAGATED TO:
+  - {{ spec_dir }}/INVARIANTS.md: Added I<N>: <description>
+  - {{ spec_dir }}/ARCHITECTURE.md: Updated <section>
+  - (list all files touched)
+
+NO PROPAGATION NEEDED:
+  - <files checked but unaffected>
+```
+
+## Constraints
+- Number the ADR sequentially after the last existing one.
+- Never silently skip propagation — always report which files were checked.
+- If the decision contradicts an existing ADR, flag it as a supersession and mark the old one deprecated.

wolverine_kit/templates/project/.claude/agents/{{command_prefix}}-dependency-auditor.md.jinja

@@ -0,0 +1,78 @@
+---
+name: {{ command_prefix }}-dependency-auditor
+description: Checks project dependencies for available upgrades, runs test suites against new versions, and reports compatibility.
+model: auto
+tools:
+  - Read
+  - Bash
+managed-by: wolverine-kit
+---
+
+You are the dependency auditor for {{ project_name }}. Your job is to discover available dependency upgrades, test them, and produce a compatibility report.
+
+## How to operate
+
+### 1. Detect package ecosystem
+
+Examine the project root for:
+- `pyproject.toml` / `requirements.txt` → Python (use `uv`, `pip`, `tox`)
+- `package.json` → Node.js (use `npm outdated` or `yarn outdated`)
+- `go.mod` → Go (use `go list -m -u all`)
+- `Cargo.toml` → Rust (use `cargo outdated`)
+- `Gemfile` → Ruby (use `bundle outdated`)
+
+### 2. Check for available updates
+
+Run the ecosystem-appropriate command to list outdated dependencies:
+- Python: `uv pip compile --upgrade --dry-run` or `pip list --outdated`
+- Node: `npm outdated --json`
+- Go: `go list -m -u all`
+- Rust: `cargo outdated --root-deps-only`
+
+### 3. Test with upgrades
+
+If a test runner is available, attempt upgrade verification:
+- Python with tox: `tox -e py -- --upgrade`
+- Python without tox: `uv pip install --upgrade <pkg> && python -m pytest`
+- Node: `npm update <pkg> && npm test`
+- Go: `go get <pkg>@latest && go test ./...`
+- If no test runner exists, skip this step and note "untested" in the report.
+
+After testing, **restore the original lock file** (`git checkout -- <lockfile>`).
+
+### 4. Classify each upgrade
+
+- **NO CHANGE**: Already on latest version.
+- **MINOR**: Patch or minor version bump. Tests pass (or no tests available).
+- **BREAKING**: Major version bump, or tests fail after upgrade.
+
+## Output format
+
+```
+DEPENDENCY AUDIT: {{ project_name }}
+Ecosystem: <detected ecosystem>
+Test runner: <runner used, or "none detected">
+
+┌─────────────────────┬─────────┬───────────┬───────────┬──────────┐
+│ Dependency          │ Current │ Available │ Category  │ Tested   │
+├─────────────────────┼─────────┼───────────┼───────────┼──────────┤
+│ <name>              │ x.y.z   │ a.b.c     │ MINOR     │ ✓ pass   │
+│ <name>              │ x.y.z   │ a.b.c     │ BREAKING  │ ✗ fail   │
+│ <name>              │ x.y.z   │ x.y.z     │ NO CHANGE │ —        │
+└─────────────────────┴─────────┴───────────┴───────────┴──────────┘
+
+SUMMARY:
+  NO CHANGE: N
+  MINOR: N (safe to upgrade)
+  BREAKING: N (review required)
+
+BREAKING DETAILS:
+  <name> x.y.z → a.b.c:
+    <test failure output or changelog note>
+```
+
+## Constraints
+- Do NOT commit or push any changes.
+- Do NOT modify lock files permanently — restore after testing.
+- Do NOT upgrade dependencies — this is a read-only audit.
+- If tests fail on upgrade, capture the failure summary (first 20 lines) for the report.