@scemoon/cdh 1.0.9 → 1.0.10-beta.1

package/cdh/scaffold.py

@@ -1,1436 +0,0 @@
-from __future__ import annotations
-
-import logging
-import os
-import re
-from dataclasses import dataclass
-from pathlib import Path
-
-import yaml
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class ComponentSpec:
-    id: str
-    kind: str
-    owns: str
-    fr_prefix: str
-    tech: str
-    label: str
-    description: str
-
-
-@dataclass(frozen=True)
-class CrossCutSpec:
-    id: str
-    paths: tuple[str, ...]
-    label: str
-    description: str
-
-
-COMPONENTS: tuple[ComponentSpec, ...] = (
-    ComponentSpec(
-        id="native",
-        kind="mobile",
-        owns="apps/native",
-        fr_prefix="NATIVE",
-        tech="react-native | flutter",
-        label="Mobile App",
-        description="iOS/Android cross-platform (RN/Flutter)",
-    ),
-    ComponentSpec(
-        id="desktop",
-        kind="desktop",
-        owns="apps/desktop",
-        fr_prefix="DESKTOP",
-        tech="electron | tauri",
-        label="Desktop App",
-        description="Cross-platform desktop (Electron/Tauri)",
-    ),
-    ComponentSpec(
-        id="backend",
-        kind="service",
-        owns="apps/backend",
-        fr_prefix="BE",
-        tech="python | node | go",
-        label="Backend Service",
-        description="HTTP API/microservice (Python/Node/Go)",
-    ),
-    ComponentSpec(
-        id="wxa",
-        kind="mini-program",
-        owns="apps/wxa",
-        fr_prefix="WXA",
-        tech="miniprogram",
-        label="WeChat Mini-Program",
-        description="WeChat ecosystem mini-program",
-    ),
-    ComponentSpec(
-        id="mya",
-        kind="mini-program",
-        owns="apps/mya",
-        fr_prefix="MYA",
-        tech="miniprogram",
-        label="Alipay Mini-Program",
-        description="Alipay ecosystem mini-program",
-    ),
-    ComponentSpec(
-        id="tta",
-        kind="mini-program",
-        owns="apps/tta",
-        fr_prefix="TTA",
-        tech="miniprogram",
-        label="TikTok Mini-Program",
-        description="TikTok/Douyin ecosystem mini-program",
-    ),
-)
-
-
-COMPONENT_BY_ID: dict[str, ComponentSpec] = {c.id: c for c in COMPONENTS}
-
-
-CROSS_CUTTING: tuple[CrossCutSpec, ...] = (
-    CrossCutSpec(
-        id="contracts",
-        paths=("aidlc/contracts/CHANGELOG.md",),
-        label="Interface Contracts",
-        description="API/event contracts and changelog",
-    ),
-    CrossCutSpec(
-        id="shared",
-        paths=("aidlc/packages/shared",),
-        label="Shared Types",
-        description="Cross-component shared types package",
-    ),
-    CrossCutSpec(
-        id="openspec",
-        paths=(),
-        label="OpenSpec Changes",
-        description="OpenSpec change proposals",
-    ),
-    CrossCutSpec(
-        id="cross_stack_features",
-        paths=(),
-        label="Cross-Stack BDD",
-        description="End-to-end BDD features across components",
-    ),
-    CrossCutSpec(
-        id="cross_stack_tests",
-        paths=("aidlc/tests/contract", "aidlc/tests/cross-stack"),
-        label="Cross-Stack Tests",
-        description="Contract tests and cross-stack integration tests",
-    ),
-    CrossCutSpec(
-        id="provider",
-        paths=(
-            "aidlc/providers/tcb/provider.yaml",
-            "aidlc/providers/tcb/deployment.yaml",
-            "aidlc/providers/tcb/preview.yaml",
-        ),
-        label="Cloud Provider",
-        description="TCB (Tencent CloudBase) provider config",
-    ),
-    CrossCutSpec(
-        id="tools",
-        paths=(
-            "aidlc/tools/deploy_stack.py",
-            "aidlc/tools/contract_diff.py",
-            "aidlc/tools/generate_shared.py",
-            "aidlc/tools/bvt.py",
-        ),
-        label="Tooling Scripts",
-        description="deploy_stack / contract_diff / generate_shared / bvt scripts",
-    ),
-)
-
-
-CROSS_CUTTING_BY_ID: dict[str, CrossCutSpec] = {c.id: c for c in CROSS_CUTTING}
-
-
-TCB_PROVIDER_YAML = """provider:
-  name: tcb
-  display_name: Tencent CloudBase
-  default: true
-  version: 3.0.0
-
-storage:
-  object_storage: cloudbase-storage
-  document_db: docdb
-  relational_db: mysql
-  cdn: tencent-cloud-cdn
-"""
-
-TCB_DEPLOYMENT_YAML = """environments:
-  preview:
-    orchestrator: deploy_stack
-    strategy: unified
-    ttl: 24h
-  staging:
-    orchestrator: deploy_stack
-  production:
-    orchestrator: deploy_stack
-    pre_conditions:
-      - human-approval-gate
-"""
-
-TCB_PREVIEW_YAML = """preview:
-  orchestrator: deploy_stack
-  strategy: unified
-  ttl: 24h
-  auto_cleanup: true
-  db_sandbox: true
-"""
-
-CONTRACT_DIFF_PY = '''#!/usr/bin/env python3
-"""Contract diff tool — checks API/event contract compatibility."""
-import argparse
-import sys
-from pathlib import Path
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Check contract compatibility")
-    parser.add_argument("--base", default="origin/main", help="Base commit/branch")
-    parser.add_argument("--head", default="HEAD", help="Head commit/branch")
-    parser.add_argument("--contracts-dir", default="aidlc/contracts", help="Contracts directory")
-    parser.add_argument("--output", default="json", choices=["json", "text"], help="Output format")
-    args = parser.parse_args()
-
-    contracts_dir = Path(args.contracts_dir)
-    if not contracts_dir.exists():
-        print(f"No contracts directory found: {contracts_dir}")
-        sys.exit(1)
-
-    api_dir = contracts_dir / "api"
-    events_dir = contracts_dir / "events"
-
-    changes = {"breaking": [], "additions": [], "deletions": []}
-
-    if args.output == "json":
-        import json
-        print(json.dumps(changes, indent=2))
-    else:
-        print("Contract diff complete. No breaking changes detected.")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()
-'''
-
-DEPLOY_STACK_PY = '''#!/usr/bin/env python3
-"""Deploy stack tool — deploys unified stack to target environment."""
-import argparse
-import sys
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Deploy unified stack")
-    parser.add_argument("--environment", "-e", required=True, choices=["preview", "staging", "production"])
-    parser.add_argument("--components", nargs="*", help="Components to deploy (default: all)")
-    parser.add_argument("--output", choices=["url", "json"], help="Output format")
-    args = parser.parse_args()
-
-    if args.environment == "production":
-        print("WARNING: Deploying to production requires human approval gate")
-        print("Use --approve flag to confirm production deployment")
-
-    output = {
-        "environment": args.environment,
-        "components": args.components or ["all"],
-        "url": f"https://preview.example.com",
-    }
-
-    if args.output == "json":
-        import json
-        print(json.dumps(output, indent=2))
-    else:
-        print(f"Deployed to {args.environment}")
-        print(f"URL: {output['url']}")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()
-'''
-
-GENERATE_SHARED_PY = '''#!/usr/bin/env python3
-"""Generate shared types from OpenAPI/AsyncAPI contracts."""
-import argparse
-import sys
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Generate shared type definitions")
-    parser.add_argument("--contracts-dir", default="aidlc/contracts", help="Contracts directory")
-    parser.add_argument("--output-dir", default="aidlc/packages/shared", help="Output directory")
-    parser.add_argument("--lang", default="typescript", choices=["typescript", "python", "go"], help="Target language")
-    args = parser.parse_args()
-
-    contracts_dir = Path(args.contracts_dir)
-    if not contracts_dir.exists():
-        print(f"No contracts directory found: {contracts_dir}")
-        sys.exit(1)
-
-    output_dir = Path(args.output_dir)
-    output_dir.mkdir(parents=True, exist_ok=True)
-
-    print(f"Generated {args.lang} types in {output_dir}")
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()
-'''
-
-BVT_PY = '''#!/usr/bin/env python3
-"""BVT (Baseline Verification Test) — smoke test for production deployment."""
-import argparse
-import sys
-
-
-CHECKS = {
-    "health": ("Backend /health endpoint", lambda url: True),
-    "home": ("Web home page loads", lambda url: True),
-    "login": ("Core login flow works", lambda url: True),
-    "db": ("Database connectivity", lambda url: True),
-    "error_rate": ("Error rate < 0.1%", lambda url: True),
-}
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Run BVT smoke tests")
-    parser.add_argument("--url", required=True, help="Stack URL to test")
-    parser.add_argument("--checks", nargs="*", default=list(CHECKS.keys()), help="Checks to run")
-    parser.add_argument("--json", action="store_true", help="JSON output")
-    args = parser.parse_args()
-
-    results = {}
-    for check in args.checks:
-        if check in CHECKS:
-            results[check] = {"passed": True, "description": CHECKS[check][0]}
-        else:
-            results[check] = {"passed": False, "error": f"Unknown check: {check}"}
-
-    passed = sum(1 for r in results.values() if r.get("passed"))
-    total = len(results)
-
-    if args.json:
-        import json
-        print(json.dumps({"passed": passed, "total": total, "results": results}, indent=2))
-    else:
-        print(f"BVT: {passed}/{total} checks passed")
-        for check, result in results.items():
-            status = "✓" if result.get("passed") else "✗"
-            print(f"  {status} {check}: {result.get('description') or result.get('error')}")
-
-    sys.exit(0 if passed == total else 1)
-
-
-if __name__ == "__main__":
-    main()
-'''
-
-TOOL_STUB = '''#!/usr/bin/env python3
-"""Stub — auto-generated by cdh scaffold."""
-import sys
-
-
-def main():
-    print(f"{__file__}: not yet implemented")
-    sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()
-'''
-
-ALIYUN_PROVIDER_YAML = """provider:
-  name: aliyun
-  display_name: Alibaba Cloud
-  default: false
-  version: 3.0.0
-
-storage:
-  object_storage: oss
-  document_db: mongodb
-  relational_db: rds-mysql
-  cdn: aliyun-cdn
-"""
-
-ALIYUN_DEPLOYMENT_YAML = """environments:
-  preview:
-    orchestrator: deploy_stack
-    strategy: unified
-    ttl: 24h
-  staging:
-    orchestrator: deploy_stack
-  production:
-    orchestrator: deploy_stack
-    pre_conditions:
-      - human-approval-gate
-"""
-
-ALIYUN_PREVIEW_YAML = """preview:
-  orchestrator: deploy_stack
-  strategy: unified
-  ttl: 24h
-  auto_cleanup: true
-  db_sandbox: true
-"""
-
-GITHUB_ACTIONS_CI_YAML = """name: AIDLC Quality Gates
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.14"
-      - name: Install cdh
-        run: pip install cdh
-      - name: Validate spec quality
-        run: cdh aidlc validate --format json
-      - name: Contract compat check
-        run: |
-          cdh aidlc tools install
-          python aidlc/tools/contract_diff.py --base origin/main --head HEAD \\
-            --project-root .
-      - name: Run tests
-        run: |
-          pip install pytest pytest-cov pytest-bdd
-          pytest --cov --cov-fail-under=80
-"""
-
-PRE_COMMIT_CONFIG_YAML = """repos:
-  - repo: local
-    hooks:
-      - id: aidlc-validate
-        name: aidlc validate
-        entry: cdh aidlc validate
-        language: system
-        pass_filenames: false
-        always_run: true
-      - id: aidlc-contract-diff
-        name: aidlc contract diff
-        entry: python aidlc/tools/contract_diff.py --base origin/main --head HEAD
-        language: system
-        pass_filenames: false
-        always_run: true
-"""
-
-CONFTEST_PY = '''"""Auto-generated by cdh scaffold."""
-import json
-from pathlib import Path
-import pytest
-
-
-def pytest_addoption(parser):
-    parser.addoption("--base-url", default="http://localhost:8080", help="Base URL for e2e tests")
-    parser.addoption("--api-url", default="", help="API URL")
-    parser.addoption("--stack-url", default="", help="Stack preview URL")
-
-
-@pytest.fixture
-def base_url(request):
-    return request.config.getoption("--base-url")
-
-
-@pytest.fixture
-def api_url(request):
-    return request.config.getoption("--api-url") or request.config.getoption("--base-url")
-'''
-
-PYPROJECT_TOML = """[tool.pytest.ini_options]
-minversion = "8.0"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-markers = [
-    "unit: unit tests",
-    "integration: integration tests",
-    "e2e: end-to-end tests",
-    "contract: contract tests",
-    "cross_stack: cross-stack tests",
-    "positive: positive scenarios",
-    "negative: negative/error scenarios",
-    "edge: edge case scenarios",
-]
-"""
-
-DOCKER_COMPOSE_YAML = """version: "3.9"
-services:
-  postgres:
-    image: postgres:16-alpine
-    environment:
-      POSTGRES_DB: aidlc
-      POSTGRES_USER: aidlc
-      POSTGRES_PASSWORD: aidlc
-    ports:
-      - "5432:5432"
-    tmpfs: /var/lib/postgresql/data
-
-  redis:
-    image: redis:7-alpine
-    ports:
-      - "6379:6379"
-
-  minio:
-    image: minio/minio:latest
-    command: server /data --console-address ":9001"
-    environment:
-      MINIO_ROOT_USER: aidlc
-      MINIO_ROOT_PASSWORD: aidlc123456
-    ports:
-      - "9000:9000"
-      - "9001:9001"
-"""
-
-ENV_LOCAL = """BACKEND_URL=http://localhost:8080
-DATABASE_URL=postgresql://aidlc:aidlc@localhost:5432/aidlc
-REDIS_URL=redis://localhost:6379/0
-S3_ENDPOINT=http://localhost:9000
-S3_ACCESS_KEY=aidlc
-S3_SECRET_KEY=aidlc123456
-"""
-
-GITIGNORE_CONTENT = """# Python
-__pycache__/
-*.py[cod]
-*.egg-info/
-dist/
-build/
-.venv/
-venv/
-*.egg
-
-# Node
-node_modules/
-.next/
-dist/
-.nuxt/
-.cache/
-
-# IDE
-.vscode/
-.idea/
-*.swp
-*.swo
-*~
-
-# OS
-.DS_Store
-Thumbs.db
-
-# CDH
-.cdh/
-"""
-
-CHANGELOG_MD = "# Changelog\n\n## [0.1.0] - Initial scaffold\n\n- Project created via cdh scaffold\n"
-
-
-
-
-AGENTS_HEADER = """# AGENTS.md — {project_name}
-
-<!-- ═══════════════════════════════════════════════════════════
-     AI-DLC Project Context — version {ai_dlc_version}
-     Skill Location: {{SKILL_PATH}}
-     This file contains PROJECT-SPECIFIC rules only.
-     Core skill definitions are in `SKILL.md` (injected separately).
-     DO NOT duplicate skill content here.
-     ═══════════════════════════════════════════════════════════ -->
-
-"""
-
-PROJECT_RULES_BLOCK = """
-## Quality Gates
-
-| Gate | Threshold |
-|------|-----------|
-| Coverage | ≥{coverage_min}% |
-| BDD pass rate | {bdd_pass_rate}% |
-| Contract diff | required |
-| No TODO in diff | true |
-| No secrets in diff | true |
-
-## Project Rules
-
-1. Intent → Spec (EARS) → BDD → Design (DAG) → TDD → Deploy
-2. Contract-first for cross-component changes
-3. Cross-stack e2e mandatory for ≥2 components
-4. Breaking changes require human approval
-5. Never commit secrets; never force-push to main/master
-"""
-
-CDH_COMMANDS_BLOCK = """
-## CDH Commands
-
-```bash
-# AI-DLC lifecycle
-cdh aidlc phase <understand|plan|verify|deliver>   # Set current phase
-cdh aidlc gate <name> --status <passed|failed>     # Record gate result
-cdh aidlc sync                                      # Regenerate AGENTS.md
-
-# Validation
-cdh aidlc validate --ears                           # EARS format check
-cdh aidlc validate --bdd                            # BDD coverage check
-cdh aidlc validate --fr                             # FR namespace check
-cdh aidlc validate --dag                            # Task DAG check
-
-# Project management
-cdh project list                                    # List projects
-cdh project load <name>                             # Load project
-```
-"""
-
-STATE_FILE_BLOCK = """
-## State File
-
-`.cdh/state.json` — AI-DLC project state
-
-| Field | Description |
-|-------|-------------|
-| `current_phase` | Current phase (understand/plan/verify/deliver) |
-| `completed_phases` | Array of completed phase names |
-| `gate_results` | Gate validation results |
-| `task_registry` | Task history with fingerprints |
-"""
-
-MDC_FRONTMATTER = """---
-description: AI-DLC Project Context
-globs: ["*"]
----
-
-"""
-
-REQUIREMENTS_MD = """# {project_name}
-
-## Intent
-
-{description}
-
-## Stack Topology
-
-Monorepo multi-component stack with the following components:
-
-| Component | FR Prefix | Default Language | Default UI Framework | Directory |
-|-----------|-----------|-----------------|---------------------|-----------|
-{component_table}
-
-## Quality Gates
-
-| Gate | Threshold |
-|------|-----------|
-| Unit/integration coverage | >= 80% |
-| BDD scenarios pass | 100% |
-| Contract tests pass | 100% |
-| Cross-stack e2e pass | 100% |
-| Security vulns | 0 |
-
-Default cloud provider: TCB (Tencent CloudBase).
-"""
-
-CONFIG_MD = """# AI-DLC Configuration
-
-This file defines path variables and settings used across AI-DLC phases.
-
-## Path Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `{spec_dir}` | `aidlc/openspec/changes/` | Spec delta documents |
-| `{features_dir}` | `apps/{component}/features/` | BDD feature files |
-| `{contracts_api}` | `aidlc/contracts/api/` | OpenAPI contract definitions |
-| `{contracts_events}` | `aidlc/contracts/events/` | AsyncAPI event definitions |
-| `{shared_types}` | `aidlc/packages/shared/` | Generated shared types |
-| `{cross_stack_features}` | `aidlc/features/cross-stack/` | Cross-stack BDD features |
-| `{unit_tests}` | `apps/{component}/tests/unit/` | Unit tests |
-| `{integration_tests}` | `apps/{component}/tests/integration/` | Integration tests |
-| `{e2e_tests}` | `apps/{component}/tests/e2e/` | E2E tests |
-| `{cross_stack_tests}` | `aidlc/tests/cross-stack/` | Cross-stack integration tests |
-
-## Phase Settings
-
-### Understand Phase
-- `und_min_scenarios`: 3  # Minimum BDD scenarios per FR
-- `und_require_ears`: true  # Require EARS format
-
-### Plan Phase
-- `plan_require_dag`: true  # Require task dependency DAG
-- `plan_require_test_plan`: true  # Require test plan before implementation
-
-### Verify Phase
-- `vrf_coverage_min`: 80  # Minimum coverage percentage
-- `vrf_bdd_pass_rate`: 100  # Required BDD pass rate
-- `vrf_contract_compat`: true  # Require contract backward compatibility
-
-### Deliver Phase
-- `dlv_preview_ttl`: 24h  # Preview environment TTL
-- `dlv_bvt_checks`: ["health", "home", "login", "db", "error_rate"]  # BVT check list
-
-## Component Overrides
-
-Components can override defaults:
-
-```yaml
-components:
-  backend:
-    features_dir: apps/backend/src/features/
-    test_dir: apps/backend/__tests__/
-```
-"""
-
-
-def _mkdir(path: Path) -> None:
-    path.mkdir(parents=True, exist_ok=True)
-
-
-def _gitkeep(path: Path) -> None:
-    keep = path / ".gitkeep"
-    if not keep.exists():
-        keep.write_text("", encoding="utf-8")
-
-
-def _write(path: Path, content: str) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(content.lstrip("\n"), encoding="utf-8")
-
-
-def _build_agents_component_table(active: list[ComponentSpec]) -> str:
-    rows = ["| Prefix | Component | Directory | FR Namespace |"]
-    rows.append("|--------|-----------|-----------|--------------|")
-    for c in active:
-        component_map = {
-            "native": "Mobile",
-            "desktop": "Desktop",
-            "web": "Browser",
-            "backend": "Service",
-            "wxa": "WeChat Mini",
-            "mya": "Alipay Mini",
-            "tta": "TikTok Mini",
-        }
-        component = component_map.get(c.id, c.id.title())
-        rows.append(f"| {c.fr_prefix} | {component} | `{c.owns}/` | {c.fr_prefix}-FR-NNN |")
-    rows.append("| INT | Contracts | `aidlc/contracts/`, `aidlc/packages/shared/` | INT-FR-NNN |")
-    return "\n".join(rows)
-
-
-ENGINE_SKILL_PATHS = {
-    "opencode": Path.home() / ".opencode" / "skills",
-    "claude": Path.home() / ".claude" / "skills",
-    "onecode": Path.home() / ".onecode" / "skills",
-}
-
-
-def _find_skill_installation() -> Path | None:
-    """Find ai-dlc-skill installation (project-local or global).
-
-    Search order:
-    1. ~/.cdh/skills/ai-dlc-skill (canonical skill cache)
-    2. Engine-specific paths (symlinks created by cdh skills install)
-    3. cdh project-local ai-dlc-skill/
-    """
-    candidates = [
-        Path.home() / ".cdh" / "skills" / "ai-dlc-skill",
-    ]
-    for engine, engine_dir in ENGINE_SKILL_PATHS.items():
-        candidates.append(engine_dir / "ai-dlc-skill")
-
-    script_path = Path(__file__).resolve()
-    cdh_root = script_path.parents[1]
-    candidates.append(cdh_root / "ai-dlc-skill")
-    candidates.append(Path.home() / ".local" / "share" / "cdh" / "ai-dlc-skill")
-
-    for p in candidates:
-        if (p / "SKILL.md").exists():
-            return p
-    return None
-
-
-def create_engine_symlinks(skill_source: Path, workspace_root: Path) -> list[str]:
-    """Create symlinks from engine skill directories to the skill source.
-
-    Args:
-        skill_source: Path to the skill (e.g., ~/.cdh/skills/ai-dlc-skill/)
-        workspace_root: Path to the project workspace (for AGENTS.md symlinks)
-
-    Returns:
-        List of created symlink paths.
-    """
-    created = []
-    skipped = []
-
-    for engine, engine_dir in ENGINE_SKILL_PATHS.items():
-        if not engine_dir.exists():
-            skipped.append(engine)
-            logger.debug("Engine directory does not exist, skipping: %s", engine_dir)
-            continue
-
-        skill_link = engine_dir / skill_source.name
-        if not skill_link.exists() and not skill_link.is_symlink():
-            try:
-                skill_link.parent.mkdir(parents=True, exist_ok=True)
-                os.symlink(skill_source, skill_link)
-                created.append(str(skill_link))
-            except OSError as e:
-                logger.warning("Failed to create symlink for %s: %s", engine, e)
-
-    if skipped:
-        logger.info("Skipped symlinks for engines without directories: %s", ", ".join(skipped))
-
-    return created
-
-
-def _read_skill_body(skill_path: Path) -> str:
-    """Read SKILL.md and strip YAML frontmatter, return body only."""
-    if not skill_path.exists():
-        return ""
-    raw = skill_path.read_text(encoding="utf-8")
-    body = re.sub(r'^---[\s\S]*?\n---\n?', '', raw)
-    return body.strip()
-
-
-def _read_skill_file(skill_root: Path | None, relative_path: str) -> str:
-    """Read a file from the skill installation directory."""
-    if not skill_root:
-        return ""
-    file_path = skill_root / relative_path
-    if not file_path.exists():
-        return ""
-    try:
-        return file_path.read_text(encoding="utf-8")
-    except Exception:
-        return ""
-
-
-_COMPLEXITY_SECTION_PATTERN = re.compile(
-    r'(##\s+Complexity\s+Evaluation\s+Checklist.*?)'
-    r'(##\s+Quick\s+Decision\s+Table)',
-    re.DOTALL
-)
-
-
-def _extract_complexity_section(content: str) -> str:
-    """Extract the complexity evaluation checklist section."""
-    match = _COMPLEXITY_SECTION_PATTERN.search(content)
-    if match:
-        return "\n## Complexity Evaluation Checklist\n\n" + match.group(1).strip() + "\n"
-    return ""
-
-
-def _write_symlink(target: Path, link_path: Path) -> None:
-    """Create a relative symlink link_path → target."""
-    link_path.parent.mkdir(parents=True, exist_ok=True)
-    if link_path.is_symlink() or link_path.exists():
-        link_path.unlink()
-    rel = os.path.relpath(target, link_path.parent)
-    link_path.symlink_to(rel)
-
-
-def _get_aidlc_version(skill_yaml_path: Path) -> str:
-    """Get AI-DLC version from skill.yaml."""
-    if skill_yaml_path.exists():
-        try:
-            data = yaml.safe_load(skill_yaml_path.read_text(encoding="utf-8"))
-            return str(data.get("version", "unknown"))
-        except Exception:
-            pass
-    return "unknown"
-
-
-def _get_quality_gates(skill_yaml_path: Path) -> dict:
-    """Get quality gates from skill.yaml."""
-    defaults = {
-        "coverage_min": 80,
-        "bdd_pass_rate": 100,
-        "contract_diff": True,
-        "no_todo": True,
-        "no_secrets_in_diff": True,
-    }
-    if not skill_yaml_path.exists():
-        return defaults
-    try:
-        data = yaml.safe_load(skill_yaml_path.read_text(encoding="utf-8"))
-        gates = data.get("quality_gates", {}) if data else {}
-        return {
-            "coverage_min": gates.get("coverage_min", defaults["coverage_min"]),
-            "bdd_pass_rate": gates.get("bdd_pass_rate", defaults["bdd_pass_rate"]),
-            "contract_diff": gates.get("contract_diff", defaults["contract_diff"]),
-            "no_todo": gates.get("no_todo", defaults["no_todo"]),
-            "no_secrets_in_diff": gates.get("no_secrets_in_diff", defaults["no_secrets_in_diff"]),
-        }
-    except Exception:
-        return defaults
-
-
-def _get_skill_path_for_agents(skill_instal: Path) -> str:
-    """Get the skill path for AGENTS.md header.
-
-    Returns the canonical path if skill is in ~/.cdh/skills/, otherwise
-    returns the actual resolved path. This helps LLM locate SKILL.md.
-    """
-    canonical = Path.home() / ".cdh" / "skills" / "ai-dlc-skill"
-    if skill_instal.resolve() == canonical.resolve():
-        return str(canonical)
-    return str(skill_instal)
-
-
-def _write_agents_and_claude_md(
-    root: Path,
-    project_name: str,
-    description: str,
-    active: list[ComponentSpec],
-) -> None:
-    # Read AI-DLC skill installation
-    skill_instal = _find_skill_installation()
-    if skill_instal:
-        skill_yaml = skill_instal / "skill.yaml"
-    else:
-        skill_yaml = root / "ai-dlc-skill" / "skill.yaml"
-        skill_instal = root / "ai-dlc-skill"
-
-    aidlc_version = _get_aidlc_version(skill_yaml)
-    quality_gates = _get_quality_gates(skill_yaml)
-
-    skill_path = _get_skill_path_for_agents(skill_instal)
-
-    component_table = _build_agents_component_table(active)
-
-    adaptive_flow_content = _read_skill_file(skill_instal, "core/adaptive-flow.md")
-    complexity_section = ""
-    if adaptive_flow_content:
-        complexity_section = _extract_complexity_section(adaptive_flow_content)
-
-    agents_content = (
-        AGENTS_HEADER.format(project_name=project_name, ai_dlc_version=aidlc_version, SKILL_PATH=skill_path)
-        + PROJECT_RULES_BLOCK.format(
-            coverage_min=quality_gates["coverage_min"],
-            bdd_pass_rate=quality_gates["bdd_pass_rate"],
-        )
-        + CDH_COMMANDS_BLOCK
-        + STATE_FILE_BLOCK
-        + "\n## Components\n\n"
-        + component_table
-        + "\n"
-        + complexity_section
-    )
-    _write(root / "AGENTS.md", agents_content)
-
-    # ── Symlinks to AGENTS.md for engine-native discovery ──
-    symlinks = [
-        root / "CLAUDE.md",
-        root / ".clinerules",
-        root / ".github" / "copilot-instructions.md",
-    ]
-    for link_path in symlinks:
-        _write_symlink(root / "AGENTS.md", link_path)
-
-    # ── .cursor/rules/ai-dlc-core.mdc (same as AGENTS.md for Cursor) ──
-    cursor_dir = root / ".cursor" / "rules"
-    cursor_dir.mkdir(parents=True, exist_ok=True)
-    mdc_content = (
-        MDC_FRONTMATTER
-        + PROJECT_RULES_BLOCK.format(
-            coverage_min=quality_gates["coverage_min"],
-            bdd_pass_rate=quality_gates["bdd_pass_rate"],
-        )
-        + CDH_COMMANDS_BLOCK
-        + STATE_FILE_BLOCK
-        + "\n## Components\n\n"
-        + component_table
-        + "\n"
-        + complexity_section
-    )
-    (cursor_dir / "ai-dlc-core.mdc").write_text(mdc_content.lstrip("\n"), encoding="utf-8")
-
-
-def _component_to_dict(c: ComponentSpec) -> dict:
-    out = {
-        "id": c.id,
-        "kind": c.kind,
-        "tech": c.tech,
-        "owns": c.owns,
-        "fr_prefix": c.fr_prefix,
-    }
-    return out
-
-
-def _build_project_yaml(
-    active: list[ComponentSpec],
-    cross_cutting_ids: list[str],
-    name: str = "",
-    description: str = "",
-) -> dict:
-    cross_cutting: dict = {"fr_prefix": "INT"}
-    if "contracts" in cross_cutting_ids:
-        cross_cutting["contracts"] = "aidlc/contracts/"
-    if "shared" in cross_cutting_ids:
-        cross_cutting["shared_types"] = "aidlc/packages/shared/"
-    doc: dict = {
-        "name": name,
-        "description": description,
-        "stack": {
-            "topology": "monorepo",
-            "components": [_component_to_dict(c) for c in active],
-            "cross_cutting": cross_cutting,
-        },
-        "settings": {
-            "aidlc_mode": "L2",
-        },
-    }
-    return doc
-
-
-def _build_component_table(active: list[ComponentSpec]) -> str:
-    if not active:
-        return "| (none)       | -             | -                 | -                   | -                   |"
-    return "\n".join(
-        f"| {c.id:8s} | {c.fr_prefix + '-FR-*':14s} | {'-':17s} | {'-':21s} | {c.owns:20s} |"
-        for c in active
-    )
-
-
-def _scaffold_component(c: ComponentSpec, root: Path) -> None:
-    comp_dir = root / c.owns
-    _mkdir(comp_dir / "src")
-    if c.kind == "mini-program":
-        _mkdir(comp_dir / "tests" / "e2e")
-        _gitkeep(comp_dir / "tests" / "e2e")
-    else:
-        _mkdir(comp_dir / "tests" / "unit")
-        _mkdir(comp_dir / "tests" / "integration")
-        _mkdir(comp_dir / "tests" / "e2e")
-        _gitkeep(comp_dir / "tests" / "unit")
-        _gitkeep(comp_dir / "tests" / "integration")
-        _gitkeep(comp_dir / "tests" / "e2e")
-    _mkdir(comp_dir / "features")
-    _gitkeep(comp_dir / "features")
-    _gitkeep(comp_dir / "src")
-    _gitkeep(comp_dir)
-
-
-def _scaffold_cross_cutting(cross_ids: list[str], root: Path) -> None:
-    for cid in cross_ids:
-        spec = CROSS_CUTTING_BY_ID.get(cid)
-        if spec is None:
-            continue
-        for p in spec.paths:
-            target = root / p
-            if p.endswith((".yaml", ".py", ".md")):
-                if p == "aidlc/contracts/CHANGELOG.md":
-                    _write(target, CHANGELOG_MD)
-                elif p == "aidlc/providers/tcb/provider.yaml":
-                    _write(target, TCB_PROVIDER_YAML)
-                elif p == "aidlc/providers/tcb/deployment.yaml":
-                    _write(target, TCB_DEPLOYMENT_YAML)
-                elif p == "aidlc/providers/tcb/preview.yaml":
-                    _write(target, TCB_PREVIEW_YAML)
-                elif p == "aidlc/tools/deploy_stack.py":
-                    _write(target, DEPLOY_STACK_PY)
-                    target.chmod(0o755)
-                elif p == "aidlc/tools/contract_diff.py":
-                    _write(target, CONTRACT_DIFF_PY)
-                    target.chmod(0o755)
-                elif p == "aidlc/tools/generate_shared.py":
-                    _write(target, GENERATE_SHARED_PY)
-                    target.chmod(0o755)
-                elif p == "aidlc/tools/bvt.py":
-                    _write(target, BVT_PY)
-                    target.chmod(0o755)
-                else:
-                    _write(target, TOOL_STUB if p.endswith(".py") else "")
-                    if p.endswith(".py"):
-                        target.chmod(0o755)
-            else:
-                _mkdir(target)
-                _gitkeep(target)
-
-
-def _scaffold_ci_templates(root: Path, component_ids: list[str] | None = None) -> None:
-    ci_dir = root / ".github" / "workflows"
-    ci_dir.mkdir(parents=True, exist_ok=True)
-    (ci_dir / "aidlc-ci.yaml").write_text(GITHUB_ACTIONS_CI_YAML, encoding="utf-8")
-    (root / ".pre-commit-config.yaml").write_text(PRE_COMMIT_CONFIG_YAML, encoding="utf-8")
-
-
-def _scaffold_test_templates(root: Path, component_ids: list[str] | None = None) -> None:
-    _write(root / "conftest.py", CONFTEST_PY)
-    _write(root / "pyproject.toml", PYPROJECT_TOML)
-
-
-def _scaffold_local_env(root: Path) -> None:
-    _write(root / "docker-compose.yaml", DOCKER_COMPOSE_YAML)
-    _write(root / ".env.local", ENV_LOCAL)
-    _write(root / ".env.example", ENV_LOCAL)
-
-
-def _scaffold_provider_templates(root: Path, provider: str | None) -> None:
-    if provider is None or provider == "tcb":
-        return
-    provider_dir = root / "aidlc" / "providers" / provider
-    provider_dir.mkdir(parents=True, exist_ok=True)
-    if provider == "aliyun":
-        _write(provider_dir / "provider.yaml", ALIYUN_PROVIDER_YAML)
-        _write(provider_dir / "deployment.yaml", ALIYUN_DEPLOYMENT_YAML)
-        _write(provider_dir / "preview.yaml", ALIYUN_PREVIEW_YAML)
-
-
-def _write_project_yaml(
-    root: Path,
-    project_name: str,
-    active: list[ComponentSpec],
-    cross_cutting_ids: list[str],
-    description: str,
-) -> None:
-    _write(
-        root / "aidlc" / "project.yaml",
-        yaml.dump(
-            _build_project_yaml(active, cross_cutting_ids, name=project_name, description=description),
-            default_flow_style=False,
-        ),
-    )
-    _write(
-        root / "aidlc" / "requirements.md",
-        REQUIREMENTS_MD.format(
-            project_name=project_name,
-            description=description or f"AI-DLC monorepo project: {project_name}",
-            component_table=_build_component_table(active),
-        ),
-    )
-    _write(root / "aidlc" / "CONFIG.md", CONFIG_MD)
-    _write(root / ".gitignore", GITIGNORE_CONTENT)
-    _write(root / "aidlc" / "CHANGELOG.md", CHANGELOG_MD)
-
-
-def init_dlc_project(
-    workspace_root: Path,
-    project_name: str,
-    description: str = "",
-    with_ci: bool = False,
-    with_tests: bool = False,
-    with_local: bool = False,
-    provider: str | None = None,
-) -> bool:
-    """Scaffold project metadata only (no apps/*, no cross-cutting dirs)."""
-
-    root = workspace_root.resolve()
-    _write_project_yaml(
-        root=root,
-        project_name=project_name,
-        active=[],
-        cross_cutting_ids=[],
-        description=description,
-    )
-    _write_agents_and_claude_md(root, project_name, description, [])
-
-    skill_instal = _find_skill_installation()
-    if skill_instal:
-        create_engine_symlinks(skill_instal, root)
-
-    if with_ci:
-        _scaffold_ci_templates(root)
-    if with_tests:
-        _scaffold_test_templates(root)
-    if with_local:
-        _scaffold_local_env(root)
-    if provider:
-        _scaffold_provider_templates(root, provider)
-    return True
-
-
-def scaffold_dlc_project(
-    workspace_root: Path,
-    project_name: str,
-    components: list[str] | None = None,
-    description: str = "",
-    with_ci: bool = False,
-    with_tests: bool = False,
-    with_local: bool = False,
-    provider: str | None = None,
-) -> bool:
-    """Scaffold a full ai-dlc-skill monorepo project structure.
-
-    Application components are optional — when omitted only cross-cutting
-    items (contracts, shared types, openspec, etc.) are created.
-    Components can be added later with add_component().
-
-    Args:
-        components: list of component ids (e.g. ["web", "backend"]).
-                   If None or empty, only cross-cutting items are scaffolded.
-
-    Returns True if scaffolding was performed.
-
-    Raises ValueError if any component id is unknown.
-    """
-    if components is None:
-        components = []
-
-    unknown = [c for c in components if c not in COMPONENT_BY_ID]
-    if unknown:
-        raise ValueError(
-            f"Unknown component id(s): {', '.join(unknown)}. "
-            f"Valid ids: {', '.join(COMPONENT_BY_ID)}."
-        )
-
-    root = workspace_root.resolve()
-    active = [COMPONENT_BY_ID[cid] for cid in components]
-    all_cross_ids = [
-        c.id for c in CROSS_CUTTING if c.id not in ("provider", "tools")
-    ]
-
-    _write_project_yaml(
-        root=root,
-        project_name=project_name,
-        active=active,
-        cross_cutting_ids=all_cross_ids,
-        description=description,
-    )
-
-    for c in active:
-        _scaffold_component(c, root)
-
-    _scaffold_cross_cutting(all_cross_ids, root)
-    _write_agents_and_claude_md(root, project_name, description, active)
-
-    skill_instal = _find_skill_installation()
-    if skill_instal:
-        create_engine_symlinks(skill_instal, root)
-
-    if with_ci:
-        _scaffold_ci_templates(root, components)
-    if with_tests:
-        _scaffold_test_templates(root, components)
-    if with_local:
-        _scaffold_local_env(root)
-    if provider:
-        _scaffold_provider_templates(root, provider)
-
-    return True
-
-
-def _regenerate_agents_and_claude_md(root: Path) -> None:
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        return
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    name = data.get("name", root.name)
-    description = data.get("description", "")
-    components = data.get("stack", {}).get("components", []) or []
-    active = []
-    for c in components:
-        spec = COMPONENT_BY_ID.get(c.get("id", ""))
-        if spec:
-            active.append(spec)
-    _write_agents_and_claude_md(root, name, description, active)
-
-
-def add_component(
-    workspace_root: Path,
-    component_id: str,
-) -> bool:
-    """Add a single application component to an existing project.
-
-    Creates apps/<owns>/{src,tests/unit,tests/e2e,features} with
-    .gitkeep files and updates aidlc/project.yaml's stack.components list.
-
-    Returns True if the component was added, False if it was already
-    present. Raises ValueError on unknown component id.
-    """
-    spec = COMPONENT_BY_ID.get(component_id)
-    if spec is None:
-        raise ValueError(
-            f"Unknown component id: {component_id}. "
-            f"Valid ids: {', '.join(COMPONENT_BY_ID)}."
-        )
-
-    root = workspace_root.resolve()
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        raise FileNotFoundError(
-            f"aidlc/project.yaml not found at {root}. Run 'cdh project init' first."
-        )
-
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    components = data.get("stack", {}).get("components", []) or []
-    if any(c.get("id") == component_id for c in components):
-        return False
-
-    _scaffold_component(spec, root)
-
-    components.append(_component_to_dict(spec))
-    data["stack"]["components"] = components
-    project_yaml.write_text(
-        yaml.dump(data, default_flow_style=False),
-        encoding="utf-8",
-    )
-    _regenerate_agents_and_claude_md(root)
-    return True
-
-
-def add_cross_cutting(
-    workspace_root: Path,
-    cross_id: str,
-) -> bool:
-    """Add a single cross-cutting item to an existing project.
-
-    Creates the relevant directories/files and updates aidlc/project.yaml
-    so that stack.cross_cutting references the new path.
-
-    Returns True if the item was added, False if it was already present.
-    Raises ValueError on unknown cross-cutting id.
-    """
-    spec = CROSS_CUTTING_BY_ID.get(cross_id)
-    if spec is None:
-        raise ValueError(
-            f"Unknown cross-cutting id: {cross_id}. "
-            f"Valid ids: {', '.join(CROSS_CUTTING_BY_ID)}."
-        )
-
-    root = workspace_root.resolve()
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        raise FileNotFoundError(
-            f"aidlc/project.yaml not found at {root}. Run 'cdh project init' first."
-        )
-
-    cross_paths = [root / p for p in spec.paths]
-    if all(p.exists() for p in cross_paths):
-        return False
-
-    _scaffold_cross_cutting([cross_id], root)
-
-    data = yaml.safe_load(project_yaml.read_text(encoding="utf-8")) or {}
-    cross_cutting = data.setdefault("stack", {}).setdefault("cross_cutting", {})
-    if cross_id == "contracts":
-        cross_cutting["contracts"] = "aidlc/contracts/"
-    elif cross_id == "shared":
-        cross_cutting["shared_types"] = "packages/shared/"
-
-    project_yaml.write_text(
-        yaml.dump(data, default_flow_style=False),
-        encoding="utf-8",
-    )
-    _regenerate_agents_and_claude_md(root)
-    return True
-
-
-def check_dlc_project(workspace_root: Path) -> dict:
-    """Check whether a directory is a valid AIDC project and return diagnostics.
-
-    Returns a dict with keys:
-      valid        — bool, whether the project is minimally valid
-      name         — str or None
-      path         — str (resolved root)
-      components   — list of component ids
-      has_cdh      — bool
-      suggestions  — list of human-readable improvement suggestions
-    """
-    root = workspace_root.resolve()
-    result: dict = {
-        "valid": True,
-        "name": None,
-        "path": str(root),
-        "components": [],
-        "has_cdh": False,
-        "suggestions": [],
-    }
-
-    project_yaml = root / "aidlc" / "project.yaml"
-    if not project_yaml.exists():
-        result["suggestions"].append(
-            f"Missing aidlc/project.yaml — run 'cdh aidlc init {root}' first"
-        )
-        result["valid"] = False
-        return result
-
-    try:
-        data = yaml.safe_load(project_yaml.read_text(encoding="utf-8"))
-    except Exception as e:
-        result["suggestions"].append(f"Invalid YAML in aidlc/project.yaml: {e}")
-        result["valid"] = False
-        return result
-
-    if not isinstance(data, dict):
-        result["suggestions"].append("aidlc/project.yaml is not a valid YAML mapping")
-        result["valid"] = False
-        return result
-
-    name = data.get("name", "")
-    if not name:
-        result["suggestions"].append("Missing 'name' field in aidlc/project.yaml")
-        result["valid"] = False
-        name = root.name
-    result["name"] = name
-
-    components = data.get("stack", {}).get("components", [])
-    if not components:
-        result["suggestions"].append(
-            "No components defined in stack.components — "
-            "use 'cdh aidlc add-component' to add one"
-        )
-    else:
-        ids = []
-        for c in components:
-            cid = c.get("id", "")
-            if not cid:
-                result["suggestions"].append(
-                    "A component entry is missing its 'id' field"
-                )
-                continue
-            ids.append(cid)
-            if cid not in COMPONENT_BY_ID:
-                result["suggestions"].append(
-                    f"Unknown component id '{cid}' — expected one of: "
-                    f"{', '.join(COMPONENT_BY_ID)}"
-                )
-            else:
-                owns = COMPONENT_BY_ID[cid].owns
-                if not (root / owns).exists():
-                    result["suggestions"].append(
-                        f"Component '{cid}' directory '{owns}/' not found on disk"
-                    )
-        result["components"] = ids
-
-    cross_cutting = data.get("stack", {}).get("cross_cutting", {})
-    if isinstance(cross_cutting, dict):
-        for key, path_val in cross_cutting.items():
-            if isinstance(path_val, str) and not (root / path_val).exists():
-                result["suggestions"].append(
-                    f"Cross-cutting '{key}' path '{path_val}' not found on disk"
-                )
-
-    from cdh.project_loader import CdhProjectLoader
-    result["has_cdh"] = CdhProjectLoader.find_cdh_dir(root) is not None
-    if not result["has_cdh"]:
-        result["suggestions"].append(
-            ".cdh/ not found — run 'cdh aidlc init' to set up project state"
-        )
-
-    return result
-
-
-__all__ = [
-    "COMPONENTS",
-    "COMPONENT_BY_ID",
-    "CROSS_CUTTING",
-    "CROSS_CUTTING_BY_ID",
-    "ComponentSpec",
-    "CrossCutSpec",
-    "init_dlc_project",
-    "scaffold_dlc_project",
-    "add_component",
-    "add_cross_cutting",
-    "check_dlc_project",
-    "_regenerate_agents_and_claude_md",
-]