@sushanglewis/lincoln 1.6.2 → 1.7.0

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:

package/framework/scripts/lincoln_mr_mine.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Lincoln MR / PR knowledge miner.
+
+Extracts decision-related review comments from a merged pull request and writes
+structured decision notes to the issue work package. These notes stay in
+issue-<N>/docs/decisions/ until the sync-knowledge stage promotes them to
+knowledge/.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+DECISION_KEYWORDS = ["decision", "decided", "agreed", "rejected", "note:", "approve", "approved"]
+
+
+def _run_gh(args: list[str]) -> dict[str, Any] | list[Any]:
+    """Call the gh CLI and return parsed JSON."""
+    cmd = ["gh", *args]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "gh CLI failed")
+    return json.loads(result.stdout or "[]")
+
+
+def _extract_decision_snippets(text: str) -> list[str]:
+    """Pull decision-oriented sentences or paragraphs from a comment body."""
+    if not text:
+        return []
+    snippets = []
+    for paragraph in re.split(r"\n\s*\n", text.strip()):
+        paragraph = paragraph.strip()
+        if not paragraph:
+            continue
+        lowered = paragraph.lower()
+        if any(keyword in lowered for keyword in DECISION_KEYWORDS):
+            snippets.append(paragraph)
+    return snippets
+
+
+def _sanitize_filename(text: str) -> str:
+    """Reduce a comment snippet to a safe filename slug."""
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    text = text.strip("-")
+    return text[:60]
+
+
+def mine_pr_decisions(
+    owner: str,
+    repo: str,
+    pr_number: int,
+    issue_number: int | None = None,
+    output_dir: Path | None = None,
+) -> list[Path]:
+    """Mine decision comments from a PR and write them to the issue package."""
+    if output_dir is None:
+        if issue_number is None:
+            raise ValueError("issue_number or output_dir is required")
+        output_dir = Path(f"issue-{issue_number}") / "docs" / "decisions"
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    comments = _run_gh(
+        ["api", f"repos/{owner}/{repo}/pulls/{pr_number}/comments"]
+    )
+    review_comments = _run_gh(
+        ["api", f"repos/{owner}/{repo}/pulls/{pr_number}/reviews"]
+    )
+
+    if isinstance(comments, dict):
+        comments = [comments]
+    if isinstance(review_comments, dict):
+        review_comments = [review_comments]
+
+    all_comments = list(comments) + list(review_comments)
+
+    written: list[Path] = []
+    seen: set[str] = set()
+
+    for comment in all_comments:
+        body = comment.get("body") or ""
+        snippets = _extract_decision_snippets(body)
+        for snippet in snippets:
+            if snippet in seen:
+                continue
+            seen.add(snippet)
+            slug = _sanitize_filename(snippet)
+            filename = f"pr-{pr_number}-{slug}.md"
+            path = output_dir / filename
+            if path.exists():
+                continue
+
+            content = f"""# PR {pr_number} Decision Note
+
+**Source:** {owner}/{repo}#{pr_number}
+**Author:** {comment.get('author', {}).get('login', 'unknown')}
+**Created:** {comment.get('createdAt', 'unknown')}
+**Comment ID:** {comment.get('id', 'unknown')}
+
+## Snippet
+
+{snippet}
+
+## Keywords
+
+{', '.join(DECISION_KEYWORDS)}
+
+---
+*Auto-generated by scripts/lincoln_mr_mine.py*
+"""
+            path.write_text(content, encoding="utf-8")
+            written.append(path)
+
+    return written
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Mine PR review decisions")
+    parser.add_argument("--owner", required=True)
+    parser.add_argument("--repo", required=True)
+    parser.add_argument("--pr", type=int, required=True)
+    parser.add_argument("--issue", type=int, default=None)
+    parser.add_argument("--output-dir", type=Path, default=None)
+    args = parser.parse_args(argv)
+
+    paths = mine_pr_decisions(
+        owner=args.owner,
+        repo=args.repo,
+        pr_number=args.pr,
+        issue_number=args.issue,
+        output_dir=args.output_dir,
+    )
+    for path in paths:
+        print(path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_recall.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Lincoln recall precheck.
+
+Given a task description, scores knowledge base documents by keyword overlap
+(and optionally by embedding similarity) and returns the top-K matches.
+Designed to be called from on-session-start.sh before injecting context.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+DEFAULT_KNOWLEDGE_DIR = "knowledge"
+DEFAULT_TOP_K = 5
+
+
+def _tokenize(text: str) -> set[str]:
+    """Extract lowercase alphanumeric tokens."""
+    return set(re.findall(r"[a-zA-Z0-9一-鿿]+", text.lower()))
+
+
+def _load_documents(knowledge_dir: Path) -> list[dict[str, Any]]:
+    docs: list[dict[str, Any]] = []
+    if not knowledge_dir.exists():
+        return docs
+    for path in sorted(knowledge_dir.rglob("*.md")):
+        try:
+            text = path.read_text(encoding="utf-8")
+            docs.append(
+                {
+                    "path": str(path.relative_to(knowledge_dir)),
+                    "tokens": _tokenize(text),
+                    "title": path.stem,
+                    "_text": text[:2000],
+                }
+            )
+        except Exception:
+            continue
+    return docs
+
+
+def _score_by_keywords(query_tokens: set[str], doc: dict[str, Any]) -> float:
+    if not query_tokens:
+        return 0.0
+    doc_tokens = doc["tokens"]
+    if not doc_tokens:
+        return 0.0
+    overlap = len(query_tokens & doc_tokens)
+    return overlap / max(len(query_tokens), len(doc_tokens))
+
+
+def _try_embedding_score(query: str, docs: list[dict[str, Any]]) -> list[float] | None:
+    """Attempt embedding-based scoring if sentence-transformers is installed."""
+    try:
+        from sentence_transformers import SentenceTransformer, util  # type: ignore
+
+        model = SentenceTransformer("all-MiniLM-L6-v2")
+        query_embedding = model.encode(query, convert_to_tensor=True)
+        doc_texts = [doc.get("_text", "") for doc in docs]
+        doc_embeddings = model.encode(doc_texts, convert_to_tensor=True)
+        scores = util.cos_sim(query_embedding, doc_embeddings)[0].tolist()
+        return list(scores)
+    except Exception:
+        return None
+
+
+def recall(
+    query: str,
+    knowledge_dir: Path | None = None,
+    top_k: int = DEFAULT_TOP_K,
+    use_embedding: bool = True,
+) -> dict[str, Any]:
+    """Return top-K knowledge documents for a query."""
+    knowledge_dir = knowledge_dir or Path(DEFAULT_KNOWLEDGE_DIR)
+    docs = _load_documents(knowledge_dir)
+    query_tokens = _tokenize(query)
+
+    if use_embedding:
+        embedding_scores = _try_embedding_score(query, docs)
+    else:
+        embedding_scores = None
+
+    results = []
+    for idx, doc in enumerate(docs):
+        keyword_score = _score_by_keywords(query_tokens, doc)
+        if embedding_scores is not None:
+            score = 0.5 * keyword_score + 0.5 * embedding_scores[idx]
+        else:
+            score = keyword_score
+        results.append(
+            {
+                "path": doc["path"],
+                "title": doc["title"],
+                "score": round(score, 4),
+                "method": "embedding+keywords" if embedding_scores else "keywords",
+            }
+        )
+
+    results.sort(key=lambda r: r["score"], reverse=True)
+    return {
+        "query": query,
+        "top_k": top_k,
+        "docs": [r for r in results[:top_k] if r["score"] > 0],
+        "method": "embedding+keywords" if embedding_scores else "keywords",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Recall relevant knowledge documents")
+    parser.add_argument("--query", required=True)
+    parser.add_argument("--knowledge-dir", type=Path, default=None)
+    parser.add_argument("--top-k", type=int, default=DEFAULT_TOP_K)
+    parser.add_argument("--format", choices=["json", "markdown"], default="json")
+    parser.add_argument("--no-embedding", action="store_true", default=False)
+    args = parser.parse_args(argv)
+
+    result = recall(
+        query=args.query,
+        knowledge_dir=args.knowledge_dir,
+        top_k=args.top_k,
+        use_embedding=not args.no_embedding,
+    )
+
+    if args.format == "json":
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"# 相关知识（{result['method']}）\n")
+        if result["docs"]:
+            for doc in result["docs"]:
+                print(f"- [{doc['title']}]({doc['path']}) — score {doc['score']}")
+        else:
+            print("_未找到相关知识。_")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())