codd-dev 1.3.0__tar.gz → 1.5.1__tar.gz

{codd_dev-1.3.0 → codd_dev-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 1.3.0
+Version: 1.5.1
 Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
 Project-URL: Homepage, https://github.com/yohey-w/codd-dev
 Project-URL: Repository, https://github.com/yohey-w/codd-dev
@@ -37,7 +37,7 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <strong>CoDD — Coherence-Driven Development</strong><br>
-  <em>Keep AI-built systems coherent when requirements change.</em>
+  <em>The evidence engine for change management in AI-assisted development.</em>
 </p>
 
 <p align="center">
@@ -53,27 +53,26 @@ Description-Content-Type: text/markdown
 
 ---
 
-> *Harnesses tell agents how to work. CoDD keeps artifacts coherent.*
+> *When code changes, CoDD traces what's affected, checks what's violated, and produces the evidence trail for your merge decision.*
 
 ```
 pip install codd-dev
 ```
 
-**v1.2.0** — `init` / `scan` / `impact` are stable. `generate` / `implement` / `assemble` / `validate` / `extract` are alpha.
+**v1.5.0** — `init` / `scan` / `impact` are stable. `extract --ai` with baseline preset. `audit` / `policy` / `require` / `validate` are alpha. GitHub Action for CI integration.
 
 ---
 
 ## Why CoDD?
 
-AI can generate code from specs. But what happens when **requirements change mid-project?**
+AI can generate code. Humans can review PRs. But who tracks the **evidence trail** when requirements change?
 
-- Which design docs are affected?
-- Which tests need updating?
-- Which API contracts broke?
-- Did anyone forget to update the database migration?
+- Which design docs are now stale?
+- Which policy rules did the change violate?
+- What's the blast radius across the dependency graph?
+- Can the PM sign off on this merge with confidence?
 
-**Spec Kit** and **OpenSpec** answer *"how do I start?"*
-**CoDD** answers *"how do I keep going when things change?"*
+**CoDD is the evidence engine.** It builds the dependency graph, traces change impact, enforces enterprise policies, and produces a reviewer-ready audit pack — so your merge decision is based on evidence, not gut feeling.
 
 ## How It Works
 
@@ -145,145 +144,27 @@ codd assemble
 
 ```bash
 codd extract              # Reverse-engineer design docs from code
+codd require              # Infer requirements from code (what was built and why)
 codd plan --init          # Generate wave_config from extracted docs
 codd scan                 # Build dependency graph
 codd impact               # Change impact analysis
+codd audit --skip-review  # Full change review: validate + impact + policy
+codd measure              # Project health score (0-100)
 ```
 
-## 5-Minute Greenfield Demo — Spec to Working App
+## Demos
 
-37 lines of spec → 6 design docs (1,353 lines) → 102 code files (6,445 lines) → TypeScript strict build passes.
+### Greenfield — Spec to Working App
 
-### Step 1: Write your requirements
+37 lines of spec → 6 design docs (1,353 lines) → 102 code files (6,445 lines) → TypeScript strict build passes. No interactive AI chat — the entire workflow is a shell script.
 
-```text
-# TaskFlow — Personal Todo App
+Full walkthrough: [Harness as Code — A Guide to CoDD #1](https://zenn.dev/shio_shoppaize/articles/codd-greenfield-guide?locale=en)
 
-## Functional Requirements
-- Task CRUD: create, read, update, delete tasks
-- Each task has: title, description (optional), due date (optional),
-  priority (low/medium/high), completed status
-- Task list with filtering by: status (all/active/completed), priority
-- Local state management (no backend, localStorage)
+### Brownfield — Change Impact Analysis
 
-## UI Requirements
-- Single-page app with responsive layout (mobile-first)
-- Dark theme with accent color (#3b82f6)
-- Floating action button opens a modal form
-- Toast notifications on create/update/delete
-- Keyboard shortcuts: Enter to submit, Escape to close modal
+2 lines changed in requirements → `codd impact` identifies 6 out of 7 design docs affected. Green band: AI auto-updates. Amber band: human reviews. You know exactly what to fix before anything breaks.
 
-## Constraints
-- Next.js 15 App Router with React Server Components
-- Tailwind CSS
-- TypeScript strict mode
-- Deploy-ready as static export
-```
-
-### Step 2: Run the pipeline
-
-```bash
-pip install codd-dev
-codd init --requirements spec.md
-codd plan --init                          # AI designs the wave structure
-
-waves=$(codd plan --waves)                # → 4
-for wave in $(seq 1 $waves); do
-  codd generate --wave $wave              # design docs, wave by wave
-done
-
-codd validate                             # quality gate
-
-sprints=$(codd plan --sprints)            # → 17
-for sprint in $(seq 1 $sprints); do
-  codd implement --sprint $sprint         # code from design docs
-done
-
-codd assemble                             # integrate into buildable project
-npm run build                             # TypeScript strict, zero errors
-```
-
-No interactive AI chat at any step. Every AI call goes through `claude --print` — prompt in, text out. **Harness as Code**: the entire workflow is a shell script.
-
-### Step 3: Model role separation
-
-```bash
-# Design docs — needs judgment, use Opus
-codd generate --wave 1 --ai-cmd 'claude --print --model claude-opus-4-6 --tools ""'
-
-# Code generation — needs volume, use Codex (or Sonnet)
-codd implement --sprint 1 --ai-cmd 'codex --full-auto -q'
-```
-
-## 5-Minute Brownfield Demo — Change Impact Analysis
-
-Already have a codebase? CoDD tracks what's affected when requirements change.
-
-### Step 1: Write requirements and generate design docs
-
-```text
-# TaskFlow — Requirements
-
-## Functional Requirements
-- User auth (email + Google OAuth)
-- Workspace management (teams, roles, invites)
-- Task CRUD with assignees, labels, due dates
-- Real-time updates (WebSocket)
-- File attachments (S3)
-- Notification system (in-app + email)
-
-## Constraints
-- Next.js + Prisma + PostgreSQL
-- Row-level security for workspace isolation
-- All API endpoints rate-limited
-```
-
-```bash
-codd init --requirements spec.txt
-codd plan --init
-waves=$(codd plan --waves)
-for wave in $(seq 1 $waves); do codd generate --wave $wave; done
-codd scan
-```
-
-```
-Scan complete:
-  Documents with frontmatter: 7
-  Graph: 7 nodes, 15 edges
-```
-
-### Step 2: Change requirements mid-project
-
-Your PM asks for SSO and audit logging. Add to `docs/requirements/requirements.md`:
-
-```text
-## Additional Requirements (v1.1)
-- SAML SSO (enterprise customers)
-- Audit logging (record & export all operations)
-```
-
-```bash
-codd impact    # detects uncommitted changes automatically
-```
-
-```
-# CoDD Impact Report
-
-## Green Band (high confidence, auto-propagate)
-| Target                  | Depth | Confidence |
-|-------------------------|-------|------------|
-| design:system-design    | 1     | 0.90       |
-| design:api-design       | 1     | 0.90       |
-| detail:db-design        | 2     | 0.90       |
-| detail:auth-design      | 2     | 0.90       |
-
-## Amber Band (must review)
-| Target                  | Depth | Confidence |
-|-------------------------|-------|------------|
-| test:test-strategy      | 2     | 0.90       |
-```
-
-**2 lines changed → 6 out of 7 docs affected.** Green band: AI auto-updates. Amber: human reviews. You know exactly what to fix before anything breaks.
+Deep dive: [CoDD deep-dive](https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence?locale=en)
 
 ## Wave-Based Generation
 
@@ -381,6 +262,15 @@ All other commands (`scan`, `impact`, `generate`, etc.) automatically discover w
 
 Already have a codebase? CoDD provides a full brownfield workflow — from code extraction to design doc reconstruction.
 
+### AI-Powered Extraction (--ai)
+
+> **Note on presets**: `codd extract --ai` ships with a **baseline** extraction prompt. The extraction quality in published benchmarks (F1 0.953+) was achieved with a tuned preset and internal evaluation dataset — not the public baseline. The baseline uses the same workflow and output format, but results will vary depending on your codebase and prompt. Use `--prompt-file` to supply your own tuned prompt.
+
+```bash
+codd extract --ai                        # Uses built-in baseline preset
+codd extract --ai --prompt-file my.md    # Uses your custom prompt
+```
+
 ### Step 1: Extract structure from code
 
 `codd extract` reverse-engineers design documents from your source code. No AI required — pure static analysis.
@@ -454,6 +344,118 @@ codd impact
 | `codd propagate` | Experimental | Reverse-propagate source code changes to design docs |
 | `codd review` | Experimental | AI-powered artifact quality evaluation (LLM-as-Judge) |
 | `codd extract` | **Alpha** | Reverse-engineer design docs from existing code |
+| `codd require` | **Alpha** | Infer requirements from existing codebase (brownfield) |
+| `codd audit` | **Alpha** | Consolidated change review pack (validate + impact + policy + review) |
+| `codd policy` | **Alpha** | Enterprise policy checker (forbidden/required patterns in source code) |
+| `codd measure` | **Alpha** | Project health metrics (graph, coverage, quality, health score 0-100) |
+| `codd mcp-server` | **Alpha** | MCP server for AI tool integration (stdio, zero dependencies) |
+
+## CI Integration (GitHub Action)
+
+Run CoDD audit on every pull request. The action posts a comment with verdict (APPROVE / CONDITIONAL / REJECT), validation results, policy violations, and impact analysis.
+
+### Quick Setup
+
+Add `.github/workflows/codd.yml` to your project:
+
+```yaml
+name: CoDD Audit
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: yohey-w/codd-dev@main
+        with:
+          diff-target: origin/${{ github.base_ref }}
+          skip-review: "true"  # Set to "false" to enable AI review
+```
+
+### Action Inputs
+
+| Input | Default | Description |
+|-------|---------|-------------|
+| `diff-target` | `origin/main` | Git ref to diff against |
+| `skip-review` | `true` | Skip AI review phase (faster, no AI cost) |
+| `python-version` | `3.12` | Python version |
+| `codd-version` | latest | Specific version (e.g., `>=1.3.0`) |
+| `post-comment` | `true` | Post results as PR comment |
+
+### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `verdict` | `APPROVE`, `CONDITIONAL`, or `REJECT` |
+| `risk-level` | `LOW`, `MEDIUM`, or `HIGH` |
+| `report-json` | Path to the JSON audit report |
+
+### Enterprise Policies
+
+Define source code policies in your `codd.yaml`:
+
+```yaml
+policies:
+  - id: SEC-001
+    description: "No hardcoded passwords"
+    severity: CRITICAL
+    kind: forbidden
+    pattern: 'password\s*=\s*[''"]'
+    glob: "*.py"
+
+  - id: LOG-001
+    description: "All modules must import logging"
+    severity: WARNING
+    kind: required
+    pattern: "import logging"
+    glob: "*.py"
+```
+
+The policy checker runs as part of `codd audit` and independently via `codd policy`. Critical violations cause REJECT; warnings cause CONDITIONAL.
+
+## MCP Server
+
+CoDD exposes its tools via the [Model Context Protocol](https://modelcontextprotocol.io/) for direct AI tool integration. Zero external dependencies — works with any MCP-compatible client.
+
+```bash
+codd mcp-server --project /path/to/your/project
+```
+
+### Claude Code Configuration
+
+Add to `~/.claude/claude_code_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "codd": {
+      "command": "codd",
+      "args": ["mcp-server", "--project", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `codd_validate` | Check frontmatter integrity and graph consistency |
+| `codd_impact` | Analyze change impact for a given node or file |
+| `codd_policy` | Check source code against enterprise policy rules |
+| `codd_audit` | Consolidated change review (validate + impact + policy) |
+| `codd_scan` | Build dependency graph from design documents |
+| `codd_measure` | Project health metrics (graph, coverage, quality, health score) |
 
 ## Claude Code Integration
 
@@ -618,7 +620,7 @@ CoDD dogfoods itself. The `.codd/` directory contains CoDD's own config, and `co
 codd init --config-dir .codd --project-name "codd-dev" --language "python"
 codd extract          # 15 modules → design docs with dependency frontmatter
 codd scan             # 49 nodes, 83 edges
-codd verify           # mypy + pytest (127/127 tests pass)
+codd verify           # mypy + pytest (434 tests pass)
 ```
 
 If CoDD can't manage itself, it shouldn't manage your project.
@@ -635,15 +637,22 @@ If CoDD can't manage itself, it shouldn't manage your project.
 - [x] `codd review` — AI-powered quality evaluation with review-driven regeneration loop
 - [x] `--feedback` flag — feed review results back into generate/restore/propagate
 - [x] `codd verify` — language-agnostic verification (Python: mypy + pytest, TypeScript: tsc + jest)
+- [x] `codd require` — infer requirements from existing codebase with confidence tags
+- [x] `codd audit` — consolidated change review pack (validate + impact + policy + review)
+- [x] `codd policy` — enterprise policy checker (forbidden/required patterns)
+- [x] `codd measure` — project health metrics (graph, coverage, quality, score 0-100)
+- [x] GitHub Action — CI integration for PR audit with auto-commenting
+- [x] MCP Server — stdio JSON-RPC server for AI tool integration
+- [x] Plugin system — extensible require prompts (tags, evidence format, output sections)
 - [ ] Multi-harness integration examples (Claude Code, Copilot, Cursor)
 - [ ] VS Code extension for impact visualization
 
 ## Articles
 
-- [dev.to (English): Harness as Code — Treating AI Workflows Like Infrastructure](https://dev.to/yohey-w/harness-as-code-treating-ai-workflows-like-infrastructure-27ni)
-- [dev.to (English): What Happens After "Spec First"](https://dev.to/yohey-w/codd-coherence-driven-development-what-happens-after-spec-first-514f)
-- [Zenn (Japanese): Harness as Code — CoDD活用ガイド #1 spec → 設計書 → コード](https://zenn.dev/shio_shoppaize/articles/codd-greenfield-guide)
-- [Zenn (Japanese): CoDD deep-dive](https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence)
+- [dev.to: Harness as Code — Treating AI Workflows Like Infrastructure](https://dev.to/yohey-w/harness-as-code-treating-ai-workflows-like-infrastructure-27ni)
+- [dev.to: What Happens After "Spec First"](https://dev.to/yohey-w/codd-coherence-driven-development-what-happens-after-spec-first-514f)
+- [Zenn: Harness as Code — A Guide to CoDD #1 spec → design → code](https://zenn.dev/shio_shoppaize/articles/codd-greenfield-guide?locale=en)
+- [Zenn: CoDD deep-dive](https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence?locale=en)
 
 ## License