@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/scripts/lincoln_harness_adapter.py

@@ -0,0 +1,319 @@
+#!/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.
+
+Usage:
+    python3 scripts/lincoln_harness_adapter.py --harness opencode
+    python3 scripts/lincoln_harness_adapter.py --harness codex --check
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+GENERATED_NOTE = "自动生成,请勿手改"
+GENERATOR = "scripts/lincoln_harness_adapter.py"
+
+GATE_CLAUSE = """## 门控约束(Lincoln lightweight gate)
+
+阶段推进前必须运行准入/准出校验:
+
+```
+python3 scripts/stage_loader.py --stage <current_stage> --action validate-entry
+python3 scripts/stage_loader.py --stage <current_stage> --action validate-exit
+```
+
+human_gate 阶段必须获得人类 PM 显式确认后才可推进,不得跳过。"""
+
+FRONTMATTER_WHITELIST = ("description", "mode", "model", "permission", "tools")
+
+
+class HarnessAdapterError(Exception):
+    """Raised when a harness manifest is missing or invalid."""
+
+
+def load_manifest(root: Path, name: str) -> dict[str, Any]:
+    path = root / ".claude" / "harnesses" / f"{name}.yaml"
+    if not path.exists():
+        raise HarnessAdapterError(f"Harness manifest not found: {path}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise HarnessAdapterError(f"Invalid manifest (not a mapping): {path}")
+    if "command_map" not in data and "command_map_source" in data:
+        source_path = path.parent / data["command_map_source"]
+        if not source_path.exists():
+            raise HarnessAdapterError(f"command_map_source not found: {source_path}")
+        shared = yaml.safe_load(source_path.read_text(encoding="utf-8")) or {}
+        commands = shared.get("commands")
+        if not isinstance(commands, dict):
+            raise HarnessAdapterError(f"command_map_source missing 'commands': {source_path}")
+        data["command_map"] = commands
+    errors = validate_manifest(data)
+    if errors:
+        raise HarnessAdapterError(f"Invalid manifest {path}: {'; '.join(errors)}")
+    return data
+
+
+def validate_manifest(manifest: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if not manifest.get("name"):
+        errors.append("missing field: name")
+    capabilities = manifest.get("capabilities")
+    if not isinstance(capabilities, dict):
+        errors.append("missing field: capabilities")
+    else:
+        for key in ("hooks", "skills", "agents", "commands"):
+            if not isinstance(capabilities.get(key), bool):
+                errors.append(f"capabilities.{key} must be an explicit boolean")
+    if not isinstance(manifest.get("targets"), list):
+        errors.append("missing field: targets")
+    command_map = manifest.get("command_map")
+    if not isinstance(command_map, dict) or not command_map:
+        errors.append("missing field: command_map")
+    else:
+        for key in command_map:
+            if not key.startswith("lc-"):
+                errors.append(f"command_map key must start with 'lc-': {key}")
+    return errors
+
+
+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:
+    rendered = template.format(
+        project=str(project_dir), home=str(home_dir), name=name
+    )
+    return Path(rendered)
+
+
+def _split_frontmatter(text: str) -> tuple[dict[str, Any], str]:
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+    try:
+        front = yaml.safe_load(parts[1]) or {}
+    except yaml.YAMLError:
+        front = {}
+    if not isinstance(front, dict):
+        front = {}
+    return front, parts[2].lstrip("\n")
+
+
+def _transform_frontmatter(
+    text: str, harness: str, source: str, fields: tuple[str, ...] = FRONTMATTER_WHITELIST
+) -> str:
+    front, body = _split_frontmatter(text)
+    kept = {k: v for k, v in front.items() if k in fields}
+    if "mode" not in kept:
+        kept["mode"] = "subagent"
+    yaml_front = yaml.safe_dump(kept, allow_unicode=True, sort_keys=False).strip()
+    return f"---\n{yaml_front}\n---\n\n{_header(harness, source)}\n\n{body}"
+
+
+def _transform_copy(text: str, harness: str, source: str) -> str:
+    return f"{_header(harness, source)}\n\n{text}"
+
+
+# Metadata fields kept when deriving a codex/opencode plugin manifest.
+_PLUGIN_METADATA_KEYS = (
+    "name",
+    "version",
+    "description",
+    "author",
+    "repository",
+    "homepage",
+    "license",
+    "keywords",
+)
+
+
+def _transform_plugin_json(text: str, harness: str, source: str) -> str:
+    """Derive a plugin.json manifest with explicit empty capability declarations.
+
+    Lesson from superpowers (obra/superpowers@7d8d3d4): Codex falls back to
+    hooks/hooks.json when the manifest omits the `hooks` field. We therefore
+    keep only neutral metadata, drop harness-incompatible blocks, and emit
+    `"hooks": {}` explicitly rather than omitting the field.
+    """
+    try:
+        original = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise HarnessAdapterError(f"Invalid plugin JSON ({source}): {exc}") from exc
+    if not isinstance(original, dict):
+        raise HarnessAdapterError(f"Plugin JSON must be an object: {source}")
+
+    manifest = {k: original[k] for k in _PLUGIN_METADATA_KEYS if k in original}
+    # Explicitly disable hooks so the harness does not fall back to defaults.
+    manifest["hooks"] = {}
+    return json.dumps(manifest, indent=2, ensure_ascii=False) + "\n"
+
+
+def _transform_concat(
+    texts: list[tuple[str, str]], harness: str, sources: str, manifest: dict[str, Any]
+) -> str:
+    parts = [_header(harness, sources), ""]
+    for title, text in texts:
+        parts.append(f"## {title}\n\n{text.strip()}\n")
+    command_map = manifest.get("command_map", {})
+    if command_map:
+        parts.append("## 命令(lc-*)\n")
+        for cmd_name, cmd in command_map.items():
+            description = cmd.get("description", cmd_name)
+            action = cmd.get("action", "")
+            args_hint = cmd.get("args_hint", "")
+            parts.append(f"- `{cmd_name}` — {description}。执行: `{action}` {args_hint}".rstrip())
+        parts.append(f"\n{GATE_CLAUSE}\n")
+    return "\n".join(parts)
+
+
+def _transform_command_template(cmd_name: str, cmd: dict[str, Any], harness: str) -> str:
+    description = cmd.get("description", cmd_name)
+    action = cmd.get("action", "")
+    args_hint = cmd.get("args_hint", "")
+    body = (
+        f"---\ndescription: {description}\n---\n\n"
+        f"{_header(harness, 'command_map')}\n\n"
+        f"执行: `{action}` {args_hint}\n\n"
+        f"{GATE_CLAUSE}\n\n"
+        "用户输入: $ARGUMENTS\n"
+    )
+    return body
+
+
+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."""
+    kind = target.get("kind")
+    transform = target.get("transform", "copy")
+    source = target.get("source", "")
+    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"))
+        return items
+
+    sources = sorted(root.glob(source))
+    if not sources:
+        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)]
+
+    items = []
+    for path in sources:
+        text = path.read_text(encoding="utf-8")
+        if transform == "frontmatter":
+            fields = tuple(target.get("fields", FRONTMATTER_WHITELIST))
+            content = _transform_frontmatter(
+                text, harness, str(path.relative_to(root)), fields
+            )
+        elif transform == "plugin-json":
+            content = _transform_plugin_json(
+                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))))
+    return items
+
+
+def generate(
+    root: Path, harness: str, project_dir: Path, home_dir: Path
+) -> list[Path]:
+    """Generate all artifacts for a harness. Returns written paths."""
+    manifest = load_manifest(root, harness)
+    written: list[Path] = []
+    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)
+            staging.append((out_path, content))
+
+    # Write via temp files then move (atomic per file).
+    for out_path, content in staging:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = out_path.with_suffix(out_path.suffix + ".tmp")
+        tmp.write_text(content, encoding="utf-8")
+        tmp.replace(out_path)
+        written.append(out_path)
+    return written
+
+
+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."""
+    diffs: list[str] = []
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_project = Path(tmp) / "project"
+        tmp_home = Path(tmp) / "home"
+        tmp_project.mkdir()
+        tmp_home.mkdir()
+        staged = generate(root, harness, tmp_project, tmp_home)
+        for temp_path in staged:
+            if str(temp_path).startswith(str(tmp_project)):
+                real_path = project_dir / temp_path.relative_to(tmp_project)
+            else:
+                real_path = home_dir / temp_path.relative_to(tmp_home)
+            if not real_path.exists():
+                diffs.append(f"missing: {real_path}")
+            elif real_path.read_text(encoding="utf-8") != temp_path.read_text(encoding="utf-8"):
+                diffs.append(f"modified: {real_path}")
+    return diffs
+
+
+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)")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--project-dir", type=Path, default=Path.cwd())
+    parser.add_argument("--home-dir", type=Path, default=Path.home())
+    parser.add_argument("--check", action="store_true", help="Drift check only; no writes")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.check:
+            diffs = check_drift(args.root, args.harness, args.project_dir, args.home_dir)
+            if diffs:
+                print(f"Drift detected for harness '{args.harness}':")
+                for d in diffs:
+                    print(f"  - {d}")
+                print(
+                    "Run: python3 scripts/lincoln_harness_adapter.py "
+                    f"--harness {args.harness}"
+                )
+                return 1
+            print(f"No drift for harness '{args.harness}'.")
+            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:
+            print(f"  - {path}")
+        return 0
+    except HarnessAdapterError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_index.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Maintain the per-package HTML portal index.
+
+Generates {process_slug}/assets/js/package-data.js from workflow-stage.yaml and a
+scan of {process_slug}/pages/**/*.html. The portal's index.html loads this file
+and renders navigation, status, and annotations.
+
+Replaces the older documents.yaml index; machine state stays in
+workflow-stage.yaml, while package-data.js is a generated projection for humans.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from scripts.lincoln_paths import STATE_FILENAME, is_process_state_path
+
+PACKAGE_DATA_FILENAME = "assets/js/package-data.js"
+VERSION_COMMENT_RE = re.compile(r"<!--\s*version:\s*(v\d+\.\d+)\s*-->", re.IGNORECASE)
+STATUS_COMMENT_RE = re.compile(r"<!--\s*status:\s*(\w+)\s*-->", re.IGNORECASE)
+LIST_META_KEYS = ("doc-fields", "doc-stories", "doc-rules", "doc-boundaries", "doc-exceptions", "doc-refs")
+LIST_SEPARATOR = "|"
+
+
+class MetaParser(HTMLParser):
+    """Collect <meta name="..." content="..."> tags and the <title>."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.meta: dict[str, str] = {}
+        self.title: str = ""
+        self._in_title = False
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag == "meta":
+            attr_dict = {k: v or "" for k, v in attrs}
+            name = attr_dict.get("name", "").strip()
+            content = attr_dict.get("content", "").strip()
+            if name:
+                self.meta[name] = content
+        if tag == "title":
+            self._in_title = True
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag == "title":
+            self._in_title = False
+
+    def handle_data(self, data: str) -> None:
+        if self._in_title:
+            self.title += data
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def package_relative(path: str, process_slug: str) -> str:
+    """Strip the '<process_slug>/' prefix from a repo-relative artifact path."""
+    prefix = f"{process_slug}/"
+    return path[len(prefix) :] if path.startswith(prefix) else path
+
+
+def split_list_meta(value: str) -> list[str]:
+    """Split a pipe-separated meta value into a list of trimmed non-empty items."""
+    if not value:
+        return []
+    return [item.strip() for item in value.split(LIST_SEPARATOR) if item.strip()]
+
+
+def extract_html_meta(full_path: Path) -> dict[str, Any]:
+    """Parse meta tags and version/status comments from an HTML page."""
+    if not full_path.exists():
+        return {}
+    text = full_path.read_text(encoding="utf-8")
+    parser = MetaParser()
+    try:
+        parser.feed(text)
+    except Exception:
+        pass
+
+    version_match = VERSION_COMMENT_RE.search(text)
+    status_match = STATUS_COMMENT_RE.search(text)
+    meta = {
+        "title": parser.meta.get("doc-title") or parser.title or full_path.stem,
+        "nav_label": parser.meta.get("nav-label", ""),
+        "nav_group": parser.meta.get("nav-group", "Docs"),
+        "version": parser.meta.get("doc-version") or (version_match.group(1) if version_match else None),
+        "status": status_match.group(1) if status_match else "",
+        "uid": parser.meta.get("doc-uid") or parser.meta.get("page-uid", ""),
+        "purpose": parser.meta.get("doc-purpose", ""),
+        "layout": parser.meta.get("doc-layout", ""),
+    }
+    for key in LIST_META_KEYS:
+        field = key.replace("doc-", "")
+        meta[field] = split_list_meta(parser.meta.get(key, ""))
+    return meta
+
+
+def extract_html_markdown(full_path: Path) -> str:
+    """Return the embedded Markdown source from a Lincoln doc HTML page.
+
+    If the page does not contain a `<script id="docSource" type="text/markdown">`
+    block, fall back to the raw file text so that legacy or migrated pages still
+    pass content-based validators.
+    """
+    if not full_path.exists():
+        return ""
+    text = full_path.read_text(encoding="utf-8")
+    match = re.search(
+        r'<script(?=\s)([^>]*?\s(?:id="docSource"|type="text/markdown")[^>]*?)>(.*?)</script>',
+        text,
+        re.DOTALL | re.IGNORECASE,
+    )
+    if match:
+        source = match.group(2)
+        return source.strip()
+    return text.strip()
+
+
+def scan_pages(project_root: Path, process_slug: str) -> dict[str, dict[str, Any]]:
+    """Return a dict keyed by page path with metadata from each HTML page."""
+    pages_dir = project_root / process_slug / "pages"
+    found: dict[str, dict[str, Any]] = {}
+    if not pages_dir.is_dir():
+        return found
+    for path in sorted(pages_dir.rglob("*.html")):
+        rel = path.relative_to(project_root / process_slug).as_posix()
+        found[rel] = extract_html_meta(path)
+    return found
+
+
+def build_package_data(
+    state: dict[str, Any],
+    process_slug: str,
+    generated_at: str | None = None,
+    project_root: Path | None = None,
+) -> dict[str, Any]:
+    """Build the portal data object from state and scanned HTML pages."""
+    root = project_root or Path(__file__).resolve().parents[1]
+    current_run = state.get("current_run", {})
+
+    # Start with scanned pages; merge state node metadata over them.
+    page_data = scan_pages(root, process_slug)
+
+    for node in state.get("nodes") or []:
+        stage_id = str(node.get("stage_id") or "")
+        status = str(node.get("status") or "")
+        gate_passed = bool(node.get("gate_passed"))
+        approver = node.get("approved_by")
+        human_confirmed = bool(approver and str(approver).startswith("human"))
+
+        for artifact in node.get("artifacts") or []:
+            rel = package_relative(str(artifact), process_slug)
+            if not rel.endswith(".html"):
+                continue
+            entry = page_data.setdefault(rel, {})
+            entry.setdefault("path", rel)
+            entry.setdefault("title", entry.get("title", Path(rel).stem))
+            entry.setdefault("label", entry.get("title", Path(rel).stem))
+            entry.setdefault("group", entry.get("nav_group", "Docs"))
+            entry["stage"] = stage_id or entry.get("stage", "")
+            entry["status"] = status or entry.get("status", "")
+            entry["gate_passed"] = gate_passed or entry.get("gate_passed", False)
+            entry["human_confirmed"] = human_confirmed or entry.get("human_confirmed", False)
+
+    # Build nav groups preserving scan order.
+    groups: dict[str, list[dict[str, Any]]] = {}
+    for rel in sorted(page_data):
+        entry = page_data[rel]
+        group_name = entry.get("group") or entry.get("nav_group") or "Docs"
+        groups.setdefault(group_name, []).append(
+            {
+                "path": rel,
+                "label": entry.get("nav_label") or entry.get("label") or entry.get("title") or Path(rel).stem,
+                "title": entry.get("title") or Path(rel).stem,
+                "version": entry.get("version"),
+                "status": entry.get("status", ""),
+                "stage": entry.get("stage", ""),
+                "gate_passed": entry.get("gate_passed", False),
+                "human_confirmed": entry.get("human_confirmed", False),
+                "purpose": entry.get("purpose", ""),
+                "layout": entry.get("layout", ""),
+                "stories": entry.get("stories", []),
+                "fields": entry.get("fields", []),
+                "rules": entry.get("rules", []),
+                "boundaries": entry.get("boundaries", []),
+                "exceptions": entry.get("exceptions", []),
+                "refs": entry.get("refs", []),
+                "uid": entry.get("uid", ""),
+            }
+        )
+
+    nav = [{"group": g, "items": items} for g, items in groups.items()]
+
+    return {
+        "process_slug": process_slug,
+        "issue_number": str(current_run.get("issue_number") or ""),
+        "current_stage": str(current_run.get("current_stage") or ""),
+        "status": str(current_run.get("status") or ""),
+        "generated_at": generated_at or now_iso(),
+        "nav": nav,
+    }
+
+
+def write_package_index(
+    state: dict[str, Any],
+    state_path: Path,
+    generated_at: str | None = None,
+) -> Path | None:
+    """Regenerate package-data.js next to a team package state file."""
+    if not is_process_state_path(state_path):
+        return None
+    project_root = state_path.parents[1]
+    process_slug = state_path.parent.name
+    data = build_package_data(state, process_slug, generated_at, project_root)
+
+    package_data_dir = state_path.parent / "assets" / "js"
+    package_data_dir.mkdir(parents=True, exist_ok=True)
+    index_path = package_data_dir / "package-data.js"
+
+    js = "window.LINC_PACKAGE = " + json.dumps(data, ensure_ascii=False, indent=2) + ";\n"
+    index_path.write_text(js, encoding="utf-8")
+    return index_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Regenerate the issue-package HTML portal index")
+    parser.add_argument("--state-file", required=True, help="Path to the package workflow-stage.yaml")
+    args = parser.parse_args()
+
+    state_path = Path(args.state_file).resolve()
+    if not state_path.is_file():
+        print(f"ERROR: state file not found: {state_path}", file=sys.stderr)
+        return 1
+    state = yaml.safe_load(state_path.read_text(encoding="utf-8"))
+    index_path = write_package_index(state, state_path)
+    if index_path is None:
+        print(f"SKIP: {state_path} is not a team issue-package state file")
+        return 0
+    print(f"Updated {index_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())