@sushanglewis/lincoln 1.6.3 → 1.7.0

package/framework/scripts/lincoln_friction.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""Lincoln friction scorer.
+
+Reads the session trace for the current node, computes a friction score based
+on configured signals, and writes a suggestion/prompt file when thresholds are
+met. Designed to be invoked asynchronously from on-stop.sh.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DEFAULT_POLICY_PATH = ".claude/policies/friction.yaml"
+DEFAULT_TRACE_TAIL_LINES = 500
+
+
+def load_policy(root: Path) -> dict[str, Any]:
+    """Load the friction policy YAML, returning defaults if missing."""
+    path = root / DEFAULT_POLICY_PATH
+    if not path.exists():
+        return _default_policy()
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or _default_policy()
+
+
+def _default_policy() -> dict[str, Any]:
+    return {
+        "schema_version": "1.0.0",
+        "thresholds": {"prompt_user": 5, "auto_suggest": 3},
+        "weights": {
+            "tool_failed": 2,
+            "tool_rejected": 3,
+            "retry_spike": 3,
+            "human_override": 5,
+            "long_session": 1,
+        },
+        "long_session_minutes": 30,
+        "retry_count_threshold": 3,
+    }
+
+
+def _tail_jsonl(trace_file: Path, lines: int) -> list[dict[str, Any]]:
+    if not trace_file.exists():
+        return []
+    try:
+        with open(trace_file, "r", encoding="utf-8") as fh:
+            all_lines = fh.readlines()
+        return [json.loads(line) for line in all_lines[-lines:] if line.strip()]
+    except Exception:
+        return []
+
+
+def _parse_timestamp(ts: str | None) -> datetime | None:
+    if not ts:
+        return None
+    try:
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _compute_long_session_minutes(events: list[dict[str, Any]], threshold_minutes: int) -> float:
+    if len(events) < 2 or threshold_minutes <= 0:
+        return 0.0
+    timestamps = [t for t in (_parse_timestamp(e.get("timestamp")) for e in events) if t]
+    if len(timestamps) < 2:
+        return 0.0
+    duration = (max(timestamps) - min(timestamps)).total_seconds() / 60.0
+    return duration if duration >= threshold_minutes else 0.0
+
+
+def _count_tool_failures(events: list[dict[str, Any]]) -> int:
+    return sum(
+        1
+        for e in events
+        if e.get("category") == "tool" and e.get("exit_code", 0) != 0
+    )
+
+
+def _count_tool_rejected(events: list[dict[str, Any]]) -> int:
+    return sum(
+        1
+        for e in events
+        if e.get("category") == "tool" and e.get("args_summary", {}).get("blocked") is True
+    )
+
+
+def _count_retry_spikes(events: list[dict[str, Any]], threshold: int) -> int:
+    """Count tools that consecutively failed >= threshold times in this window."""
+    if threshold <= 0:
+        return 0
+    counts: dict[str, int] = {}
+    spikes = 0
+    for e in events:
+        if e.get("category") != "tool":
+            continue
+        tool = e.get("tool", "")
+        failed = e.get("exit_code", 0) != 0 or e.get("args_summary", {}).get("blocked") is True
+        if failed:
+            counts[tool] = counts.get(tool, 0) + 1
+            if counts[tool] == threshold:
+                spikes += 1
+        else:
+            counts[tool] = 0
+    return spikes
+
+
+def compute_friction(
+    events: list[dict[str, Any]],
+    policy: dict[str, Any],
+) -> dict[str, Any]:
+    """Compute friction score and signals from a window of trace events."""
+    weights = policy.get("weights", {})
+    retry_threshold = policy.get("retry_count_threshold", 3)
+    long_session_minutes = policy.get("long_session_minutes", 30)
+
+    tool_failed = _count_tool_failures(events)
+    tool_rejected = _count_tool_rejected(events)
+    retry_spike = _count_retry_spikes(events, retry_threshold)
+    long_session = _compute_long_session_minutes(events, long_session_minutes)
+
+    signals: dict[str, Any] = {
+        "tool_failed": {"count": tool_failed, "weight": weights.get("tool_failed", 0)},
+        "tool_rejected": {"count": tool_rejected, "weight": weights.get("tool_rejected", 0)},
+        "retry_spike": {"count": retry_spike, "weight": weights.get("retry_spike", 0)},
+        "human_override": {"count": 0, "weight": weights.get("human_override", 0)},
+        "long_session": {
+            "minutes": round(long_session, 2),
+            "weight": weights.get("long_session", 0),
+        },
+    }
+
+    score = (
+        tool_failed * signals["tool_failed"]["weight"]
+        + tool_rejected * signals["tool_rejected"]["weight"]
+        + retry_spike * signals["retry_spike"]["weight"]
+        + signals["human_override"]["count"] * signals["human_override"]["weight"]
+        + (1 if long_session >= long_session_minutes else 0) * signals["long_session"]["weight"]
+    )
+
+    return {
+        "score": score,
+        "signals": signals,
+        "event_count": len(events),
+    }
+
+
+def resolve_trace_file(state_path: Path | None) -> Path | None:
+    """Resolve the trace file from workflow state or environment override."""
+    env_file = os.environ.get("LINCOLN_TRACE_FILE")
+    if env_file:
+        return Path(env_file)
+
+    if state_path is None:
+        return None
+
+    try:
+        sys.path.insert(0, str(state_path.resolve().parents[1]))
+        from scripts.lincoln_paths import get_process_slug, process_package_root
+        from scripts.lincoln_trace import _load_state
+
+        state = _load_state(state_path)
+        if state is None:
+            return state_path.parent / ".trace" / "lc-trace.jsonl"
+        slug = get_process_slug(state, state_path)
+        root = process_package_root(slug, state, state_path)
+        return root / ".trace" / "lc-trace.jsonl"
+    except Exception:
+        return state_path.parent / ".trace" / "lc-trace.jsonl"
+
+
+def write_friction_report(
+    trace_dir: Path,
+    score: int,
+    signals: dict[str, Any],
+    policy: dict[str, Any],
+) -> Path | None:
+    """Write a friction suggestion or prompt file when thresholds are met."""
+    thresholds = policy.get("thresholds", {})
+    prompt_threshold = thresholds.get("prompt_user", 5)
+    suggest_threshold = thresholds.get("auto_suggest", 3)
+
+    if score >= prompt_threshold:
+        path = trace_dir / "friction-prompt.md"
+        kind = "prompt"
+    elif score >= suggest_threshold:
+        path = trace_dir / "friction-suggestion.md"
+        kind = "suggestion"
+    else:
+        return None
+
+    active_signals = [
+        f"- **{name}**: {info.get('count', info.get('minutes', 0))} (weight {info['weight']})"
+        for name, info in signals.items()
+        if (info.get("count", 0) > 0 or info.get("minutes", 0) > 0)
+    ]
+
+    content = f"""# Friction Report ({kind})
+
+Generated at: {datetime.now(timezone.utc).isoformat()}
+Score: **{score}**
+
+## Detected signals
+
+{chr(10).join(active_signals) if active_signals else "_No strong friction signals detected._"}
+
+## Suggested action
+
+Consider capturing a lesson learned in `knowledge/05-learnings/` or running:
+
+```bash
+python3 scripts/lincoln-knowledge.py suggest --stage <stage_id>
+```
+
+This is a suggestion only; the human PM decides whether to persist anything.
+"""
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def score_friction(
+    root: Path,
+    state_path: Path | None = None,
+    trace_file: Path | None = None,
+    tail_lines: int = DEFAULT_TRACE_TAIL_LINES,
+) -> dict[str, Any]:
+    """Score friction and write a report if thresholds are met."""
+    policy = load_policy(root)
+    target_trace = trace_file or resolve_trace_file(state_path)
+    if target_trace is None:
+        return {"score": 0, "signals": {}, "report": None, "error": "no trace file"}
+
+    events = _tail_jsonl(target_trace, tail_lines)
+    result = compute_friction(events, policy)
+    report = write_friction_report(target_trace.parent, result["score"], result["signals"], policy)
+    result["report"] = str(report) if report else None
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Score session friction from trace events")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--state-file", type=Path, default=None)
+    parser.add_argument("--trace-file", type=Path, default=None)
+    parser.add_argument("--tail-lines", type=int, default=DEFAULT_TRACE_TAIL_LINES)
+    args = parser.parse_args(argv)
+
+    result = score_friction(
+        root=args.root,
+        state_path=args.state_file,
+        trace_file=args.trace_file,
+        tail_lines=args.tail_lines,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_harness_adapter.py

@@ -1,13 +1,15 @@
 #!/usr/bin/env python3
 """Harness adapter generator for Lincoln.
 
-Derives codex/opencode artifacts (AGENTS.md, prompts, agents, commands) from
-the single source of truth in `.claude/`, driven by `.claude/harnesses/<name>.yaml`
-manifests. Idempotent; `--check` regenerates into a temp dir and reports drift.
+Derives codex/opencode artifacts (AGENTS.md, prompts, agents, commands, hooks,
+MCP config) from the single source of truth in `.claude/`, driven by
+`.claude/harnesses/<name>.yaml` manifests. Idempotent; `--check` regenerates
+into a temp dir and reports drift.
 
 Usage:
     python3 scripts/lincoln_harness_adapter.py --harness opencode
     python3 scripts/lincoln_harness_adapter.py --harness codex --check
+    python3 scripts/lincoln_harness_adapter.py --harness claude-code --check
 """
 
 from __future__ import annotations
@@ -37,6 +39,9 @@ human_gate 阶段必须获得人类 PM 显式确认后才可推进,不得跳过
 
 FRONTMATTER_WHITELIST = ("description", "mode", "model", "permission", "tools")
 
+MCP_SOURCE_PATH = Path(".claude") / "mcp" / "mcp.yaml"
+HOOKS_SOURCE_PATH = Path(".claude") / "hooks" / "hooks.yaml"
+
 
 class HarnessAdapterError(Exception):
     """Raised when a harness manifest is missing or invalid."""
@@ -91,9 +96,50 @@ def _header(harness: str, source: str) -> str:
     return f"<!-- {GENERATED_NOTE} (generated by {GENERATOR}; harness: {harness}; source: {source}) -->"
 
 
-def _resolve_output(template: str, name: str, project_dir: Path, home_dir: Path) -> Path:
+def _glob_base(root: Path, pattern: str) -> Path:
+    """Return the concrete base directory of a glob pattern relative to root.
+
+    Examples:
+        .claude/skills/*/SKILL.md  -> root/.claude/skills
+        .claude/rules/**/*.md      -> root/.claude/rules
+        .claude/hooks/*.sh        -> root/.claude/hooks
+    """
+    parts = Path(pattern).parts
+    concrete: list[str] = []
+    for part in parts:
+        if any(c in part for c in "*?["):
+            break
+        concrete.append(part)
+    return root / Path(*concrete)
+
+
+def _resolve_output(
+    template: str,
+    source: Path,
+    root: Path,
+    pattern: str,
+    project_dir: Path,
+    home_dir: Path,
+) -> Path:
+    """Render an output path template using source path metadata."""
+    name = source.stem
+    parent = source.parent.name
+    base = _glob_base(root, pattern)
+    try:
+        rel = source.relative_to(base)
+        relative_path = str(rel.with_suffix(""))
+        relative_full = str(rel)
+    except ValueError:
+        relative_path = name
+        relative_full = source.name
+
     rendered = template.format(
-        project=str(project_dir), home=str(home_dir), name=name
+        project=str(project_dir),
+        home=str(home_dir),
+        name=name,
+        parent=parent,
+        relative_path=relative_path,
+        relative_full=relative_full,
     )
     return Path(rendered)
 
@@ -162,6 +208,46 @@ def _transform_plugin_json(text: str, harness: str, source: str) -> str:
     return json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
 
 
+def _transform_mcp_config(text: str, harness: str, source: str) -> str:
+    """Convert Lincoln's declarative mcp.yaml to a harness-native MCP config.
+
+    The output is a JSON object keyed by `mcpServers`. Harness overrides declared
+    under each server's `harness_overrides` are applied for the target harness.
+    Environment variable placeholders (`${VAR}`) are preserved; the runtime
+    environment or `.env` file is responsible for resolving them.
+    """
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise HarnessAdapterError(f"Invalid MCP config YAML ({source}): {exc}") from exc
+    if not isinstance(data, dict):
+        raise HarnessAdapterError(f"MCP config must be a mapping: {source}")
+
+    servers = data.get("servers", {})
+    if not isinstance(servers, dict):
+        raise HarnessAdapterError(f"MCP config 'servers' must be a mapping: {source}")
+
+    rendered: dict[str, Any] = {}
+    for server_name, server in servers.items():
+        if not isinstance(server, dict):
+            continue
+        overrides = server.get("harness_overrides", {}).get(harness, {})
+        enabled = server.get("enabled", True)
+        if isinstance(overrides.get("enabled"), bool):
+            enabled = overrides["enabled"]
+        if not enabled:
+            continue
+
+        entry: dict[str, Any] = {}
+        for key in ("command", "args", "env", "type", "url", "headers", "description"):
+            if key in server:
+                entry[key] = server[key]
+        entry.update({k: v for k, v in overrides.items() if k != "enabled"})
+        rendered[server_name] = entry
+
+    return json.dumps({"mcpServers": rendered}, indent=2, ensure_ascii=False) + "\n"
+
+
 def _transform_concat(
     texts: list[tuple[str, str]], harness: str, sources: str, manifest: dict[str, Any]
 ) -> str:
@@ -195,32 +281,49 @@ def _transform_command_template(cmd_name: str, cmd: dict[str, Any], harness: str
 
 
 def _expand_target(
-    root: Path, target: dict[str, Any], manifest: dict[str, Any]
-) -> list[tuple[str, str, str]]:
-    """Expand a target into (output_name, content, source_label) tuples."""
+    root: Path,
+    target: dict[str, Any],
+    manifest: dict[str, Any],
+    project_dir: Path,
+    home_dir: Path,
+) -> list[tuple[Path, str, str]]:
+    """Expand a target into (output_path, content, source_label) tuples."""
     kind = target.get("kind")
     transform = target.get("transform", "copy")
     source = target.get("source", "")
+    output_template = target.get("output", "")
     harness = manifest["name"]
 
     if source == "command_map" or kind == "command":
         items = []
         for cmd_name, cmd in manifest.get("command_map", {}).items():
             content = _transform_command_template(cmd_name, cmd, harness)
-            items.append((cmd_name, content, "command_map"))
+            out_path = _resolve_output(
+                output_template,
+                Path(f"{cmd_name}.md"),
+                root,
+                source,
+                project_dir=project_dir,
+                home_dir=home_dir,
+            )
+            items.append((out_path, content, "command_map"))
         return items
 
     sources = sorted(root.glob(source))
     if not sources:
+        if target.get("optional"):
+            return []
         raise HarnessAdapterError(f"Target source matched nothing: {source}")
 
     if transform == "concat":
         texts = [(p.stem, p.read_text(encoding="utf-8")) for p in sources]
-        return [("__concat__", _transform_concat(texts, harness, source, manifest), source)]
+        out_path = _resolve_output(output_template, sources[0], root, source, project_dir, home_dir)
+        return [(out_path, _transform_concat(texts, harness, source, manifest), source)]
 
     items = []
     for path in sources:
         text = path.read_text(encoding="utf-8")
+        out_path = _resolve_output(output_template, path, root, source, project_dir, home_dir)
         if transform == "frontmatter":
             fields = tuple(target.get("fields", FRONTMATTER_WHITELIST))
             content = _transform_frontmatter(
@@ -230,9 +333,13 @@ def _expand_target(
             content = _transform_plugin_json(
                 text, harness, str(path.relative_to(root))
             )
+        elif transform == "mcp-config":
+            content = _transform_mcp_config(
+                text, harness, str(path.relative_to(root))
+            )
         else:
             content = _transform_copy(text, harness, str(path.relative_to(root)))
-        items.append((path.stem, content, str(path.relative_to(root))))
+        items.append((out_path, content, str(path.relative_to(root))))
     return items
 
 
@@ -245,8 +352,9 @@ def generate(
     staging: list[tuple[Path, str]] = []
 
     for target in manifest["targets"]:
-        for name, content, _source in _expand_target(root, target, manifest):
-            out_path = _resolve_output(target["output"], name, project_dir, home_dir)
+        for out_path, content, _source in _expand_target(
+            root, target, manifest, project_dir, home_dir
+        ):
             staging.append((out_path, content))
 
     # Write via temp files then move (atomic per file).
@@ -259,10 +367,55 @@ def generate(
     return written
 
 
+def _check_claude_code_sources(root: Path) -> list[str]:
+    """Validate that .claude/ source files referenced by hooks.yaml exist."""
+    diffs: list[str] = []
+    hooks_yaml = root / HOOKS_SOURCE_PATH
+    if not hooks_yaml.exists():
+        diffs.append(f"missing: {hooks_yaml}")
+        return diffs
+
+    try:
+        hooks_data = yaml.safe_load(hooks_yaml.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as exc:
+        diffs.append(f"invalid YAML: {hooks_yaml}: {exc}")
+        return diffs
+
+    hooks = hooks_data.get("hooks", [])
+    if not isinstance(hooks, list):
+        diffs.append("invalid hooks.yaml: 'hooks' is not a list")
+        return diffs
+
+    for hook in hooks:
+        if not isinstance(hook, dict):
+            continue
+        file_name = hook.get("file")
+        if not file_name:
+            continue
+        hook_file = root / ".claude" / "hooks" / file_name
+        if not hook_file.exists():
+            diffs.append(f"missing hook: {hook_file}")
+        elif not hook_file.stat().st_mode & 0o111:
+            diffs.append(f"not executable: {hook_file}")
+
+    mcp_yaml = root / MCP_SOURCE_PATH
+    if not mcp_yaml.exists():
+        diffs.append(f"missing: {mcp_yaml}")
+
+    risk_policy = root / ".claude" / "policies" / "security.yaml"
+    if not risk_policy.exists():
+        diffs.append(f"missing: {risk_policy}")
+
+    return diffs
+
+
 def check_drift(
     root: Path, harness: str, project_dir: Path, home_dir: Path
 ) -> list[str]:
     """Regenerate into a temp dir and compare with existing artifacts."""
+    if harness == "claude-code":
+        return _check_claude_code_sources(root)
+
     diffs: list[str] = []
     with tempfile.TemporaryDirectory() as tmp:
         tmp_project = Path(tmp) / "project"
@@ -282,6 +435,19 @@ def check_drift(
     return diffs
 
 
+def _load_dotenv(root: Path) -> None:
+    """Load environment variables from project root .env if python-dotenv is available."""
+    env_file = root / ".env"
+    if not env_file.exists():
+        return
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv(dotenv_path=env_file, override=False, verbose=False)
+    except ImportError:
+        pass
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description="Lincoln harness adapter generator")
     parser.add_argument("--harness", required=True, help="Harness name (codex|opencode|claude-code)")
@@ -291,6 +457,8 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--check", action="store_true", help="Drift check only; no writes")
     args = parser.parse_args(argv)
 
+    _load_dotenv(args.root)
+
     try:
         if args.check:
             diffs = check_drift(args.root, args.harness, args.project_dir, args.home_dir)
@@ -305,6 +473,10 @@ def main(argv: list[str] | None = None) -> int:
                 return 1
             print(f"No drift for harness '{args.harness}'.")
             return 0
+        if args.harness == "claude-code":
+            # Claude Code uses .claude/ directly; nothing to generate.
+            print("Harness 'claude-code' uses .claude/ as the source of truth; no artifacts generated.")
+            return 0
         written = generate(args.root, args.harness, args.project_dir, args.home_dir)
         print(f"Generated {len(written)} artifacts for harness '{args.harness}':")
         for path in written: