@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/requirements.txt

@@ -0,0 +1,4 @@
+# Lincoln runtime dependencies for scripts/
+pyyaml>=6.0
+pytest>=7.0
+jsonschema>=4.0

package/framework/scripts/build_codebase_knowledge.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Scan a codebase and emit a machine-readable feature map."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+
+DEFAULT_SOURCE_DIRS = ("products", "src", "lib", "app", "packages", "server", "client")
+IGNORE_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build"}
+SOURCE_EXTENSIONS = {".py", ".ts", ".js", ".tsx", ".go", ".rs"}
+
+
+def find_source_root(root: Path) -> Path | None:
+    for candidate in DEFAULT_SOURCE_DIRS:
+        path = root / candidate
+        if path.is_dir():
+            return path
+    if any(
+        p.suffix in SOURCE_EXTENSIONS for p in root.iterdir() if p.is_file()
+    ):
+        return root
+    return None
+
+
+def scan_features(root: Path, max_features: int = 10) -> dict[str, Any]:
+    root = root.resolve()
+    source_root = find_source_root(root)
+    features: list[dict[str, Any]] = []
+
+    if source_root:
+        for child in sorted(source_root.iterdir()):
+            if not child.is_dir() or child.name in IGNORE_DIRS:
+                continue
+            scan_root = child
+            if source_root.name == "products":
+                nested_source = find_source_root(child)
+                if nested_source:
+                    scan_root = nested_source
+            entry_points = sorted(
+                p.relative_to(root)
+                for p in scan_root.rglob("*")
+                if p.is_file() and p.suffix in SOURCE_EXTENSIONS
+            )[:5]
+            features.append(
+                {
+                    "name": child.name,
+                    "path": str(child.relative_to(root)),
+                    "entry_points": [str(ep) for ep in entry_points],
+                    "has_tests": (root / "tests" / child.name).exists(),
+                }
+            )
+            if len(features) >= max_features:
+                break
+
+    return {
+        "root": str(root),
+        "source_root": str(source_root) if source_root else None,
+        "features": features,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Build a feature map from an existing codebase.")
+    parser.add_argument("--root", default=".", help="Project root")
+    parser.add_argument("--max-features", type=int, default=10, help="Maximum features to emit")
+    args = parser.parse_args()
+    result = scan_features(Path(args.root), max_features=args.max_features)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/framework/scripts/bump_version.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""版本锁步工具(#68:借鉴 superpowers 的 plugin/marketplace 版本漂移教训)。
+
+`.version-bump.json` 是版本号唯一事实源,用 RFC 6901 JSON Pointer 列出所有
+携带版本号的 manifest 位置。用法:
+
+    python3 scripts/bump_version.py bump 1.3.0     # 锁步更新事实源与所有 manifest
+    python3 scripts/bump_version.py --check        # CI:验证所有 manifest 与事实源一致
+    python3 scripts/bump_version.py --audit 1.2.0  # 发布前:列出残留的旧版本引用
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
+
+# audit 模式中合理保留旧版本号的位置(历史记录,不是漂移);
+# package-lock 内依赖自身版本号易误报,其产品版本由 bump 按 pointer 精确维护
+AUDIT_EXCLUDES = (
+    ":!RELEASE.md",
+    ":!knowledge",
+    ":!issue-*",
+    ":!.context",
+    ":!tools/lincoln/package-lock.json",
+)
+
+
+def load_source(root: Path) -> dict:
+    source = root / ".version-bump.json"
+    if not source.exists():
+        sys.exit("missing version source: .version-bump.json")
+    data = json.loads(source.read_text(encoding="utf-8"))
+    if not SEMVER.match(data.get("version", "")):
+        sys.exit(f".version-bump.json has invalid version: {data.get('version')!r}")
+    return data
+
+
+def parse_pointer(pointer: str) -> list[str]:
+    if not pointer.startswith("/"):
+        raise ValueError(f"pointer must start with '/': {pointer!r}")
+    return [t.replace("~1", "/").replace("~0", "~") for t in pointer.split("/")[1:]]
+
+
+def resolve(container, tokens: list[str]):
+    """沿 pointer tokens 走到末段的父容器,返回 (父容器, 末段 key)。"""
+    node = container
+    for token in tokens[:-1]:
+        node = node[int(token)] if isinstance(node, list) else node[token]
+    last = tokens[-1]
+    return node, int(last) if isinstance(node, list) else last
+
+
+def iter_versions(data: dict, root: Path):
+    """yield (manifest_path, pointer, current_value);manifest 缺失即失败。"""
+    for manifest in data["manifests"]:
+        path = root / manifest["path"]
+        if not path.exists():
+            sys.exit(f"manifest listed in .version-bump.json is missing: {manifest['path']}")
+        doc = json.loads(path.read_text(encoding="utf-8"))
+        for pointer in manifest["pointers"]:
+            parent, key = resolve(doc, parse_pointer(pointer))
+            yield manifest["path"], pointer, parent[key]
+
+
+def cmd_check(data: dict, root: Path) -> int:
+    expected = data["version"]
+    drift = [
+        f"  {path}{pointer}: {value!r} != {expected!r}"
+        for path, pointer, value in iter_versions(data, root)
+        if value != expected
+    ]
+    if drift:
+        print("version drift detected:", file=sys.stderr)
+        print("\n".join(drift), file=sys.stderr)
+        print(f"fix: python3 scripts/bump_version.py bump {expected}", file=sys.stderr)
+        return 1
+    print(f"version lockstep OK: {expected} ({len(data['manifests'])} manifests)")
+    return 0
+
+
+def cmd_bump(data: dict, root: Path, new_version: str, dry_run: bool = False) -> int:
+    if not SEMVER.match(new_version):
+        sys.exit(f"invalid semver (want X.Y.Z): {new_version!r}")
+    old_version = data["version"]
+    for manifest in data["manifests"]:
+        path = root / manifest["path"]
+        doc = json.loads(path.read_text(encoding="utf-8"))
+        for pointer in manifest["pointers"]:
+            parent, key = resolve(doc, parse_pointer(pointer))
+            parent[key] = new_version
+        if dry_run:
+            print(f"  would bump {manifest['path']}")
+        else:
+            path.write_text(
+                json.dumps(doc, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+            )
+            print(f"  bumped {manifest['path']}")
+    data["version"] = new_version
+    if dry_run:
+        print(f"would bump .version-bump.json {old_version} -> {new_version}")
+    else:
+        (root / ".version-bump.json").write_text(
+            json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        print(f"bumped {old_version} -> {new_version}")
+
+    # Keep harness artifacts in lockstep with the bumped version.
+    adapter = root / "scripts" / "lincoln_harness_adapter.py"
+    if adapter.exists():
+        for harness in ("codex", "opencode"):
+            artifact = root / ".claude" / "harnesses" / f"{harness}.yaml"
+            if not artifact.exists():
+                continue
+            if dry_run:
+                print(f"  would regenerate harness {harness}.yaml")
+                continue
+            result = subprocess.run(
+                [sys.executable, str(adapter), "--harness", harness],
+                cwd=root,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                print(result.stderr, file=sys.stderr)
+                sys.exit(f"harness generation failed for {harness}")
+            print(f"  regenerated harness {harness}.yaml")
+
+    if dry_run:
+        print(f"next (dry run complete): review changes, then run bump {new_version}")
+    else:
+        print(f"next: python3 scripts/bump_version.py --audit {old_version}")
+    return 0
+
+
+def cmd_audit(root: Path, old_version: str) -> int:
+    if not SEMVER.match(old_version):
+        sys.exit(f"invalid semver (want X.Y.Z): {old_version!r}")
+    result = subprocess.run(
+        ["git", "grep", "-n", "-F", old_version, "--", ".", *AUDIT_EXCLUDES],
+        cwd=root,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode not in (0, 1):
+        sys.exit(f"git grep failed: {result.stderr.strip()}")
+    if result.returncode == 1:
+        print(f"audit OK: no stale {old_version} references")
+        return 0
+    print(f"stale {old_version} references (review each; RELEASE.md/knowledge 等历史记录已排除):")
+    print(result.stdout, end="")
+    return 1
+
+
+def main(argv: list[str], root: Path = ROOT) -> int:
+    raw_args = argv[1:]
+    dry_run = "--dry-run" in raw_args
+    args = [a for a in raw_args if a != "--dry-run"]
+
+    if dry_run and not (len(args) == 2 and args[0] == "bump"):
+        print("--dry-run can only be used with 'bump X.Y.Z'", file=sys.stderr)
+        print(__doc__, file=sys.stderr)
+        return 2
+
+    if args == ["--check"]:
+        return cmd_check(load_source(root), root)
+    if len(args) == 2 and args[0] == "bump":
+        return cmd_bump(load_source(root), root, args[1], dry_run=dry_run)
+    if len(args) == 2 and args[0] == "--audit":
+        return cmd_audit(root, args[1])
+    print(__doc__, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/framework/scripts/check-dependency-drift.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Check upstream drift for pinned external skill dependencies (#62).
+
+Compares each git-sourced skill/plugin's pinned `ref` in
+`.claude/skills/dependencies.yaml` against the current upstream branch head
+(`pinned_from`, default `main`). Prints a report; exits 1 when any dependency
+has drifted (i.e. an upgrade review is due), 0 when all pins are current.
+
+This tool needs network access and is run manually (or from scheduled jobs),
+never from the offline test suite.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+DEPENDENCIES = ROOT / ".claude" / "skills" / "dependencies.yaml"
+GIT_SOURCE_PREFIXES = ("http://", "https://", "git@")
+
+
+def upstream_head(source: str, branch: str) -> str | None:
+    proc = subprocess.run(
+        ["git", "ls-remote", source, branch],
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    return proc.stdout.split()[0]
+
+
+def main() -> int:
+    data = yaml.safe_load(DEPENDENCIES.read_text(encoding="utf-8"))
+    drifted = False
+    for name, dep in data.get("skills", {}).items():
+        if dep.get("type") not in ("skill", "plugin"):
+            continue
+        source = str(dep.get("source", ""))
+        if not source.startswith(GIT_SOURCE_PREFIXES):
+            continue
+        ref = str(dep.get("ref", ""))
+        branch = str(dep.get("pinned_from", "main"))
+        try:
+            head = upstream_head(source, branch)
+        except (subprocess.TimeoutExpired, OSError) as exc:
+            print(f"WARN  {name}: upstream check failed ({exc}); skipped")
+            continue
+        if head is None:
+            print(f"WARN  {name}: cannot resolve {branch} at {source}; skipped")
+            continue
+        if head == ref:
+            print(f"OK    {name}: pinned at {ref[:12]} (current {branch})")
+        else:
+            drifted = True
+            print(
+                f"DRIFT {name}: pinned {ref[:12]}, upstream {branch} is {head[:12]}"
+                " — review upstream changes, run the benchmark, then update the pin"
+            )
+    return 1 if drifted else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/check-harness-drift.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Harness drift check (CI-friendly, lightweight):
+# 1. Regenerate codex/opencode artifacts into a temp dir — proves manifests
+#    load and generation succeeds (catches broken sources / bad manifests).
+# 2. If generated artifacts already exist in the project (someone ran
+#    generate-harness locally), verify they have not drifted from .claude/.
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+if [ -d "$ROOT/.venv" ] && [ -x "$ROOT/.venv/bin/python3" ]; then
+    PYTHON="$ROOT/.venv/bin/python3"
+else
+    PYTHON="python3"
+fi
+
+FAIL=0
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/project" "$TMP/home"
+
+for HARNESS in codex opencode; do
+    echo "==> Harness smoke generation: $HARNESS"
+    if ! "$PYTHON" scripts/lincoln_harness_adapter.py \
+        --harness "$HARNESS" --root "$ROOT" \
+        --project-dir "$TMP/project" --home-dir "$TMP/home" > /dev/null; then
+        echo "❌ generation failed for harness: $HARNESS"
+        FAIL=1
+        continue
+    fi
+
+    # Drift comparison only when artifacts were generated into the project.
+    case "$HARNESS" in
+        opencode) MARKER="$ROOT/.opencode" ;;
+        codex)
+            if [ -e "$ROOT/.codex-plugin" ]; then
+                MARKER="$ROOT/.codex-plugin"
+            else
+                MARKER="$ROOT/AGENTS.md"
+            fi
+            ;;
+    esac
+    if [ -e "$MARKER" ]; then
+        echo "==> Drift check: $HARNESS (project artifacts present)"
+        if ! "$PYTHON" scripts/lincoln_harness_adapter.py \
+            --harness "$HARNESS" --root "$ROOT" \
+            --project-dir "$ROOT" --home-dir "$HOME" --check; then
+            FAIL=1
+        fi
+    fi
+done
+
+if [ "$FAIL" -eq 0 ]; then
+    echo "✅ harness drift check passed"
+fi
+exit "$FAIL"

package/framework/scripts/check-main-merge-hygiene.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Reject branch-only Lincoln process artifacts from main-bound PRs."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from scripts.lincoln_paths import RESERVED_PROCESS_DIRS, STATE_FILENAME
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+ROOT_PROCESS_DIRS = {
+    "designs",
+    "interviews",
+    "recordings",
+    "requirements",
+}
+
+PROCESS_SUBPATHS = {
+    "designs",
+    "docs/research",
+    "handoffs",
+    "interviews",
+    "openspec/changes",
+    "recordings",
+    "requirements",
+}
+
+ALLOWED_ROOT_PREFIXES = (
+    ".claude/",
+    ".claude-plugin/",
+    ".conductor/",
+    ".github/",
+    "CLAUDE.md",
+    "LICENSE",
+    "README.md",
+    "RELEASE.md",
+    "knowledge/",
+    "oss/README.md",
+    "oss/projects.yaml",
+    "products/",
+    "requirements.txt",
+    "scripts/",
+    "tests/",
+    "tools/",
+)
+
+
+def changed_paths(base: str) -> list[str]:
+    result = subprocess.run(
+        ["git", "diff", "--name-only", f"{base}...HEAD"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return []
+    return [line.strip() for line in result.stdout.splitlines() if line.strip()]
+
+
+def is_process_package_dir(top_dir: str) -> bool:
+    """A directory is a Lincoln process package if it contains workflow-stage.yaml."""
+    if top_dir in RESERVED_PROCESS_DIRS or top_dir in ROOT_PROCESS_DIRS:
+        return False
+    return (ROOT / top_dir / STATE_FILENAME).is_file()
+
+
+def is_process_package_path(path: str) -> bool:
+    parts = Path(path).parts
+    if not parts:
+        return False
+    top = parts[0]
+    if top in RESERVED_PROCESS_DIRS or top in ROOT_PROCESS_DIRS:
+        return False
+    # Reject every file inside a process package directory, not only known subpaths.
+    if is_process_package_dir(top):
+        return True
+    if len(parts) == 2 and parts[1] == "workflow-stage.yaml":
+        return True
+    rest = "/".join(parts[1:])
+    return any(rest == sub or rest.startswith(f"{sub}/") for sub in PROCESS_SUBPATHS)
+
+
+def is_root_process_artifact(path: str) -> bool:
+    return any(path.startswith(f"{prefix}/") for prefix in ROOT_PROCESS_DIRS) or path.startswith("openspec/changes/") or path.startswith("docs/research/")
+
+
+def allowed_durable_path(path: str) -> bool:
+    return any(path == prefix.rstrip("/") or path.startswith(prefix) for prefix in ALLOWED_ROOT_PREFIXES)
+
+
+def violations(paths: list[str]) -> list[str]:
+    rejected: list[str] = []
+    for path in paths:
+        if is_process_package_path(path) or is_root_process_artifact(path):
+            rejected.append(path)
+            continue
+        if path.startswith("oss/clones/"):
+            rejected.append(path)
+    return rejected
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check Lincoln main merge hygiene")
+    parser.add_argument("--base", default="origin/main")
+    parser.add_argument("--path", action="append", dest="paths", help="Changed path to check; repeatable")
+    args = parser.parse_args()
+
+    paths = args.paths if args.paths is not None else changed_paths(args.base)
+    bad = violations(paths)
+    if bad:
+        print("FAIL: branch-only Lincoln process artifacts must not merge to main:")
+        for path in bad:
+            print(f"  - {path}")
+        print("Move durable knowledge to knowledge/ and keep process work in the feature branch.")
+        return 1
+
+    print("PASS: no branch-only Lincoln process artifacts detected.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/check-skill-dependencies.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Check Lincoln skill/CLI dependencies.
+# Usage:
+#   scripts/check-skill-dependencies.sh
+#   scripts/check-skill-dependencies.sh --silent
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+PYTHON="${PYTHON:-python3}"
+SILENT=false
+if [[ "${1:-}" == "--silent" ]]; then
+    SILENT=true
+fi
+
+DEP_FILE="$ROOT/.claude/skills/dependencies.yaml"
+LEGACY_DEP_FILE="$ROOT/.claude/skill-dependencies.yaml"
+if [[ ! -f "$DEP_FILE" && -f "$LEGACY_DEP_FILE" ]]; then
+    DEP_FILE="$LEGACY_DEP_FILE"
+fi
+
+if [[ "$SILENT" == false ]]; then
+    echo "==> Validate $(basename "$DEP_FILE")"
+fi
+"$PYTHON" -c "import yaml; yaml.safe_load(open('$DEP_FILE'))"
+
+if [[ "$SILENT" == false ]]; then
+    echo "==> Check declared skills and CLIs"
+fi
+
+"$PYTHON" - "$ROOT" "$DEP_FILE" "$SILENT" <<'PY'
+import sys
+import shutil
+import platform
+from pathlib import Path
+import yaml
+
+root = Path(sys.argv[1])
+dep_file = Path(sys.argv[2])
+silent = sys.argv[3].lower() == "true"
+
+manifest = yaml.safe_load(dep_file.read_text(encoding="utf-8"))
+
+skill_root = Path.home() / ".claude" / "skills"
+errors = []
+warnings = []
+install_commands = []
+
+system = platform.system().lower()
+if system == "darwin":
+    platform_name = "macos"
+elif system == "linux":
+    platform_name = "linux"
+else:
+    platform_name = system
+
+def get_install_command(cfg):
+    if "platforms" in cfg and isinstance(cfg["platforms"], dict):
+        if platform_name in cfg["platforms"]:
+            return cfg["platforms"][platform_name]
+        if "linux" in cfg["platforms"]:
+            return cfg["platforms"]["linux"]
+    return cfg.get("install")
+
+for name, cfg in manifest.get("skills", {}).items():
+    typ = cfg.get("type", "skill")
+    is_required = cfg.get("required", True)
+    source = cfg.get("source", "")
+    if typ == "cli":
+        binary = cfg.get("binary", name)
+        if not shutil.which(binary):
+            msg = f"CLI missing: {binary} (skill: {name})"
+            cmd = get_install_command(cfg)
+            if cmd:
+                install_commands.append(f"# Install {name}: {cmd}")
+            if is_required:
+                errors.append(msg)
+            else:
+                warnings.append(msg)
+    else:
+        path = cfg.get("path")
+        if path:
+            expected = root / path / "SKILL.md"
+        else:
+            expected = skill_root / name / "SKILL.md"
+        if not expected.exists():
+            msg = f"Skill missing: {name} (expected {expected})"
+            if source and source != "inline":
+                ref = cfg.get("ref", "")
+                ref_arg = f" --branch {ref}" if ref else ""
+                install_commands.append(f"# Install {name}: git clone{ref_arg} --single-branch --depth 1 {source} {skill_root / name}")
+            if is_required:
+                errors.append(msg)
+            else:
+                warnings.append(msg)
+
+if warnings and not silent:
+    print("Optional dependencies missing (warnings only):")
+    for w in warnings:
+        print(f"  - {w}")
+
+if errors and not silent:
+    print("Required dependencies missing:")
+    for e in errors:
+        print(f"  - {e}")
+
+if install_commands and not silent:
+    print("")
+    print("Suggested installation commands:")
+    for cmd in install_commands:
+        print(f"  {cmd}")
+
+if errors:
+    sys.exit(1)
+
+if not silent:
+    print("All declared skills/CLIs are present.")
+PY
+
+if [[ "$SILENT" == false ]]; then
+    echo "==> All skill dependencies satisfied"
+fi