codd-dev 1.6.0__tar.gz → 1.7.1__tar.gz

{codd_dev-1.6.0 → codd_dev-1.7.1}/.gitignore

@@ -8,7 +8,7 @@ build/
 *.egg
 
 # Virtual environments
-.venv/
+.venv*/
 venv/
 
 # IDE

{codd_dev-1.6.0 → codd_dev-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 1.6.0
+Version: 1.7.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
@@ -49,7 +49,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <a href="README_ja.md">日本語</a> | English
+  <a href="README_ja.md">日本語</a> | English | <a href="README_zh.md">中文</a>
 </p>
 
 ---
@@ -60,31 +60,31 @@ Description-Content-Type: text/markdown
 pip install codd-dev
 ```
 
-**v1.5.0** — `init` / `scan` / `impact` are stable. `extract --ai` with baseline preset. `audit` / `policy` / `require` / `validate` are alpha. GitHub Action for CI integration.
+**v1.7.0** — `init` / `scan` / `impact` are stable. `propagate` traces code changes to downstream design docs and doc-to-doc changes via CEG graph. `extract --ai` with baseline preset. Custom `node_id` prefixes via `codd.yaml`. GitHub Action for CI integration.
 
 ---
 
 ## Why CoDD?
 
-AI can generate code. Humans can review PRs. But who tracks the **evidence trail** when requirements change?
+AI can generate specs. But **what happens when upstream changes?**
 
-- 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?
+Every spec-first tool stops at creation. CoDD starts there. When a requirement changes, code is updated, or a design assumption shifts, CoDD **automatically propagates the change downstream** — updating affected design docs, flagging stale artifacts, and producing an evidence trail.
 
-**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.
+```
+Requirement changes → codd impact identifies 6 affected docs
+Code changes        → codd propagate updates downstream designs
+Design changes      → CEG graph traces all dependent artifacts
+```
+
+No other tool does this. spec-kit, Kiro, and cc-sdd create docs. **CoDD keeps them coherent.**
 
 ## How It Works
 
 ```
 Requirements (human)  →  Design docs (AI)  →  Code & tests (AI)
-                              ↑
-                    codd scan builds the
-                     dependency graph
-                              ↓
-            Something changes? codd impact tells you
-             exactly what's affected — automatically.
+         ↕                     ↕                     ↕
+     codd impact         codd propagate        codd extract
+    (what changed?)    (update downstream)   (reverse-engineer)
 ```
 
 ### The Three Layers
@@ -155,6 +155,54 @@ codd measure              # Project health score (0-100)
 
 ## Demos
 
+### Reproducible E2E Demo — 3 Propagation Patterns
+
+The following demo is pinned to commit [`d7d9f45`](https://github.com/yohey-w/codd-dev/commit/d7d9f45). You can reproduce the full cycle locally.
+
+**Setup:**
+```bash
+pip install codd-dev>=1.6.0
+mkdir demo && cd demo && git init
+cat > spec.txt << 'EOF'
+TaskFlow — Requirements
+- User authentication (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)
+EOF
+codd init --project-name "taskflow" --language "typescript" --requirements spec.txt
+```
+
+**Pattern 1 — Source → Doc** (spec → design docs):
+```bash
+codd plan --init
+for wave in $(seq 1 $(codd plan --waves)); do codd generate --wave $wave; done
+codd validate        # Expected: PASS, 0 errors
+codd scan            # Expected: 17 nodes, 30+ edges
+```
+
+**Pattern 2 — Doc → Doc** (requirement change → downstream update):
+```bash
+# Edit requirements: add "SSO (SAML 2.0)" to auth
+codd impact          # Expected: 6/7 design docs in Green/Amber band
+
+# Regenerate affected waves (propagate is for code→doc only)
+codd generate --wave 1 --force   # Re-derive acceptance criteria from updated requirements
+codd generate --wave 2 --force   # Re-derive system design from updated Wave 1
+# Repeat for each affected wave in dependency order
+```
+
+**Pattern 3 — Doc → Doc via CEG** (code change → design update):
+```bash
+# Modify source code in auth module
+codd propagate       # Expected: identifies auth-design, system-design as affected
+codd propagate --update  # AI updates affected design docs from code diff
+```
+
+**Expected output**: 20-line spec → 17 design artifacts (5,100+ lines) → downstream propagation keeps all docs coherent after changes. Pattern 3 (CEG-based propagation) is novel — no other tool traces code changes back through the dependency graph to update design documents.
+
 ### Greenfield — Spec to Working App
 
 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.
@@ -208,6 +256,27 @@ The `modules` field enables reverse traceability: when source code changes, `cod
 
 `codd/scan/` is a cache — regenerated on every `codd scan`.
 
+## Custom Node Prefixes
+
+By default, `node_id` values must use one of the built-in prefixes (`design:`, `req:`, `doc:`, `module:`, etc.). To use CoDD for non-software domains (knowledge bases, review documents, prompt management), add custom prefixes in `codd.yaml`:
+
+```yaml
+# codd.yaml
+prefixes:
+  - knowledge
+  - schema
+  - review
+  - prompt
+```
+
+Custom prefixes are **merged with** built-in defaults — you don't need to re-list `design`, `req`, etc. Prefix names must be lowercase letters and underscores only (`[a-z_]+`).
+
+```yaml
+# Now valid in frontmatter:
+codd:
+  node_id: "knowledge:domain-model"
+```
+
 ## AI Model Configuration
 
 CoDD calls an external AI CLI for document generation. The default is Claude Opus:
@@ -342,17 +411,39 @@ codd impact
 | `codd generate` | Experimental | Generate design docs in Wave order (greenfield) |
 | `codd restore` | Experimental | Reconstruct design docs from extracted facts (brownfield) |
 | `codd plan` | Experimental | Wave execution status (`--init` supports brownfield fallback) |
-| `codd verify` | Experimental | V-Model verification |
+| `codd verify` | Experimental (Pro) | V-Model verification |
 | `codd implement` | Experimental | Design-to-code generation |
-| `codd propagate` | Experimental | Reverse-propagate source code changes to design docs |
-| `codd review` | Experimental | AI-powered artifact quality evaluation (LLM-as-Judge) |
+| `codd propagate` | **Alpha** | Propagate code/doc changes downstream to affected design docs |
+| `codd review` | Experimental (Pro) | 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 audit` | **Alpha** (Pro) | 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) |
 
+## OSS / Pro Split
+
+CoDD v1.6.0 introduced a clean OSS/Pro boundary via a bridge pattern.
+
+**OSS (MIT, free)** — everything you need to keep docs coherent:
+
+`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `mcp-server`
+
+**Pro (private, paid)** — enterprise review and verification:
+
+`review` · `verify` · `audit` · `risk`
+
+```bash
+# OSS only
+pip install codd-dev
+
+# Add Pro extensions
+pip install "codd-pro @ git+ssh://git@github.com/yohey-w/codd-pro.git"
+```
+
+When `codd-pro` is installed, Pro implementations automatically override OSS fallbacks via entry-points plugin discovery. When it's not installed, Pro commands show a migration message and exit gracefully. No configuration needed.
+
 ## 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.
@@ -586,7 +677,7 @@ All major spec-driven tools focus on **creating** design documents. None address
 | Spec notation | Markdown + 40 extensions | EARS notation | Quality gates + git worktree | Frontmatter `depends_on` |
 | Harness lock-in | GitHub Copilot | Kiro IDE | Claude Code | **Any agent / IDE** |
 
-In short: spec-kit, Kiro, and cc-sdd answer *"how do I create specs?"* CoDD answers *"how do I keep specs, code, and tests coherent when requirements change?"*
+In short: spec-kit, Kiro, and cc-sdd answer *"how do I create specs?"* CoDD answers *"when something changes upstream, how do I automatically update everything downstream?"*
 
 ## Comparison
 
@@ -656,8 +747,17 @@ If CoDD can't manage itself, it shouldn't manage your project.
 - [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: Harness as Code — A Guide to CoDD #2 Brownfield](https://zenn.dev/shio_shoppaize/articles/shogun-codd-brownfield?locale=en)
+- [Zenn: Harness as Code — A Guide to CoDD #3 Bug Fixing with CoDD extract (SWE-bench)](https://zenn.dev/shio_shoppaize/articles/codd-swebench-pilot?locale=en)
 - [Zenn: CoDD deep-dive](https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence?locale=en)
 
+## Sponsors
+
+<a href="https://github.com/sponsors/yohey-w">
+  <img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge&logo=github-sponsors" alt="Sponsor">
+</a>
+
+Your sponsorship keeps CoDD free and funds continued development. See [sponsor tiers](https://github.com/sponsors/yohey-w).
+
 ## License
 
 MIT

{codd_dev-1.6.0 → codd_dev-1.7.1}/README.md

@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-  <a href="README_ja.md">日本語</a> | English
+  <a href="README_ja.md">日本語</a> | English | <a href="README_zh.md">中文</a>
 </p>
 
 ---
@@ -22,31 +22,31 @@
 pip install codd-dev
 ```
 
-**v1.5.0** — `init` / `scan` / `impact` are stable. `extract --ai` with baseline preset. `audit` / `policy` / `require` / `validate` are alpha. GitHub Action for CI integration.
+**v1.7.0** — `init` / `scan` / `impact` are stable. `propagate` traces code changes to downstream design docs and doc-to-doc changes via CEG graph. `extract --ai` with baseline preset. Custom `node_id` prefixes via `codd.yaml`. GitHub Action for CI integration.
 
 ---
 
 ## Why CoDD?
 
-AI can generate code. Humans can review PRs. But who tracks the **evidence trail** when requirements change?
+AI can generate specs. But **what happens when upstream changes?**
 
-- 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?
+Every spec-first tool stops at creation. CoDD starts there. When a requirement changes, code is updated, or a design assumption shifts, CoDD **automatically propagates the change downstream** — updating affected design docs, flagging stale artifacts, and producing an evidence trail.
 
-**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.
+```
+Requirement changes → codd impact identifies 6 affected docs
+Code changes        → codd propagate updates downstream designs
+Design changes      → CEG graph traces all dependent artifacts
+```
+
+No other tool does this. spec-kit, Kiro, and cc-sdd create docs. **CoDD keeps them coherent.**
 
 ## How It Works
 
 ```
 Requirements (human)  →  Design docs (AI)  →  Code & tests (AI)
-                              ↑
-                    codd scan builds the
-                     dependency graph
-                              ↓
-            Something changes? codd impact tells you
-             exactly what's affected — automatically.
+         ↕                     ↕                     ↕
+     codd impact         codd propagate        codd extract
+    (what changed?)    (update downstream)   (reverse-engineer)
 ```
 
 ### The Three Layers
@@ -117,6 +117,54 @@ codd measure              # Project health score (0-100)
 
 ## Demos
 
+### Reproducible E2E Demo — 3 Propagation Patterns
+
+The following demo is pinned to commit [`d7d9f45`](https://github.com/yohey-w/codd-dev/commit/d7d9f45). You can reproduce the full cycle locally.
+
+**Setup:**
+```bash
+pip install codd-dev>=1.6.0
+mkdir demo && cd demo && git init
+cat > spec.txt << 'EOF'
+TaskFlow — Requirements
+- User authentication (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)
+EOF
+codd init --project-name "taskflow" --language "typescript" --requirements spec.txt
+```
+
+**Pattern 1 — Source → Doc** (spec → design docs):
+```bash
+codd plan --init
+for wave in $(seq 1 $(codd plan --waves)); do codd generate --wave $wave; done
+codd validate        # Expected: PASS, 0 errors
+codd scan            # Expected: 17 nodes, 30+ edges
+```
+
+**Pattern 2 — Doc → Doc** (requirement change → downstream update):
+```bash
+# Edit requirements: add "SSO (SAML 2.0)" to auth
+codd impact          # Expected: 6/7 design docs in Green/Amber band
+
+# Regenerate affected waves (propagate is for code→doc only)
+codd generate --wave 1 --force   # Re-derive acceptance criteria from updated requirements
+codd generate --wave 2 --force   # Re-derive system design from updated Wave 1
+# Repeat for each affected wave in dependency order
+```
+
+**Pattern 3 — Doc → Doc via CEG** (code change → design update):
+```bash
+# Modify source code in auth module
+codd propagate       # Expected: identifies auth-design, system-design as affected
+codd propagate --update  # AI updates affected design docs from code diff
+```
+
+**Expected output**: 20-line spec → 17 design artifacts (5,100+ lines) → downstream propagation keeps all docs coherent after changes. Pattern 3 (CEG-based propagation) is novel — no other tool traces code changes back through the dependency graph to update design documents.
+
 ### Greenfield — Spec to Working App
 
 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.
@@ -170,6 +218,27 @@ The `modules` field enables reverse traceability: when source code changes, `cod
 
 `codd/scan/` is a cache — regenerated on every `codd scan`.
 
+## Custom Node Prefixes
+
+By default, `node_id` values must use one of the built-in prefixes (`design:`, `req:`, `doc:`, `module:`, etc.). To use CoDD for non-software domains (knowledge bases, review documents, prompt management), add custom prefixes in `codd.yaml`:
+
+```yaml
+# codd.yaml
+prefixes:
+  - knowledge
+  - schema
+  - review
+  - prompt
+```
+
+Custom prefixes are **merged with** built-in defaults — you don't need to re-list `design`, `req`, etc. Prefix names must be lowercase letters and underscores only (`[a-z_]+`).
+
+```yaml
+# Now valid in frontmatter:
+codd:
+  node_id: "knowledge:domain-model"
+```
+
 ## AI Model Configuration
 
 CoDD calls an external AI CLI for document generation. The default is Claude Opus:
@@ -304,17 +373,39 @@ codd impact
 | `codd generate` | Experimental | Generate design docs in Wave order (greenfield) |
 | `codd restore` | Experimental | Reconstruct design docs from extracted facts (brownfield) |
 | `codd plan` | Experimental | Wave execution status (`--init` supports brownfield fallback) |
-| `codd verify` | Experimental | V-Model verification |
+| `codd verify` | Experimental (Pro) | V-Model verification |
 | `codd implement` | Experimental | Design-to-code generation |
-| `codd propagate` | Experimental | Reverse-propagate source code changes to design docs |
-| `codd review` | Experimental | AI-powered artifact quality evaluation (LLM-as-Judge) |
+| `codd propagate` | **Alpha** | Propagate code/doc changes downstream to affected design docs |
+| `codd review` | Experimental (Pro) | 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 audit` | **Alpha** (Pro) | 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) |
 
+## OSS / Pro Split
+
+CoDD v1.6.0 introduced a clean OSS/Pro boundary via a bridge pattern.
+
+**OSS (MIT, free)** — everything you need to keep docs coherent:
+
+`init` · `scan` · `impact` · `generate` · `restore` · `propagate` · `extract` · `require` · `plan` · `validate` · `measure` · `policy` · `mcp-server`
+
+**Pro (private, paid)** — enterprise review and verification:
+
+`review` · `verify` · `audit` · `risk`
+
+```bash
+# OSS only
+pip install codd-dev
+
+# Add Pro extensions
+pip install "codd-pro @ git+ssh://git@github.com/yohey-w/codd-pro.git"
+```
+
+When `codd-pro` is installed, Pro implementations automatically override OSS fallbacks via entry-points plugin discovery. When it's not installed, Pro commands show a migration message and exit gracefully. No configuration needed.
+
 ## 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.
@@ -548,7 +639,7 @@ All major spec-driven tools focus on **creating** design documents. None address
 | Spec notation | Markdown + 40 extensions | EARS notation | Quality gates + git worktree | Frontmatter `depends_on` |
 | Harness lock-in | GitHub Copilot | Kiro IDE | Claude Code | **Any agent / IDE** |
 
-In short: spec-kit, Kiro, and cc-sdd answer *"how do I create specs?"* CoDD answers *"how do I keep specs, code, and tests coherent when requirements change?"*
+In short: spec-kit, Kiro, and cc-sdd answer *"how do I create specs?"* CoDD answers *"when something changes upstream, how do I automatically update everything downstream?"*
 
 ## Comparison
 
@@ -618,8 +709,17 @@ If CoDD can't manage itself, it shouldn't manage your project.
 - [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: Harness as Code — A Guide to CoDD #2 Brownfield](https://zenn.dev/shio_shoppaize/articles/shogun-codd-brownfield?locale=en)
+- [Zenn: Harness as Code — A Guide to CoDD #3 Bug Fixing with CoDD extract (SWE-bench)](https://zenn.dev/shio_shoppaize/articles/codd-swebench-pilot?locale=en)
 - [Zenn: CoDD deep-dive](https://zenn.dev/shio_shoppaize/articles/shogun-codd-coherence?locale=en)
 
+## Sponsors
+
+<a href="https://github.com/sponsors/yohey-w">
+  <img src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge&logo=github-sponsors" alt="Sponsor">
+</a>
+
+Your sponsorship keeps CoDD free and funds continued development. See [sponsor tiers](https://github.com/sponsors/yohey-w).
+
 ## License
 
 MIT

{codd_dev-1.6.0 → codd_dev-1.7.1}/codd/assembler.py

@@ -6,8 +6,11 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+import warnings
+
 import codd.generator as generator_module
 from codd.generator import _load_project_config, _normalize_conventions
+from codd.implementer import get_task_slugs_by_sprint
 from codd.scanner import _extract_frontmatter, build_document_node_path_map
 
 
@@ -79,7 +82,11 @@ def _collect_design_documents(project_root: Path, config: dict[str, Any]) -> lis
 
 
 def _collect_generated_fragments(project_root: Path, config: dict[str, Any]) -> list[dict[str, str]]:
-    """Collect all generated code fragments from src/generated/sprint_N/."""
+    """Collect all generated code fragments from src/generated/sprint_N/.
+
+    Cross-references against the implementation plan to detect orphan fragments
+    from renamed or deleted tasks. Orphans are excluded with a warning.
+    """
     source_dirs = config.get("scan", {}).get("source_dirs", ["src/"])
     generated_base = None
     for src_dir in source_dirs:
@@ -94,19 +101,44 @@ def _collect_generated_fragments(project_root: Path, config: dict[str, Any]) ->
     if not generated_base.is_dir():
         return []
 
+    # Load valid task slugs from implementation plan for orphan detection
+    valid_slugs = get_task_slugs_by_sprint(project_root)
+
+    code_extensions = (".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".java", ".css")
     fragments = []
     for sprint_dir in sorted(generated_base.iterdir()):
         if not sprint_dir.is_dir() or not sprint_dir.name.startswith("sprint_"):
             continue
+
+        # Identify orphan task directories
+        orphan_dirs: set[str] = set()
+        if valid_slugs and sprint_dir.name in valid_slugs:
+            expected = valid_slugs[sprint_dir.name]
+            for child in sprint_dir.iterdir():
+                if child.is_dir() and child.name not in expected:
+                    orphan_dirs.add(child.name)
+                    warnings.warn(
+                        f"Orphan fragment directory '{sprint_dir.name}/{child.name}' "
+                        f"does not match any task in the implementation plan. Skipping.",
+                        stacklevel=2,
+                    )
+
         for code_file in sorted(sprint_dir.rglob("*")):
-            if code_file.is_file() and code_file.suffix in (".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".java", ".css"):
-                rel_path = code_file.relative_to(project_root)
-                content = code_file.read_text(encoding="utf-8")
-                fragments.append({
-                    "sprint_dir": sprint_dir.name,
-                    "path": str(rel_path),
-                    "content": content,
-                })
+            if not code_file.is_file() or code_file.suffix not in code_extensions:
+                continue
+
+            # Skip files under orphan task directories
+            rel_to_sprint = code_file.relative_to(sprint_dir)
+            if rel_to_sprint.parts and rel_to_sprint.parts[0] in orphan_dirs:
+                continue
+
+            rel_path = code_file.relative_to(project_root)
+            content = code_file.read_text(encoding="utf-8")
+            fragments.append({
+                "sprint_dir": sprint_dir.name,
+                "path": str(rel_path),
+                "content": content,
+            })
 
     return fragments