codd-dev 2.15.0__tar.gz → 2.16.0__tar.gz

{codd_dev-2.15.0 → codd_dev-2.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codd-dev
-Version: 2.15.0
+Version: 2.16.0
 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
@@ -153,12 +153,13 @@ This is what lets CoDD ship one core that works for Next.js, Django, FastAPI, Ra
 
 ## 🧭 Roadmap
 
-- **v2.15.0 (current)** — `kind: common` for shared infrastructure (cmd_467). Classify cross-cutting files (DB client, middleware, config) as `common` via `common_node_patterns:` glob or frontmatter. C5 amber −79.2% on dogfood LMS (125 → 26). `**` glob translator fix. See [CHANGELOG](CHANGELOG.md).
+- **v2.16.0 (current)** — `codd fix [PHENOMENON]` — North Star entry-point 2 (cmd_468). Express a desired change in natural language; CoDD identifies affected design docs via Tier-1 lexicon + Tier-2 semantic scoring, updates them with LLM, runs the DAG verify gate. Full interactive HITL (candidate selection, ambiguity clarification, risk confirmation) with `--non-interactive` for CI. 66 new tests, 2908 total PASS, SKIP=0. See [CHANGELOG](CHANGELOG.md).
+- **v2.15.0** — `kind: common` for shared infrastructure (cmd_467). C5 amber −79.2% on dogfood LMS (125 → 26). `**` glob translator fix.
 - **v2.14.0** — 8 structural gaps closed (cmd_466 dogfood). Sidecar `<test>.codd.yaml` with `verified_by:` (C6) / `axis_matrix:` (C9); lexicon schema SSoT; completeness_audit batch; `scan.exclude` bug fix (−52%); `codd dag verify --auto-repair`; elicit mock-AI sentinel; AI timeout 3600 s SSoT. Red 22 → 0.
 - **v2.13.0** — Opt-out protection: `OptOutPolicy` requires `justification` + `expires_at`. Silent SKIP abolished; severity preserved.
 - **v2.12.0** — Test-completeness gates: C7 amber promotion + C8 `ci_health` static check.
 - **v2.11.0** — Sprint-less `codd implement` (`--design <path> --output <dir>` directly).
-- **v2.16.0 (next)** — `codd fix [PHENOMENON]` — express a desired change in natural language; CoDD identifies affected design docs, updates them, updates implementation and tests, then verifies the DAG. Interactive mode included.
+- **v2.17.0 (next)** — impl/test auto-propagation from PHENOMENON (AC #8 completion); Codex wrapper for PHENOMENON mode.
 
 ---
 

{codd_dev-2.15.0 → codd_dev-2.16.0}/README.md

@@ -113,12 +113,13 @@ This is what lets CoDD ship one core that works for Next.js, Django, FastAPI, Ra
 
 ## 🧭 Roadmap
 
-- **v2.15.0 (current)** — `kind: common` for shared infrastructure (cmd_467). Classify cross-cutting files (DB client, middleware, config) as `common` via `common_node_patterns:` glob or frontmatter. C5 amber −79.2% on dogfood LMS (125 → 26). `**` glob translator fix. See [CHANGELOG](CHANGELOG.md).
+- **v2.16.0 (current)** — `codd fix [PHENOMENON]` — North Star entry-point 2 (cmd_468). Express a desired change in natural language; CoDD identifies affected design docs via Tier-1 lexicon + Tier-2 semantic scoring, updates them with LLM, runs the DAG verify gate. Full interactive HITL (candidate selection, ambiguity clarification, risk confirmation) with `--non-interactive` for CI. 66 new tests, 2908 total PASS, SKIP=0. See [CHANGELOG](CHANGELOG.md).
+- **v2.15.0** — `kind: common` for shared infrastructure (cmd_467). C5 amber −79.2% on dogfood LMS (125 → 26). `**` glob translator fix.
 - **v2.14.0** — 8 structural gaps closed (cmd_466 dogfood). Sidecar `<test>.codd.yaml` with `verified_by:` (C6) / `axis_matrix:` (C9); lexicon schema SSoT; completeness_audit batch; `scan.exclude` bug fix (−52%); `codd dag verify --auto-repair`; elicit mock-AI sentinel; AI timeout 3600 s SSoT. Red 22 → 0.
 - **v2.13.0** — Opt-out protection: `OptOutPolicy` requires `justification` + `expires_at`. Silent SKIP abolished; severity preserved.
 - **v2.12.0** — Test-completeness gates: C7 amber promotion + C8 `ci_health` static check.
 - **v2.11.0** — Sprint-less `codd implement` (`--design <path> --output <dir>` directly).
-- **v2.16.0 (next)** — `codd fix [PHENOMENON]` — express a desired change in natural language; CoDD identifies affected design docs, updates them, updates implementation and tests, then verifies the DAG. Interactive mode included.
+- **v2.17.0 (next)** — impl/test auto-propagation from PHENOMENON (AC #8 completion); Codex wrapper for PHENOMENON mode.
 
 ---
 

{codd_dev-2.15.0 → codd_dev-2.16.0}/codd/cli.py

@@ -3333,6 +3333,7 @@ def risk(path: str):
 
 
 @main.command()
+@click.argument("phenomenon", nargs=-1)
 @click.option("--path", default=".", help="Project root directory")
 @click.option("--max-attempts", default=3, type=click.IntRange(min=1, max=10),
               help="Maximum fix attempts (default: 3)")
@@ -3345,32 +3346,73 @@ def risk(path: str):
 @click.option("--no-push", is_flag=True, help="Don't push fixes after successful fix")
 @click.option("--dry-run", is_flag=True, help="Show what would be fixed without making changes")
 @click.option("--ai-cmd", default=None, help="Override AI CLI command")
-def fix(path: str, max_attempts: int, test_results: str | None, ci_log: str | None,
-        ci_only: bool, local_only: bool, no_push: bool, dry_run: bool, ai_cmd: str | None):
-    """Fix test/build failures using AI guided by design documents.
+@click.option("--non-interactive", is_flag=True,
+              help="PHENOMENON mode: disable interactive prompts (use defaults)")
+@click.option("--on-ambiguity",
+              type=click.Choice(["abort", "default", "top1"]),
+              default="abort",
+              show_default=True,
+              help="PHENOMENON mode: behavior when candidates are ambiguous in --non-interactive")
+@click.option("--allow-delete", is_flag=True,
+              help="PHENOMENON mode: allow design_doc to lose existing acceptance criteria / user journeys")
+def fix(phenomenon: tuple[str, ...], path: str, max_attempts: int,
+        test_results: str | None, ci_log: str | None,
+        ci_only: bool, local_only: bool, no_push: bool, dry_run: bool,
+        ai_cmd: str | None, non_interactive: bool, on_ambiguity: str,
+        allow_delete: bool):
+    """Fix test/build failures or a user-described PHENOMENON.
 
     \b
-    Auto-detects failure source (in order):
+    Two modes:
+      codd fix                              # legacy: auto-detect failures
+      codd fix "ログインがわかりにくい"     # PHENOMENON mode
+
+    \b
+    Legacy mode (no positional argument) auto-detects failure source:
       1. Explicit --test-results / --ci-log files
       2. CI failures via `gh run view`
       3. Local test execution
-
-    Maps failures to relevant design documents via the dependency graph,
+    Maps failures to relevant design docs via the dependency graph,
     then invokes Claude Code to fix implementation code.
 
+    \b
+    PHENOMENON mode (with positional argument) drives the second entry
+    point of CoDD's north star: starting from a phenomenon the user wants
+    fixed, CoDD updates the design doc, propagates the change, and
+    verifies — the user touches nothing. Argument-less invocation
+    remains completely unchanged.
+
     \b
     Examples:
-      codd fix                     # auto-detect and fix
-      codd fix --ci                # fix latest CI failure
-      codd fix --local             # run tests locally and fix
-      codd fix --dry-run           # show plan without fixing
-      codd fix --no-push           # fix but don't push
+      codd fix                                          # auto-detect and fix
+      codd fix --ci                                     # fix latest CI failure
+      codd fix --local                                  # run tests locally and fix
+      codd fix --dry-run                                # show plan without fixing
+      codd fix --no-push                                # fix but don't push
+      codd fix "ログインエラーをわかりやすくしたい"     # PHENOMENON mode
+      codd fix "Button needs aria-label" --non-interactive
     """
-    from codd.fixer import run_fix
-
     project_root = Path(path).resolve()
     _require_codd_dir(project_root)
 
+    phenomenon_text = " ".join(phenomenon).strip()
+
+    if phenomenon_text:
+        _run_phenomenon_fix_cli(
+            project_root,
+            phenomenon_text,
+            ai_cmd=ai_cmd,
+            max_attempts=max_attempts,
+            non_interactive=non_interactive,
+            on_ambiguity=on_ambiguity,
+            allow_delete=allow_delete,
+            dry_run=dry_run,
+            push=not no_push,
+        )
+        return
+
+    from codd.fixer import run_fix
+
     if ci_only and local_only:
         click.echo("Error: --ci and --local are mutually exclusive.")
         raise SystemExit(1)
@@ -3427,6 +3469,87 @@ def fix(path: str, max_attempts: int, test_results: str | None, ci_log: str | No
         raise SystemExit(1)
 
 
+def _run_phenomenon_fix_cli(
+    project_root: Path,
+    phenomenon_text: str,
+    *,
+    ai_cmd: str | None,
+    max_attempts: int,
+    non_interactive: bool,
+    on_ambiguity: str,
+    allow_delete: bool,
+    dry_run: bool,
+    push: bool,
+) -> None:
+    """CLI adapter for the PHENOMENON-mode fix pipeline."""
+    from codd.fix import run_phenomenon_fix
+
+    if dry_run:
+        click.echo("🔍 Dry run — analyzing phenomenon without applying changes...")
+    click.echo(f"🩺 Phenomenon: {phenomenon_text}")
+
+    result = run_phenomenon_fix(
+        project_root,
+        phenomenon_text,
+        ai_command=ai_cmd,
+        non_interactive=non_interactive,
+        on_ambiguity=on_ambiguity,
+        max_attempts=max_attempts,
+        dry_run=dry_run,
+        push=push,
+        allow_delete=allow_delete,
+    )
+
+    if result.analysis is not None:
+        a = result.analysis
+        click.echo(
+            f"   intent={a.intent}, ambiguity={a.ambiguity_score:.2f}, "
+            f"subject_terms={a.subject_terms[:4]}"
+        )
+
+    if result.aborted:
+        click.echo(f"❌ Aborted: {result.abort_reason}")
+        raise SystemExit(1)
+
+    if result.selection is not None:
+        cands = result.selection.candidates
+        click.echo(f"   {len(cands)} candidate design doc(s) considered.")
+
+    if not result.attempts:
+        click.echo("ℹ️  No candidate produced a usable update.")
+        raise SystemExit(1)
+
+    applied_any = False
+    for att in result.attempts:
+        status = "✅" if att.applied else ("🔸" if att.aborted_reason == "dry_run: not applying" else "❌")
+        target_id = att.target.node_id if att.target else "(no target)"
+        click.echo(f"{status} Attempt {att.attempt} on {target_id}")
+        if att.update is not None and att.update.diff:
+            for line in att.update.diff.splitlines()[:40]:
+                click.echo(f"  {line}")
+            extra = len(att.update.diff.splitlines()) - 40
+            if extra > 0:
+                click.echo(f"  ... (+{extra} more diff lines)")
+        if att.risk is not None and att.risk.risky:
+            click.echo(f"  ⚠️ risk: {', '.join(att.risk.categories) or 'unspecified'} — {att.risk.summary}")
+        if att.aborted_reason:
+            click.echo(f"  reason: {att.aborted_reason}")
+        if att.applied:
+            applied_any = True
+
+    if dry_run:
+        click.echo("\n🔎 Dry run complete — no files were modified.")
+        return
+
+    if applied_any:
+        click.echo(f"\n✅ Updated {len(result.applied_paths)} design doc(s): "
+                   f"{', '.join(result.applied_paths)}")
+        click.echo("   Review the diff above and commit when satisfied.")
+    else:
+        click.echo("\n❌ No design doc was updated.")
+        raise SystemExit(1)
+
+
 @main.command()
 @click.option("--path", default=".", help="Project root directory")
 def policy(path: str):

codd_dev-2.16.0/codd/fix/__init__.py

@@ -0,0 +1,22 @@
+"""CoDD fix — PHENOMENON-driven (operational feedback) mode.
+
+Implements the second entry point of CoDD's north star:
+"Given a phenomenon the user wants fixed, CoDD updates the design doc,
+implementation, and tests in one shot — the user touches nothing."
+
+The existing `codd fix` (argument-less, test/CI failure driven) is the
+first entry point. This package adds the second one as an additive,
+opt-in code path. The legacy run_fix() is not modified.
+"""
+
+from codd.fix.phenomenon_fixer import (
+    PhenomenonFixResult,
+    PhenomenonFixAttempt,
+    run_phenomenon_fix,
+)
+
+__all__ = [
+    "PhenomenonFixResult",
+    "PhenomenonFixAttempt",
+    "run_phenomenon_fix",
+]

codd_dev-2.16.0/codd/fix/candidate_selector.py

@@ -0,0 +1,306 @@
+"""Select relevant design_doc candidates for a PHENOMENON analysis."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+from codd.dag import DAG, Node
+from codd.fix.phenomenon_parser import PhenomenonAnalysis
+from codd.fix.templates_loader import load_template
+
+AiInvoke = Callable[[str], str]
+
+
+@dataclass
+class Candidate:
+    """A scored design document candidate."""
+
+    node_id: str
+    path: str
+    score: float
+    tier_1_score: float = 0.0
+    tier_2_score: float = 0.0
+    reasons: list[str] = field(default_factory=list)
+    kind: str = "design_doc"
+
+    def to_display(self) -> str:
+        reason = "; ".join(self.reasons) or "(no reason)"
+        return f"{self.node_id} (score={self.score:.2f}) — {reason}"
+
+
+@dataclass
+class CandidateSelection:
+    """Result of candidate_selector.select()."""
+
+    candidates: list[Candidate] = field(default_factory=list)
+    is_clear_winner: bool = False
+    top_margin: float = 0.0
+    fallback_reason: str = ""
+
+
+def select_candidates(
+    analysis: PhenomenonAnalysis,
+    *,
+    dag: DAG,
+    project_root: Path,
+    ai_invoke: AiInvoke | None = None,
+    max_candidates: int = 5,
+    score_threshold: float = 0.15,
+    tier2_weight: float = 0.6,
+    include_common: bool = True,
+) -> CandidateSelection:
+    """Score design_doc / common nodes against the phenomenon analysis.
+
+    Tier 1 (lexicon-driven, exact substring match): score += 1.0 per hit.
+    Tier 2 (semantic, LLM-driven): 0.0-1.0 per candidate, weighted by
+    tier2_weight. Tier 2 is skipped when ai_invoke is None.
+    """
+    nodes = _collect_design_nodes(dag, include_common=include_common)
+    if not nodes:
+        return CandidateSelection(
+            candidates=[],
+            fallback_reason="no design_doc nodes in DAG",
+        )
+
+    tier1: dict[str, tuple[float, list[str]]] = {}
+    for node in nodes:
+        score, reasons = _tier1_score(node, analysis, project_root)
+        if score > 0.0:
+            tier1[node.id] = (score, reasons)
+
+    tier2: dict[str, tuple[float, list[str]]] = {}
+    if ai_invoke is not None and analysis.subject_terms:
+        tier2 = _tier2_score(
+            nodes=nodes,
+            analysis=analysis,
+            ai_invoke=ai_invoke,
+            project_root=project_root,
+        )
+
+    scored: list[Candidate] = []
+    candidate_ids = set(tier1) | set(tier2)
+    for node_id in candidate_ids:
+        node = next((n for n in nodes if n.id == node_id), None)
+        if node is None:
+            continue
+        t1, t1_reasons = tier1.get(node_id, (0.0, []))
+        t2, t2_reasons = tier2.get(node_id, (0.0, []))
+        combined = t1 + tier2_weight * t2
+        if combined <= 0.0:
+            continue
+        scored.append(
+            Candidate(
+                node_id=node.id,
+                path=node.path or node.id,
+                score=combined,
+                tier_1_score=t1,
+                tier_2_score=t2,
+                reasons=t1_reasons + t2_reasons,
+                kind=node.kind,
+            )
+        )
+
+    scored.sort(key=lambda c: c.score, reverse=True)
+    top = scored[: max(1, max_candidates)]
+
+    if not top:
+        return CandidateSelection(
+            candidates=[],
+            fallback_reason="no candidate matched lexicon or semantic search",
+        )
+
+    is_clear = False
+    margin = 0.0
+    if len(top) == 1:
+        is_clear = True
+    else:
+        margin = top[0].score - top[1].score
+        is_clear = margin > score_threshold
+
+    return CandidateSelection(
+        candidates=top,
+        is_clear_winner=is_clear,
+        top_margin=margin,
+    )
+
+
+def _collect_design_nodes(dag: DAG, *, include_common: bool) -> list[Node]:
+    kinds = {"design_doc"}
+    if include_common:
+        kinds.add("common")
+    return [node for node in dag.nodes.values() if node.kind in kinds]
+
+
+_WORD_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]+|[぀-ヿ一-鿿]+")
+
+
+def _tier1_score(
+    node: Node,
+    analysis: PhenomenonAnalysis,
+    project_root: Path,
+) -> tuple[float, list[str]]:
+    """Lexicon-driven exact match against frontmatter description and body."""
+    text = _read_node_text(node, project_root)
+    if not text:
+        return 0.0, []
+
+    text_lower = text.lower()
+    score = 0.0
+    reasons: list[str] = []
+
+    for lex in analysis.lexicon_hits:
+        key = lex.strip().lower()
+        if not key:
+            continue
+        if key in text_lower:
+            score += 1.0
+            reasons.append(f"lexicon hit: {lex}")
+
+    for term in analysis.subject_terms:
+        key = term.strip().lower()
+        if not key or len(key) < 2:
+            continue
+        if key in text_lower:
+            score += 0.25
+            reasons.append(f"subject term: {term}")
+
+    return score, reasons
+
+
+def _read_node_text(node: Node, project_root: Path) -> str:
+    if not node.path:
+        return ""
+    path = project_root / node.path
+    if not path.exists():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (UnicodeDecodeError, OSError):
+        return ""
+
+
+def _tier2_score(
+    *,
+    nodes: list[Node],
+    analysis: PhenomenonAnalysis,
+    ai_invoke: AiInvoke,
+    project_root: Path,
+) -> dict[str, tuple[float, list[str]]]:
+    summaries = _node_summaries(nodes, project_root)
+    if not summaries:
+        return {}
+
+    prompt = _build_tier2_prompt(analysis, summaries)
+    try:
+        raw = ai_invoke(prompt)
+    except Exception:  # noqa: BLE001
+        return {}
+
+    payload = _extract_json_object(raw)
+    if not isinstance(payload, dict):
+        return {}
+
+    raw_scores = payload.get("scores")
+    if not isinstance(raw_scores, dict):
+        return {}
+
+    out: dict[str, tuple[float, list[str]]] = {}
+    for node_id, entry in raw_scores.items():
+        score, reason = _coerce_tier2_entry(entry)
+        if score > 0.0:
+            out[str(node_id)] = (score, [f"semantic: {reason}" if reason else "semantic match"])
+    return out
+
+
+def _node_summaries(nodes: Iterable[Node], project_root: Path) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for node in nodes:
+        text = _read_node_text(node, project_root)
+        if not text:
+            continue
+        summary = _summarize_doc(text)
+        if summary:
+            out[node.id] = summary
+    return out
+
+
+def _summarize_doc(text: str, *, max_len: int = 360) -> str:
+    """Extract a short summary: frontmatter description or first paragraph."""
+    fm_match = re.match(r"^---\s*\n(.*?)\n---\s*\n?", text, re.DOTALL)
+    if fm_match:
+        fm_text = fm_match.group(1)
+        body = text[fm_match.end():]
+        desc_match = re.search(r"^description:\s*(.+)$", fm_text, re.MULTILINE)
+        if desc_match:
+            description = desc_match.group(1).strip().strip('"').strip("'")
+            if description:
+                return description[:max_len]
+    else:
+        body = text
+
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("#") and not stripped.startswith("```"):
+            return stripped[:max_len]
+    return ""
+
+
+def _build_tier2_prompt(analysis: PhenomenonAnalysis, summaries: dict[str, str]) -> str:
+    summaries_block = "\n".join(
+        f"- {node_id}: {summary}" for node_id, summary in summaries.items()
+    )
+    analysis_block = json.dumps(analysis.to_dict(), ensure_ascii=False)
+    return (
+        "You are CoDD's semantic matcher. Given a phenomenon analysis and a\n"
+        "list of design document summaries, score each summary 0.0-1.0 by\n"
+        "how likely it is the right place to make a change. Return JSON only.\n\n"
+        "PHENOMENON_ANALYSIS:\n"
+        f"{analysis_block}\n\n"
+        "DESIGN_DOC_SUMMARIES:\n"
+        f"{summaries_block}\n\n"
+        "Return JSON of shape:\n"
+        '{"scores": {"<node_id>": {"score": 0.0, "reason": "<short>"}}}\n'
+        "Omit nodes with score 0. Include at most 8 entries.\n"
+        "JSON OUTPUT:\n"
+    )
+
+
+def _coerce_tier2_entry(entry: Any) -> tuple[float, str]:
+    if isinstance(entry, (int, float)):
+        return max(0.0, min(1.0, float(entry))), ""
+    if isinstance(entry, dict):
+        try:
+            score = float(entry.get("score", 0.0))
+        except (TypeError, ValueError):
+            score = 0.0
+        reason = str(entry.get("reason", "") or "").strip()
+        return max(0.0, min(1.0, score)), reason[:160]
+    return 0.0, ""
+
+
+_JSON_FENCE_RE = re.compile(r"```(?:json)?\s*\n(.*?)```", re.DOTALL)
+
+
+def _extract_json_object(raw: str) -> dict[str, Any] | None:
+    if not raw:
+        return None
+    text = raw.strip()
+    fenced = _JSON_FENCE_RE.search(text)
+    if fenced:
+        text = fenced.group(1).strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1:
+        return None
+    try:
+        return json.loads(text[start : end + 1])
+    except json.JSONDecodeError:
+        return None