contract-driven-delivery 2.0.2 → 2.0.7

package/assets/code-map/python_scanner.py

@@ -0,0 +1,167 @@
+"""cdd-kit Python AST scanner — batch mode, NDJSON output."""
+from __future__ import annotations
+
+import ast
+import json
+import os
+import sys
+import traceback
+
+
+def _check_python_version() -> None:
+    if sys.version_info < (3, 9):
+        print(
+            f"cdd-kit: python interpreter is {sys.version_info.major}.{sys.version_info.minor} "
+            f"(need 3.9+ for ast.unparse); skipping .py files",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+
+
+def _rel_path(abs_path: str, repo_root: str) -> str:
+    try:
+        rel = os.path.relpath(abs_path, repo_root)
+    except ValueError:
+        # Windows: different drive — use abs_path
+        rel = abs_path
+    return rel.replace("\\", "/")
+
+
+def _is_all_caps(name: str) -> bool:
+    """Return True if name matches /^[A-Z][A-Z0-9_]*$/ and contains at least one letter."""
+    if not name:
+        return False
+    if not name[0].isupper():
+        return False
+    if not all(c.isupper() or c.isdigit() or c == '_' for c in name):
+        return False
+    return any(c.isalpha() for c in name)
+
+
+def scan_file(abs_path: str, repo_root: str) -> dict:
+    src = open(abs_path, encoding="utf-8").read()
+    total_lines = len(src.splitlines()) if src else 0
+
+    # Check first 4KB for binary content
+    head = src[:4096]
+    if '\x00' in head:
+        return {
+            "path": _rel_path(abs_path, repo_root),
+            "ok": False,
+            "error": "binary file (null bytes detected)",
+        }
+
+    try:
+        tree = ast.parse(src, filename=abs_path)
+    except SyntaxError as exc:
+        return {
+            "path": _rel_path(abs_path, repo_root),
+            "ok": False,
+            "error": str(exc),
+        }
+    except UnicodeDecodeError as exc:
+        return {
+            "path": _rel_path(abs_path, repo_root),
+            "ok": False,
+            "error": str(exc),
+        }
+
+    imports: list[dict] = []
+    constants: list[dict] = []
+    classes: list[dict] = []
+    functions: list[dict] = []
+
+    for node in ast.iter_child_nodes(tree):
+        # ── imports ──────────────────────────────────────────────────────────
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                imports.append({
+                    "module": alias.name,
+                    "items": [],
+                    "line": node.lineno,
+                })
+        elif isinstance(node, ast.ImportFrom):
+            level = node.level or 0
+            module_name = ("." * level) + (node.module or "")
+            items = [a.asname if a.asname else a.name for a in node.names]
+            imports.append({
+                "module": module_name,
+                "items": items,
+                "line": node.lineno,
+            })
+
+        # ── constants ────────────────────────────────────────────────────────
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name) and _is_all_caps(target.id):
+                    constants.append({"name": target.id, "line": node.lineno})
+        elif isinstance(node, ast.AnnAssign):
+            if isinstance(node.target, ast.Name) and _is_all_caps(node.target.id):
+                constants.append({"name": node.target.id, "line": node.lineno})
+
+        # ── classes ──────────────────────────────────────────────────────────
+        elif isinstance(node, ast.ClassDef):
+            methods: list[dict] = []
+            for sub in ast.iter_child_nodes(node):
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    methods.append({
+                        "name": sub.name,
+                        "lines": [sub.lineno, sub.end_lineno],
+                        "async": isinstance(sub, ast.AsyncFunctionDef),
+                    })
+            classes.append({
+                "name": node.name,
+                "lines": [node.lineno, node.end_lineno],
+                "methods": methods,
+            })
+
+        # ── functions ────────────────────────────────────────────────────────
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            decos: list[str] = []
+            for d in node.decorator_list:
+                try:
+                    decos.append(ast.unparse(d))
+                except Exception:
+                    decos.append("?")
+            functions.append({
+                "name": node.name,
+                "lines": [node.lineno, node.end_lineno],
+                "decorators": decos,
+                "async": isinstance(node, ast.AsyncFunctionDef),
+            })
+
+    return {
+        "path": _rel_path(abs_path, repo_root),
+        "total_lines": total_lines,
+        "imports": imports,
+        "constants": constants,
+        "classes": classes,
+        "functions": functions,
+        "ok": True,
+    }
+
+
+def main() -> None:
+    _check_python_version()
+
+    import argparse
+    parser = argparse.ArgumentParser(description="cdd-kit Python AST scanner")
+    parser.add_argument("--batch-file", required=True, help="File containing one abs path per line")
+    parser.add_argument("--repo-root", required=True, help="Repository root for relative paths")
+    args = parser.parse_args()
+
+    with open(args.batch_file, encoding="utf-8") as fh:
+        paths = [line.rstrip("\n") for line in fh if line.strip()]
+
+    for abs_path in paths:
+        try:
+            result = scan_file(abs_path, args.repo_root)
+        except Exception:
+            tb = traceback.format_exc()
+            print(json.dumps({"fatal": tb}), file=sys.stderr)
+            sys.exit(2)
+        print(json.dumps(result, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/contract-driven-delivery/references/code-map-protocol.md

@@ -0,0 +1,107 @@
+# Code Map Protocol
+
+`.cdd/code-map.yml` is a deterministic structural index of every source
+file in the repo (`.py`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`,
+`.vue`). Generated by `cdd-kit code-map`, committed to git, refreshed
+automatically when `cdd-kit init --hooks` is installed. `cdd-kit gate`
+hard-fails when any source file is newer than the map.
+
+## Why agents must read it FIRST
+
+Agents have no built-in way to know a file's line count before reading it.
+Reading a 1300-line file when you only need lines 200–250 wastes 80%+
+of the token budget. The code map is the size oracle: it tells you how
+big a file is and exactly which lines hold the symbol you need.
+
+## The 300-line rule
+
+Before reading any source file:
+
+1. `Read .cdd/code-map.yml` once at the start of your task (cache it for
+   the rest of your session).
+2. Find the file's entry. The first line is `<path>:  # N lines`.
+3. If `N <= 300`: do a normal full `Read <path>`.
+4. If `N > 300`: locate the class / method / function in the entry's
+   `classes:` / `functions:` block (or, for `.ts`/`.tsx`, the
+   `interfaces:` / `types:` / `enums:` blocks); its `lines: A-B`
+   field is the exact range. Use `Read <path> offset:A limit:(B-A+1)`.
+5. To understand a file's surface area without reading code, the
+   `imports:` / `constants:` / `interfaces:` / `types:` sections are
+   usually sufficient.
+
+## Fallback when the map is missing
+
+If `.cdd/code-map.yml` does not exist, do NOT proceed by reading whole
+files. Instead, write an agent-log entry with `status: needs-review`
+and `next-action: "regenerate code-map (run \`cdd-kit code-map\`)"`.
+The user must regenerate the map before you continue. This forces
+attention to missing infrastructure rather than burning tokens
+silently.
+
+## Fallback when the map is stale
+
+If `cdd-kit gate` reports `code-map stale`, the map is out of date.
+Same protocol as missing: emit `needs-review`, ask for a regen.
+
+## What the map does NOT contain
+
+- Function bodies, parameter types, JSDoc, TS generic constraints — read
+  the source for these using offset/limit.
+- Vue `<script lang="ts">` blocks — fall back to a full `Read` for now.
+- Anything inside `node_modules/`, `dist/`, `build/`, `.venv/`, `__pycache__/`.
+
+## Customising what gets indexed
+
+Optional file: `.cdd/code-map-config.yml`
+
+```yaml
+# Both keys optional. When present, each REPLACES (not merges) the built-in
+# default — copy the built-in list and edit it for partial overrides.
+include:
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/legacy/**"
+```
+
+Without this file, sensible built-in defaults apply.
+
+## Field reference
+
+Each file entry:
+
+```yaml
+backend/routes/todos.py:  # 1371 lines
+  imports:
+    - { module: flask, items: [Blueprint, request], line: 1 }
+  constants:
+    - { name: MAX_BATCH_SIZE, line: 18 }
+  classes:
+    - name: TodoService
+      lines: 22-104
+      methods:
+        - { name: create, lines: 30-62 }
+  functions:
+    - { name: get_todos, lines: 105-253 }  # @todos_bp.route(...)
+```
+
+For `.ts` / `.tsx` files, three additional optional sections may appear:
+
+```yaml
+src/types/index.ts:  # 625 lines
+  interfaces:
+    - { name: User, lines: 12-40 }
+    - { name: InternalState, lines: 42-50 }  # local
+  types:
+    - { name: UserId, lines: 52-52 }
+  enums:
+    - name: Status
+      lines: 60-66
+      members: [Pending, Active, Done]
+```
+
+`async ` prefix on a function/method name indicates `async def` (Python)
+or `async function` (JS/TS). `# local` annotation on an interface/type/enum
+means it is NOT exported.

package/assets/skills/contract-driven-delivery/templates/change-classification.md

@@ -38,7 +38,7 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 - Business logic:
 - CI/CD:
 
-## Required Test Families
+## Required Tests
 - unit:
 - contract:
 - integration:
@@ -52,4 +52,38 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 
 ## Required Agents
 
-## Assumptions / Clarifications
+## Inferred Acceptance Criteria
+<!-- 3-8 testable acceptance criteria derived from the change request. Format: AC-N: <criterion>.
+     test-strategist uses these to populate the Acceptance Criteria → Test Mapping table. -->
+- AC-1:
+- AC-2:
+- AC-3:
+
+## Tasks Not Applicable
+<!-- Comma-separated task IDs from tasks.yml that do NOT apply to this change.
+     /cdd-new SKILL marks these as `status: skipped` in tasks.yml. -->
+- not-applicable:
+
+## Clarifications or Assumptions
+
+## Context Manifest Draft
+<!-- Classifier fills this section. In /cdd-new Step 2.3, Claude copies it verbatim into
+     specs/changes/<change-id>/context-manifest.md, replacing the scaffold.
+     All paths must be repo-relative. Gate enforces Allowed Paths against agent files-read logs. -->
+
+### Affected Surfaces
+-
+
+### Allowed Paths
+<!-- Union of ALL paths any agent will read. Add change-specific paths below the defaults. -->
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
+
+### Agent Work Packets
+<!-- One sub-section per required agent (paths must be a subset of Allowed Paths above). -->
+
+#### change-classifier
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md

package/assets/specs-templates/change-classification.md

@@ -38,7 +38,7 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 - Business logic:
 - CI/CD:
 
-## Required Test Families
+## Required Tests
 - unit:
 - contract:
 - integration:
@@ -52,4 +52,38 @@ Always required: change-request.md, change-classification.md, test-plan.md, ci-g
 
 ## Required Agents
 
-## Assumptions / Clarifications
+## Inferred Acceptance Criteria
+<!-- 3-8 testable acceptance criteria derived from the change request. Format: AC-N: <criterion>.
+     test-strategist uses these to populate the Acceptance Criteria → Test Mapping table. -->
+- AC-1:
+- AC-2:
+- AC-3:
+
+## Tasks Not Applicable
+<!-- Comma-separated task IDs from tasks.yml that do NOT apply to this change.
+     /cdd-new SKILL marks these as `status: skipped` in tasks.yml. -->
+- not-applicable:
+
+## Clarifications or Assumptions
+
+## Context Manifest Draft
+<!-- Classifier fills this section. In /cdd-new Step 2.3, Claude copies it verbatim into
+     specs/changes/<change-id>/context-manifest.md, replacing the scaffold.
+     All paths must be repo-relative. Gate enforces Allowed Paths against agent files-read logs. -->
+
+### Affected Surfaces
+-
+
+### Allowed Paths
+<!-- Union of ALL paths any agent will read. Add change-specific paths below the defaults. -->
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
+
+### Agent Work Packets
+<!-- One sub-section per required agent (paths must be a subset of Allowed Paths above). -->
+
+#### change-classifier
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md

package/assets/specs-templates/context-manifest.md

@@ -8,6 +8,10 @@ and is automatically applied by `cdd-kit gate` — do not duplicate it here.
 -
 
 ## Allowed Paths
+<!-- UNION of all repo-relative paths (or globs) any agent may read for this change.
+     cdd-kit gate validates every agent's files-read log against this list.
+     Be specific — wide globs (e.g. src/) defeat read-scope governance.
+     Always include the three defaults below; add change-specific paths beneath them. -->
 - specs/changes/<change-id>/
 - specs/context/project-map.md
 - specs/context/contracts-index.md
@@ -19,12 +23,26 @@ and is automatically applied by `cdd-kit gate` — do not duplicate it here.
 -
 
 ## Agent Work Packets
+<!-- One sub-section per required agent. Each path list must be a subset of Allowed Paths above.
+     Add or remove sub-sections to match Required Agents in change-classification.md.
+     These sub-sections are documentation only — gate enforces Allowed Paths, not individual packets. -->
 
 ### change-classifier
-- allowed:
-  - specs/changes/<change-id>/
-  - specs/context/project-map.md
-  - specs/context/contracts-index.md
+- specs/changes/<change-id>/
+- specs/context/project-map.md
+- specs/context/contracts-index.md
+
+### <implementation-agent>
+<!-- Replace with actual agent name, e.g. backend-engineer, frontend-engineer -->
+- specs/changes/<change-id>/
+- contracts/
+- src/
+- tests/
+
+### <review-agent>
+<!-- Replace with actual agent name, e.g. contract-reviewer, qa-reviewer -->
+- specs/changes/<change-id>/
+- contracts/
 
 ## Context Expansion Requests
 

package/assets/specs-templates/tasks.yml

@@ -8,7 +8,7 @@ archive-tasks:
 depends-on: []
 
 tasks:
-  # status: pending | done | skipped
+  # status: pending | done | skipped   (optional: note: "reason or context")
   - { id: "1.1", section: Preparation, title: "Confirm classification and required artifacts", status: pending }
   - { id: "1.2", section: Preparation, title: "Confirm contracts to update", status: pending }
   - { id: "1.3", section: Preparation, title: "Confirm CI/CD gate plan", status: pending }