cc-codeconductor 1.1.0 → 1.3.0

package/presets/pi/AGENTS.md

@@ -0,0 +1,43 @@
+<!-- CODECONDUCTOR:BEGIN managed -->
+
+# CodeConductor — Pi Preset
+
+This file configures CodeConductor for **Pi** (pi.dev — `earendil-works/pi`,
+the coding-agent CLI, not Inflection's Pi). It lives at the project root
+(`AGENTS.md`) so Pi's context-file loader picks it up automatically.
+
+## Behavioral Discipline
+
+1. **Think Before Coding** — state assumptions; ask if uncertain; present
+   alternatives instead of picking silently.
+2. **Simplicity First** — minimum code that solves the problem; no
+   speculative abstractions.
+3. **Surgical Changes** — touch only what the task requires; match existing
+   style; remove only what your own change made unused.
+4. **Goal-Driven Execution** — turn the task into a verifiable goal with a
+   success check; loop until it passes.
+
+## Commands
+
+CodeConductor ships its slash commands as Pi prompt templates under
+`.pi/prompts/`, invoked as `/cc-<name>` (e.g. `/cc-feature`, `/cc-review`).
+Run `/cc-ask "<problem>"` when unsure which one applies — it recommends
+exactly one and stops; it does not start the workflow.
+
+Skills live under `.agents/skills/` (shared with the agy preset — Pi
+discovers skills there natively, per its own docs). Read
+`.agents/skills/using-cc-skills/SKILL.md` first — it maps intent to the
+right slash command.
+
+Pi has no Task tool or subagents: every command runs in your own session.
+Where a step says "adopt the `X` role", read the matching file under
+`.agents/agents/` (short) or `.agents/prompts/v1.0.0/` (full contract) and
+act as that role for the rest of the step.
+
+## What never changes
+
+- Do not invoke the Implementer without an accepted Technical Plan.
+- Do not skip the Reviewer step for medium- or high-risk changes.
+- Do not store secrets in any file loaded by Pi.
+
+<!-- CODECONDUCTOR:END managed -->

package/presets/pi/settings.json

@@ -0,0 +1,3 @@
+{
+  "enableSkillCommands": true
+}

package/presets/seo-hotel/skills/astro-seo/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: astro-seo
-version: 1.0.0
 name: Astro SEO Validator
 description: >
   SEO validation specific to Astro framework projects. Checks static generation,

package/presets/seo-hotel/skills/geo-readiness/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: geo-readiness
-version: 1.0.0
 name: GEO Readiness Checker
 description: >
   Validates AI-search readiness (Generative Engine Optimization) for hotel websites.

package/presets/seo-hotel/skills/off-page/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: off-page
-version: 1.0.0
 name: SEO Off-Page & Marketing
 description: >
   Guidance for off-page SEO strategy specific to hotel and hospitality websites.

package/presets/seo-hotel/skills/schema-validator/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: schema-validator
-version: 1.0.0
 name: Schema.org Validator
 description: >
   Validates Schema.org structured data (JSON-LD, Microdata, RDFa) on hotel and hospitality websites.

package/presets/seo-hotel/skills/seo-audit/SKILL.md

@@ -1,6 +1,5 @@
 ---
 id: seo-audit
-version: 1.0.0
 name: SEO Technical Audit
 description: >
   Comprehensive technical SEO audit for hotel websites. Checks meta tags, headings,

package/presets/shared/invoke-hook.cjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const { join, resolve } = require('node:path');
+
+const VALID_EVENTS = ['pre-tool', 'post-tool', 'session-start'];
+const SPAWN_TIMEOUT = 10000;
+
+const rawArgs = process.argv.slice(1);
+const args = rawArgs.filter((arg) => {
+  if (VALID_EVENTS.includes(arg) || arg.startsWith('-')) return true;
+  return false;
+});
+
+const event = args.find((a) => VALID_EVENTS.includes(a)) || 'pre-tool';
+const extra = args.filter((a) => a !== event);
+const isAgy = process.argv.some((a) => a === '--format=agy') || extra.includes('--format=agy');
+
+function findProjectRoot() {
+  const candidates = [
+    process.env.PROJECT_ROOT,
+    process.env.WORKSPACE_DIR,
+    resolve(__dirname, '..', '..'),
+    process.cwd(),
+  ].filter(Boolean);
+
+  for (const dir of candidates) {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, '.agents')) ||
+      existsSync(join(dir, '.claude'))
+    ) {
+      return dir;
+    }
+  }
+  return resolve(__dirname, '..', '..');
+}
+
+const projectRoot = findProjectRoot();
+
+/**
+ * Run one candidate runner. Stdout/stderr are captured (not inherited) so a
+ * candidate that writes partial output before failing can never leak onto
+ * this process's real stdout ahead of a later candidate's output or the
+ * fallback JSON — every event this process ever emits on stdout must be a
+ * single clean document. Stderr is diagnostic-only and safe to relay
+ * unconditionally; stdout is only ever relayed on the two branches that
+ * immediately exit, so nothing else can write to stdout afterward.
+ */
+function tryRun(bin, runArgs) {
+  try {
+    const result = spawnSync(bin, runArgs, {
+      cwd: projectRoot,
+      stdio: ['inherit', 'pipe', 'pipe'],
+      windowsHide: true,
+      env: process.env,
+      encoding: 'utf8',
+      timeout: SPAWN_TIMEOUT,
+    });
+    if (result.error) {
+      return false;
+    }
+    if (result.stderr) {
+      process.stderr.write(result.stderr);
+    }
+    if (result.status === 0) {
+      if (result.stdout) process.stdout.write(result.stdout);
+      process.exit(0);
+    }
+    if (!isAgy && result.status === 2) {
+      process.exit(2);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function fallback() {
+  if (isAgy) {
+    if (event === 'post-tool' || event === 'session-start') {
+      process.stdout.write('{}\n');
+    } else {
+      process.stdout.write('{"decision":"allow"}\n');
+    }
+  }
+  process.exit(0);
+}
+
+try {
+  // spawnSync('bun', ['--version']) as a pre-check before every real attempt
+  // used to cost a second subprocess on every single hook invocation. A
+  // missing/unrunnable 'bun' already surfaces as `result.error` inside
+  // tryRun(), so the pre-check is redundant — dropping it halves the spawn
+  // count (and the worst-case latency) for the common case where bun exists.
+  const srcMain = join(projectRoot, 'src', 'cli', 'main.ts');
+  if (existsSync(srcMain)) {
+    tryRun('bun', ['run', srcMain, 'hook', event, ...extra]);
+  }
+
+  const packaged = join(projectRoot, 'node_modules', 'cc-codeconductor', 'dist', 'index.js');
+  if (existsSync(packaged)) {
+    tryRun(process.execPath, [packaged, 'hook', event, ...extra]);
+  }
+
+  const localDist = join(projectRoot, 'dist', 'index.js');
+  if (existsSync(localDist)) {
+    tryRun(process.execPath, [localDist, 'hook', event, ...extra]);
+  }
+
+  tryRun('npx', ['--no-install', 'cc-codeconductor', 'hook', event, ...extra]);
+} catch {
+  // Ignore errors in runner attempts
+}
+
+fallback();

package/presets/shared/mutation_runner.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Deterministic mutation-testing runner (stdlib only).
+
+Applies single syntactic mutations over comparison operators in a Python
+production file and re-runs the test suite per mutant. If a mutant survives
+(tests still pass), the runner writes a handoff for the `tdd_craftsman` agent
+(`specs/handover.md`, appended to `specs/implementation-summary.md`, optional
+Engram/MCP memory hook) and exits with code 2 (HANDS_OFF). If every mutant is
+killed, it exits 0 (PASS). The original source is always restored.
+
+Usage:
+    python3 mutation_runner.py --target src/billing.py \
+        --test-command "pytest tests/test_billing.py" [--spec-folder specs]
+"""
+import argparse
+import ast
+import difflib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+@dataclass(frozen=True)
+class MutationRecord:
+    mutant_id: str
+    target_file: str
+    line_number: int
+    original_op: str
+    mutated_op: str
+    diff: str
+    survived: bool
+    details: str
+
+
+class DeterministicOperatorMutator(ast.NodeTransformer):
+    """Applies one deterministic syntactic mutation over a comparison operator."""
+
+    OP_MAP = {
+        ast.Gt: ast.LtE,      # >  -> <=
+        ast.Lt: ast.GtE,      # <  -> >=
+        ast.GtE: ast.Lt,      # >= -> <
+        ast.LtE: ast.Gt,      # <= -> >
+        ast.Eq: ast.NotEq,    # == -> !=
+        ast.NotEq: ast.Eq,    # != -> ==
+        ast.Is: ast.IsNot,    # is -> is not
+        ast.IsNot: ast.Is,    # is not -> is
+    }
+
+    def __init__(self, target_index: int):
+        super().__init__()
+        self.target_index = target_index
+        self.current_index = 0
+        self.applied_mutation: Optional[Tuple[int, str, str]] = None
+
+    def visit_Compare(self, node: ast.Compare) -> ast.AST:
+        mutated_ops = []
+        modified = False
+
+        for op in node.ops:
+            op_type = type(op)
+            if op_type in self.OP_MAP:
+                if self.current_index == self.target_index:
+                    new_op = self.OP_MAP[op_type]()
+                    mutated_ops.append(new_op)
+                    modified = True
+                    self.applied_mutation = (
+                        node.lineno,
+                        op_type.__name__,
+                        type(new_op).__name__,
+                    )
+                else:
+                    mutated_ops.append(op)
+                self.current_index += 1
+            else:
+                mutated_ops.append(op)
+
+        if modified:
+            node.ops = mutated_ops
+            return node
+        return self.generic_visit(node)
+
+
+class MutationEngine:
+    def __init__(self, target_file: str, test_command: str, spec_folder: str = "specs"):
+        self.target_file = Path(target_file).resolve()
+        self.test_command = test_command
+        self.spec_folder = Path(spec_folder)
+        self.original_source = self.target_file.read_text(encoding="utf-8")
+        self.spec_folder.mkdir(parents=True, exist_ok=True)
+
+    def _count_mutation_points(self) -> int:
+        tree = ast.parse(self.original_source)
+        count = 0
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Compare):
+                for op in node.ops:
+                    if type(op) in DeterministicOperatorMutator.OP_MAP:
+                        count += 1
+        return count
+
+    def _clear_bytecode_cache(self) -> None:
+        """Removes cached bytecode for the target so mutants are not shadowed
+        by a stale .pyc with an equal-mtimestamp source."""
+        cache_dir = self.target_file.parent / "__pycache__"
+        if cache_dir.is_dir():
+            for pyc in cache_dir.glob(f"{self.target_file.stem}.*.pyc"):
+                pyc.unlink(missing_ok=True)
+
+    def _run_test_suite(self) -> bool:
+        """Runs the test suite. Returns True if every test passes."""
+        self._clear_bytecode_cache()
+        env = {**os.environ, "PYTHONDONTWRITEBYTECODE": "1"}
+        result = subprocess.run(
+            self.test_command,
+            shell=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=env,
+        )
+        return result.returncode == 0
+
+    def _create_diff(self, mutated_source: str) -> str:
+        return "\n".join(
+            difflib.unified_diff(
+                self.original_source.splitlines(),
+                mutated_source.splitlines(),
+                fromfile=f"a/{self.target_file.name}",
+                tofile=f"b/{self.target_file.name}",
+                lineterm="",
+            )
+        )
+
+    def _persist_to_engram_or_markdown(self, record: MutationRecord) -> None:
+        """Documents the handoff in handover.md and implementation-summary.md."""
+        markdown_summary = self.spec_folder / "implementation-summary.md"
+        handover_file = self.spec_folder / "handover.md"
+
+        payload_md = f"""## Mutation Gate: Survivor Detected (TDD Gap)
+- **Target File**: `{record.target_file}`
+- **Line**: {record.line_number}
+- **Mutant ID**: `{record.mutant_id}`
+- **Operator Change**: `{record.original_op}` -> `{record.mutated_op}`
+- **Status**: SURVIVED (Scorecard Real Coverage: 0)
+
+### Reproduction Diff
+```diff
+{record.diff}
+```
+
+### Action Required by `tdd_craftsman`
+
+1. Do NOT touch production implementation.
+2. Write a minimal failing test (TDD Law 1 & 2) that asserts this branch condition.
+3. Verify the test turns red before re-verifying production code.
+"""
+        # Handover update for continuity
+        handover_file.write_text(payload_md, encoding="utf-8")
+
+        with markdown_summary.open("a", encoding="utf-8") as f:
+            f.write(f"\n\n{payload_md}")
+
+        # Optional Engram / MCP memory integration
+        self._notify_engram(record)
+
+    def _notify_engram(self, record: MutationRecord) -> None:
+        """Invokes the local Engram/Memory Engine hook or CLI if present."""
+        if shutil.which("engram"):
+            try:
+                subprocess.run(
+                    [
+                        "engram",
+                        "memory:save",
+                        "--tag",
+                        "mutation_testing",
+                        "--title",
+                        f"Survivor {record.mutant_id}",
+                        "--body",
+                        json.dumps(asdict(record)),
+                    ],
+                    check=False,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+            except Exception:
+                pass
+
+    def run(self) -> Dict[str, object]:
+        # 1. Pre-flight check: tests must pass on the clean base code
+        if not self._run_test_suite():
+            raise RuntimeError("The test suite is already failing on unmutated base code.")
+
+        total_points = self._count_mutation_points()
+        survivors: List[MutationRecord] = []
+
+        try:
+            for idx in range(total_points):
+                mutator = DeterministicOperatorMutator(target_index=idx)
+                tree = ast.parse(self.original_source)
+                mutated_tree = mutator.visit(tree)
+                ast.fix_missing_locations(mutated_tree)
+
+                mutated_source = ast.unparse(mutated_tree)
+                diff = self._create_diff(mutated_source)
+
+                # Apply mutant to disk
+                self.target_file.write_text(mutated_source, encoding="utf-8")
+
+                # Run tests against the mutant
+                passed = self._run_test_suite()
+
+                if passed:
+                    # The mutant survived: tests are blind to this change
+                    lineno, orig, mut = mutator.applied_mutation or (0, "Unknown", "Unknown")
+                    survivor = MutationRecord(
+                        mutant_id=f"MUT_{idx:03d}_L{lineno}",
+                        target_file=str(self.target_file),
+                        line_number=lineno,
+                        original_op=orig,
+                        mutated_op=mut,
+                        diff=diff,
+                        survived=True,
+                        details="Tests passed with inverted comparison logic. Missing explicit assert.",
+                    )
+                    survivors.append(survivor)
+
+                    # Safe Fail-Fast protocol: immediate handoff to the craftsman
+                    self._persist_to_engram_or_markdown(survivor)
+                    return {
+                        "status": "HANDS_OFF_TRIGGERED",
+                        "target_agent": "tdd_craftsman",
+                        "surviving_mutant": asdict(survivor),
+                    }
+
+        finally:
+            # Unconditional deterministic rollback: restore original source
+            self.target_file.write_text(self.original_source, encoding="utf-8")
+
+        return {
+            "status": "PASS",
+            "total_mutants_killed": total_points,
+            "survivors_count": 0,
+        }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Deterministic stdlib mutation runner.")
+    parser.add_argument("--target", required=True, help="Python production file to mutate.")
+    parser.add_argument("--test-command", required=True, help="Shell command that runs the test suite.")
+    parser.add_argument("--spec-folder", default="specs", help="Folder for handoff artifacts.")
+    args = parser.parse_args(argv)
+
+    engine = MutationEngine(
+        target_file=args.target,
+        test_command=args.test_command,
+        spec_folder=args.spec_folder,
+    )
+    outcome = engine.run()
+    print(json.dumps(outcome, indent=2))
+
+    if outcome["status"] == "HANDS_OFF_TRIGGERED":
+        # Exit code 2 tells the orchestrator (craftsman_lead) to reroute to tdd_craftsman
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/presets/council/council.yml

@@ -1,3 +1,14 @@
+# Single source of truth for the council roster (loaded by
+# src/core/presets/preset-loader.ts -> loadCouncilPreset, consumed by
+# `cc install council --target <t>` in src/commands/install.command.ts).
+# Per-role checklist and finding-format content lives in
+# src/domain/council/council-agent.ts (generateAgentContent /
+# checklistFor), shared by every generator except Codex, which renders
+# its own TOML shape in src/adapters/codex/codex-council-generator.ts.
+# Adding or renaming an agent here requires a matching entry in
+# ROLE_PROFILES (council-agent.ts) and, if it changes the roster's ids,
+# updating DEFAULT_COUNCIL_AGENTS in src/domain/council/council-spec.ts —
+# test/unit/domain/council/council-spec.test.ts asserts the two stay in sync.
 name: council
 version: 0.1.0
 description: Multi-agent council for code review and architecture decisions
@@ -13,15 +24,6 @@ agents:
       - design-patterns
       - code-structure
 
-  - id: security
-    role: Security
-    context: repo-readonly
-    modelHint: security-reasoning
-    focus:
-      - security
-      - vulnerabilities
-      - compliance
-
   - id: product
     role: Product
     context: prompt-only
@@ -56,6 +58,7 @@ agents:
     focus:
       - security
       - vulnerabilities
+      - compliance
       - credentials
       - injection
       - auth

package/src/presets/manifests/agy.yml

@@ -13,18 +13,20 @@ entries:
     strategy: overwrite
     template: true
   - src: agy/settings.json
-    dest: .agents/../antigravity-cli/settings.json
+    dest: antigravity-cli/settings.json
     strategy: skip
     globalStrategy: merge-json
   - src: agy/hooks.json
     dest: .agents/hooks.json
     strategy: overwrite
+    globalStrategy: skip
   - src: agy/mcp_config.json
     dest: .agents/mcp_config.json
     strategy: overwrite
   - src: agy/scripts
     dest: .agents/scripts
     strategy: overwrite
+    globalStrategy: skip
   - src: opencode/skills
     dest: .agents/skills
     strategy: overwrite

package/src/presets/manifests/claude.yml

@@ -9,6 +9,9 @@ entries:
     dest: .claude/settings.json
     strategy: overwrite
     globalStrategy: merge-json
+  - src: shared/invoke-hook.cjs
+    dest: .claude/hooks/invoke-hook.cjs
+    strategy: overwrite
   - src: claude/claude.json
     dest: .claude.json
     strategy: merge-json

package/src/presets/manifests/gemini.yml

@@ -1,5 +1,14 @@
 target: gemini
 entries:
+  - src: gemini/GEMINI.md
+    dest: GEMINI.md
+    strategy: merge-managed
+    globalStrategy: merge-managed
+    template: true
+  - src: gemini/settings.json
+    dest: .gemini/settings.json
+    strategy: overwrite
+    globalStrategy: merge-json
   - src: opencode/agents
     dest: .gemini/agents
     strategy: overwrite
@@ -8,3 +17,9 @@ entries:
     dest: .gemini/prompts/v1.0.0
     strategy: overwrite
     template: true
+  - src: gemini/commands
+    dest: .gemini/commands
+    strategy: overwrite
+  - src: opencode/skills
+    dest: .gemini/skills
+    strategy: overwrite

package/src/presets/manifests/pi.yml

@@ -0,0 +1,25 @@
+target: pi
+entries:
+  - src: pi/AGENTS.md
+    dest: AGENTS.md
+    strategy: merge-managed
+    globalStrategy: merge-managed
+    template: true
+  - src: pi/settings.json
+    dest: .pi/settings.json
+    strategy: overwrite
+    globalStrategy: merge-json
+  - src: opencode/commands
+    dest: .pi/prompts
+    strategy: overwrite
+  - src: opencode/skills
+    dest: .agents/skills
+    strategy: overwrite
+  - src: opencode/agents
+    dest: .agents/agents
+    strategy: overwrite
+    template: true
+  - src: opencode/prompts/v1.0.0
+    dest: .agents/prompts/v1.0.0
+    strategy: overwrite
+    template: true