dic-workflow-kit 1.0.0

package/scripts/dic_workflow.py

@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""Portable helper skeleton for DIC Workflow Kit.
+
+This script intentionally uses only the Python standard library.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+
+
+VERSION = "1.0.0"
+
+
+def write_text(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8", newline="\n")
+
+
+def find_workflow_root(start: Path) -> Path:
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+    for candidate in [current, *current.parents]:
+        if (candidate / "INSTRUCTION.md").exists():
+            return candidate
+    return current
+
+
+def rel(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def extract_validation_commands(text: str, source: str) -> list[dict[str, Any]]:
+    commands = []
+    seen = set()
+    for value in re.findall(r"`([^`\r\n]+)`", text):
+        if not re.match(
+            r"^(?:npm\s+(?:run|test|exec)\b|npx\s+|pnpm\s+|yarn\s+|"
+            r"openspec\s+validate\b|pytest(?:\s|$)|python\s+|mvn\s+)",
+            value,
+        ):
+            continue
+        try:
+            command = shlex.split(value)
+        except ValueError:
+            continue
+        key = tuple(command)
+        if key in seen:
+            continue
+        seen.add(key)
+        commands.append(
+            {
+                "name": value,
+                "command": command,
+                "cwd": ".",
+                "source": source,
+                "kind": "suggested",
+            }
+        )
+    return commands
+
+
+def obligation_id(capability_id: str, kind: str, title: str) -> str:
+    digest = hashlib.sha256(
+        f"{capability_id}\0{kind}\0{title}".encode("utf-8")
+    ).hexdigest()[:12]
+    return f"obl-{digest}"
+
+
+def extract_openspec_obligations(
+    spec_path: Path,
+    project_root: Path,
+    capability_id: str,
+    authority: str,
+) -> list[dict[str, Any]]:
+    lines = spec_path.read_text(encoding="utf-8").splitlines()
+    obligations = []
+    current_requirement = None
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        requirement_match = re.match(r"^###\s+Requirement:\s*(.+?)\s*$", line)
+        scenario_match = re.match(r"^####\s+Scenario:\s*(.+?)\s*$", line)
+        if requirement_match:
+            title = requirement_match.group(1)
+            statement_lines = []
+            cursor = index + 1
+            while cursor < len(lines) and not re.match(
+                r"^#{3,4}\s+(?:Requirement|Scenario):", lines[cursor]
+            ):
+                value = lines[cursor].strip()
+                if value and not value.startswith("#"):
+                    statement_lines.append(value)
+                cursor += 1
+            current_requirement = obligation_id(capability_id, "requirement", title)
+            obligations.append(
+                {
+                    "id": current_requirement,
+                    "capabilityId": capability_id,
+                    "kind": "requirement",
+                    "title": title,
+                    "statement": " ".join(statement_lines),
+                    "source": rel(spec_path, project_root),
+                    "line": index + 1,
+                    "authority": authority,
+                    "parentId": None,
+                    "acceptanceClauses": [],
+                }
+            )
+        elif scenario_match:
+            title = scenario_match.group(1)
+            clauses = []
+            cursor = index + 1
+            while cursor < len(lines) and not re.match(
+                r"^#{3,4}\s+(?:Requirement|Scenario):", lines[cursor]
+            ):
+                clause_match = re.match(
+                    r"^\s*-\s+\*\*(GIVEN|WHEN|THEN|AND|BUT)\*\*\s*(.+?)\s*$",
+                    lines[cursor],
+                    flags=re.IGNORECASE,
+                )
+                if clause_match:
+                    clauses.append(
+                        {
+                            "keyword": clause_match.group(1).upper(),
+                            "text": clause_match.group(2),
+                            "line": cursor + 1,
+                        }
+                    )
+                cursor += 1
+            obligations.append(
+                {
+                    "id": obligation_id(capability_id, "scenario", title),
+                    "capabilityId": capability_id,
+                    "kind": "scenario",
+                    "title": title,
+                    "statement": " ".join(
+                        f"{item['keyword']} {item['text']}" for item in clauses
+                    ),
+                    "source": rel(spec_path, project_root),
+                    "line": index + 1,
+                    "authority": authority,
+                    "parentId": current_requirement,
+                    "acceptanceClauses": clauses,
+                }
+            )
+        index += 1
+    return obligations
+
+
+def build_obligation_catalog(
+    project_root: Path, design_entry: dict[str, Any]
+) -> dict[str, Any]:
+    use_baseline = design_entry["lifecycle"] == "archived" and design_entry["baselineSpecs"]
+    selected_specs = (
+        design_entry["baselineSpecs"] if use_baseline else design_entry["deltaSpecs"]
+    )
+    authority = "current-baseline" if use_baseline else "active-change"
+    obligations = []
+    for spec in selected_specs:
+        spec_path = project_root / spec
+        capability_id = spec_path.parent.name
+        obligations.extend(
+            extract_openspec_obligations(
+                spec_path, project_root, capability_id, authority
+            )
+        )
+    return {
+        "schema": "dic.contract-obligations.v1",
+        "version": VERSION,
+        "changeId": design_entry["changeId"],
+        "changeLifecycle": design_entry["lifecycle"],
+        "authorityPolicy": (
+            "Archived changes use promoted current baseline specs."
+            if use_baseline
+            else "Active changes use their delta specs."
+        ),
+        "sources": selected_specs,
+        "counts": {
+            "requirements": sum(item["kind"] == "requirement" for item in obligations),
+            "scenarios": sum(item["kind"] == "scenario" for item in obligations),
+            "total": len(obligations),
+        },
+        "obligations": obligations,
+    }
+
+
+def render_obligation_catalog(catalog: dict[str, Any]) -> str:
+    lines = [
+        "# Contract Obligations",
+        "",
+        f"- Change: `{catalog['changeId']}`",
+        f"- Lifecycle: {catalog['changeLifecycle']}",
+        f"- Authority: {catalog['authorityPolicy']}",
+        f"- Requirements: {catalog['counts']['requirements']}",
+        f"- Scenarios: {catalog['counts']['scenarios']}",
+        "",
+    ]
+    for item in catalog["obligations"]:
+        lines.extend(
+            [
+                f"## {item['id']} — {item['title']}",
+                "",
+                f"- Kind: {item['kind']}",
+                f"- Source: `{item['source']}:{item['line']}`",
+                f"- Authority: {item['authority']}",
+            ]
+        )
+        if item["parentId"]:
+            lines.append(f"- Parent: `{item['parentId']}`")
+        lines.extend(["", item["statement"] or "_No normative body extracted._", ""])
+    return "\n".join(lines)
+
+
+def resolve_design_map(project_root: Path, capability_ids: list[str]) -> dict[str, Any] | None:
+    map_path = project_root / "openspec" / "designs" / "spec-to-design-map.md"
+    if not map_path.exists():
+        return None
+    text = map_path.read_text(encoding="utf-8")
+    for line in text.splitlines():
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [cell.strip() for cell in line.strip().strip("|").split("|")]
+        if len(cells) < 5:
+            continue
+        capability = cells[0].strip("` ")
+        if capability not in capability_ids:
+            continue
+        linked_paths = []
+        for cell in cells[1:4]:
+            linked_paths.extend(re.findall(r"`(openspec/[^`]+\.md)`", cell))
+        linked_paths = list(dict.fromkeys(linked_paths))
+        return {
+            "source": rel(map_path, project_root),
+            "capabilityId": capability,
+            "architectureDesigns": [
+                path for path in linked_paths if "/designs/architecture/" in path
+            ],
+            "moduleDesigns": [
+                path for path in linked_paths if "/designs/modules/" in path
+            ],
+            "adrs": [path for path in linked_paths if "/designs/adr/" in path],
+            "validationSummary": cells[4],
+            "validationCommands": extract_validation_commands(cells[4], rel(map_path, project_root)),
+        }
+    return None
+
+
+def resolve_openspec_change(project_root: Path, change_id: str) -> dict[str, Any]:
+    candidates = [
+        ("active", project_root / "openspec" / "changes" / change_id),
+        ("archived", project_root / "openspec" / "changes" / "archive" / change_id),
+    ]
+    for lifecycle, change_root in candidates:
+        if not change_root.is_dir():
+            continue
+        delta_specs = sorted(change_root.glob("specs/**/spec.md"))
+        capability_ids = [
+            path.relative_to(change_root / "specs").parts[0] for path in delta_specs
+        ]
+        baseline_specs = []
+        for delta_spec in delta_specs:
+            relative_spec = delta_spec.relative_to(change_root / "specs")
+            baseline = project_root / "openspec" / "specs" / relative_spec
+            if baseline.exists():
+                baseline_specs.append(baseline)
+        documents = [
+            path
+            for path in [
+                change_root / "proposal.md",
+                change_root / "design.md",
+                change_root / "tasks.md",
+            ]
+            if path.exists()
+        ]
+        result = {
+            "type": "openspec-change",
+            "changeId": change_id,
+            "lifecycle": lifecycle,
+            "changeRoot": rel(change_root, project_root),
+            "documents": [rel(path, project_root) for path in documents],
+            "deltaSpecs": [rel(path, project_root) for path in delta_specs],
+            "baselineSpecs": [rel(path, project_root) for path in baseline_specs],
+        }
+        design_map = resolve_design_map(project_root, capability_ids)
+        if design_map:
+            result["designMap"] = design_map
+        return result
+    raise SystemExit(
+        f"OpenSpec change not found: {change_id} "
+        f"(checked active and archived changes under {project_root})"
+    )
+
+
+def detect_project(root: Path, change_id: str = "") -> dict[str, Any]:
+    project_root = root
+    openspec = list(project_root.glob("**/openspec/specs/**/spec.md")) + list(
+        project_root.glob("**/openspec/changes/**/proposal.md")
+    )
+    design_entry = resolve_openspec_change(project_root, change_id) if change_id else None
+    if design_entry:
+        selected = (
+            design_entry["documents"]
+            + design_entry["deltaSpecs"]
+            + design_entry["baselineSpecs"]
+        )
+        design_map = design_entry.get("designMap")
+        if design_map:
+            selected += [
+                design_map["source"],
+                *design_map["architectureDesigns"],
+                *design_map["moduleDesigns"],
+                *design_map["adrs"],
+            ]
+        design_sources = [project_root / path for path in selected]
+    else:
+        design_sources = []
+        for pattern in ["README*", "docs/**/*.md", "design/**/*.md", "spec/**/*.md", "api/**/*.md", "schemas/**/*"]:
+            design_sources.extend(project_root.glob(pattern))
+        for path in openspec:
+            if path not in design_sources:
+                design_sources.append(path)
+
+    impl_roots = [p for p in [project_root / "src", project_root / "app", project_root / "code"] if p.exists()]
+    test_roots = [p for p in [project_root / "test", project_root / "tests", project_root / "test-cases"] if p.exists()]
+    project_types = []
+    adapters = ["generic"]
+    if openspec:
+        project_types.append("openspec")
+        adapters.append("openspec")
+    if (project_root / "pom.xml").exists() or list(project_root.glob("**/pom.xml")):
+        project_types.append("maven")
+    if (project_root / "package.json").exists() or list(project_root.glob("**/package.json")):
+        project_types.append("node")
+
+    validation_commands = []
+    if design_entry:
+        for document in design_entry["documents"]:
+            path = project_root / document
+            validation_commands.extend(
+                extract_validation_commands(path.read_text(encoding="utf-8"), document)
+            )
+        if design_entry.get("designMap"):
+            validation_commands.extend(design_entry["designMap"]["validationCommands"])
+        if design_entry["lifecycle"] == "archived":
+            validation_commands = [
+                item
+                for item in validation_commands
+                if not (
+                    item["command"][:2] == ["openspec", "validate"]
+                    and "--all" not in item["command"]
+                )
+            ]
+        unique_commands = {}
+        for item in validation_commands:
+            unique_commands.setdefault(tuple(item["command"]), item)
+        validation_commands = list(unique_commands.values())
+
+    profile = {
+        "schema": "dic.project-profile.v1",
+        "version": VERSION,
+        "projectRoot": project_root.as_posix(),
+        "projectTypes": sorted(set(project_types)) or ["generic"],
+        "adapters": adapters,
+        "designSources": [rel(p, project_root) for p in sorted(set(design_sources))],
+        "implementationRoots": [rel(p, project_root) for p in impl_roots],
+        "testRoots": [rel(p, project_root) for p in test_roots],
+        "protectedPaths": [rel(p, project_root) for p in sorted(set(design_sources))],
+        "validationCommands": validation_commands,
+        "riskFamilies": ["requirements", "api-contract", "flow-completeness", "validation"],
+        "outputContract": {
+            "finalResultJson": "reports/FINAL_RESULT.json",
+            "finalOutputMd": "result/output.md",
+            "contractObligationsJson": "reports/contract-obligations.json",
+            "contractObligationsMd": "reports/contract-obligations.md",
+            "traceDir": "logs/trace"
+        }
+    }
+    if design_entry:
+        profile["designEntry"] = design_entry
+        profile["deltaSpecs"] = design_entry["deltaSpecs"]
+        profile["baselineSpecs"] = design_entry["baselineSpecs"]
+    return profile
+
+
+def command_init(args: argparse.Namespace) -> int:
+    root = Path(args.root or os.getcwd()).resolve()
+    output_root = Path(args.output_root).resolve() if args.output_root else root
+    for directory in ["reports", "result", "logs/trace"]:
+        (output_root / directory).mkdir(parents=True, exist_ok=True)
+    profile = detect_project(root, args.change)
+    profile_path = output_root / "reports" / "project-profile.json"
+    write_text(profile_path, json.dumps(profile, indent=2, ensure_ascii=False))
+    if profile.get("designEntry"):
+        catalog = build_obligation_catalog(root, profile["designEntry"])
+        write_text(
+            output_root / "reports" / "contract-obligations.json",
+            json.dumps(catalog, indent=2, ensure_ascii=False),
+        )
+        write_text(
+            output_root / "reports" / "contract-obligations.md",
+            render_obligation_catalog(catalog),
+        )
+    output = [
+        "# DIC Workflow Init",
+        "",
+        f"- Version: {VERSION}",
+        f"- Project root: `{root.as_posix()}`",
+        f"- Output root: `{output_root.as_posix()}`",
+        f"- Project profile: `{profile_path.as_posix()}`",
+        f"- Adapters: {', '.join(profile['adapters'])}",
+    ]
+    if profile.get("designEntry"):
+        entry = profile["designEntry"]
+        output.extend(
+            [
+                f"- Design entry: OpenSpec Change `{entry['changeId']}`",
+                f"- Change lifecycle: {entry['lifecycle']}",
+            ]
+        )
+    output.append("")
+    write_text(output_root / "logs" / "trace" / "init.md", "\n".join(output))
+    print(f"DIC_WORKFLOW_VERSION: {VERSION}")
+    print(f"PROJECT_ROOT: {root}")
+    print(f"OUTPUT_ROOT: {output_root}")
+    print(f"PROJECT_PROFILE: {profile_path}")
+    return 0
+
+
+def command_finalize(args: argparse.Namespace) -> int:
+    root = find_workflow_root(Path(args.root or os.getcwd()))
+    status = args.status.upper()
+    if status not in {"PASS", "PARTIAL", "BLOCKED", "FAIL"}:
+        raise SystemExit(f"invalid status: {args.status}")
+    result = {
+        "schema": "dic.final-result.v1",
+        "status": status,
+        "final": True,
+        "summary": args.summary,
+        "artifacts": [
+            "reports/project-profile.json",
+            "reports/contract-obligations.json",
+            "reports/contract-obligations.md",
+            "reports/final-consistency-report.md",
+            "reports/FINAL_RESULT.json",
+            "result/output.md",
+            "logs/trace/"
+        ],
+        "validation": [],
+        "changedFiles": [],
+        "residualRisks": []
+    }
+    write_text(root / "reports" / "FINAL_RESULT.json", json.dumps(result, indent=2, ensure_ascii=False))
+    lines = [
+        "# DIC Final Result",
+        "",
+        f"FINAL_EXECUTION_RESULT: {status}",
+        "FINAL_RESULT_FINAL: true",
+        "",
+        args.summary,
+        "",
+        "## Artifacts",
+        "",
+        "- `reports/FINAL_RESULT.json`",
+        "- `reports/contract-obligations.json`",
+        "- `reports/contract-obligations.md`",
+        "- `result/output.md`",
+        "- `logs/trace/`",
+        "",
+    ]
+    write_text(root / "result" / "output.md", "\n".join(lines))
+    print(f"FINAL_EXECUTION_RESULT: {status}")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="dic_workflow")
+    parser.add_argument("--root", default="")
+    parser.add_argument("--output-root", default="")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init")
+    p.add_argument("--change", default="")
+    p.set_defaults(func=command_init)
+
+    p = sub.add_parser("finalize")
+    p.add_argument("--status", default="PARTIAL")
+    p.add_argument("--summary", default="DIC workflow finished with recorded evidence.")
+    p.set_defaults(func=command_finalize)
+
+    args = parser.parse_args()
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/knowledge-bdd/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: knowledge-bdd
+version: 1.0.0
+description: Derive Given-When-Then acceptance scenarios from confirmed design rules and flow contracts.
+---
+
+# Knowledge: BDD
+
+Use this Skill after requirements and flows are confirmed.
+
+For every confirmed rule, consider:
+
+- happy path
+- boundary
+- exception
+- state transition
+- authorization or eligibility
+- idempotency or retry
+- integration side effects
+- concurrency or ordering
+
+BDD scenarios are acceptance criteria. They are not a license to invent behavior outside source truth.

package/skills/knowledge-openspec/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: knowledge-openspec
+version: 1.0.0
+description: OpenSpec knowledge pack for proposals, specs, scenarios, tasks, changes, archived capabilities, validation, and design-to-implementation mapping.
+---
+
+# Knowledge: OpenSpec
+
+Use this Skill when the project contains OpenSpec files or the user says design work is managed with OpenSpec.
+
+Read candidates:
+
+- `openspec/specs/**/spec.md`
+- `openspec/changes/**/proposal.md`
+- `openspec/changes/**/design.md`
+- `openspec/changes/**/tasks.md`
+- `openspec/changes/**/specs/**/spec.md`
+- archived specs, only as historical context
+
+Checks:
+
+- Proposal intent is reflected in specs.
+- Requirements and scenarios map to implementation.
+- Tasks are complete or terminally classified.
+- Tests or payload evidence cover scenarios.
+- Implementation does not contradict current specs.
+- Archived specs do not override current accepted specs.
+
+Do not treat OpenSpec examples as implementation details unless current specs require them.

package/skills/knowledge-repair-distill/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: knowledge-repair-distill
+version: 1.0.0
+description: Generic repair convergence guidance, gap taxonomy, model steering hints, and validation gates for design-implementation consistency work.
+---
+
+# Knowledge: Repair Distill
+
+Use this Skill before repair planning or when a model drifts.
+
+Common gap families:
+
+- missing behavior
+- wrong state transition
+- incorrect numeric or money rule
+- authorization or eligibility gap
+- API contract mismatch
+- persistence invariant gap
+- side-effect or integration timing gap
+- idempotency, retry, or concurrency gap
+- validation/error contract mismatch
+- overfit to public examples
+
+Convergence rule:
+
+Do not chase compile or test failures mechanically after a repair. Re-check whether the changed code still satisfies the governing source rule, then apply only mechanical fixes that preserve the rule.

package/skills/workflow-core/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: workflow-core
+version: 1.0.0
+description: Core Design-Implementation Consistency workflow contract, evidence model, handoff rules, and final output expectations.
+---
+
+# Workflow Core
+
+Use this Skill to understand the package-level workflow mechanism.
+
+Principles:
+
+- Source truth wins over implementation.
+- Public tests are examples, not the full contract.
+- Every repair must trace to a source-backed obligation.
+- Subagents are useful only when they produce consumed evidence.
+- Final success requires validation evidence, residual-risk classification, and final artifacts.
+
+Required durable outputs:
+
+```text
+reports/project-profile.json
+reports/final-consistency-report.md
+reports/FINAL_RESULT.json
+result/output.md
+logs/trace/
+```
+
+Do not hardcode local paths, shell syntax, or a single project layout.

package/skills/workflow-intake/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: workflow-intake
+version: 1.0.0
+description: Discover authoritative design sources, implementation roots, test roots, protected paths, validation commands, and adapter hints.
+---
+
+# Workflow Intake
+
+Use this Skill before any implementation inspection or repair.
+
+Intake must identify:
+
+- workflow root
+- project root
+- design sources
+- implementation roots
+- test roots
+- protected paths
+- validation commands
+- adapter hints
+- available external tools
+
+Write the result to `reports/project-profile.json` when possible and mirror reasoning under `logs/trace/intake/`.
+
+Do not assume OpenSpec, Maven, npm, Java, Node, or Spring. Detect them from repository evidence.

package/skills/workflow-profile/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: workflow-profile
+version: 1.0.0
+description: Build a normalized project profile for design-implementation consistency work without hardcoding a repository or technology stack.
+---
+
+# Workflow Profile
+
+Use this Skill after intake to create a stable profile consumed by downstream agents.
+
+The profile should follow `schemas/project-profile.schema.json` and include:
+
+- source hierarchy
+- project type hints
+- adapters selected
+- design source paths
+- implementation root paths
+- test root paths
+- protected paths
+- validation commands
+- risk families
+- output contract
+
+If information is missing, record `unknown` or `blocked` with evidence instead of guessing.

package/skills/workflow-repair/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: workflow-repair
+version: 1.0.0
+description: Guide source-backed implementation inspection, repair planning, code repair, validation loops, and final consistency evidence.
+---
+
+# Workflow Repair
+
+Use this Skill after project profile and source obligations are known.
+
+Repair loop:
+
+1. Confirm obligation from source.
+2. Inspect implementation.
+3. Classify gap.
+4. Plan the smallest safe repair slice.
+5. Modify implementation only inside allowed boundaries.
+6. Run focused validation.
+7. Update trace and residual risk.
+8. Repeat or finalize.
+
+Never repair from failing test names alone. Convert validation failures into source-backed hypotheses first.