@sushanglewis/lincoln 1.5.0 → 1.5.2

package/framework/scripts/lincoln_paths.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Shared path helpers for Lincoln process packages."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+LEGACY_STATE_PATH = PROJECT_ROOT / ".claude" / "workflow-state.yaml"
+ROOT_STATE_PATH = PROJECT_ROOT / ".claude" / "workflow-stage.yaml"
+STATE_FILENAME = "workflow-stage.yaml"
+SOLO_STATE_DIR = ".context/workflow"
+SOLO_PROCESS_SLUG = ".context"
+
+RESERVED_PROCESS_DIRS = {
+    ".claude",
+    ".conductor",
+    ".context",
+    ".git",
+    ".github",
+    ".pytest_cache",
+    ".venv",
+    "docs",
+    "knowledge",
+    "node_modules",
+    "oss",
+    "products",
+    "scripts",
+    "tests",
+    "tools",
+    "venv",
+}
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", value.strip()).strip("-").lower()
+    return slug or "lc-process"
+
+
+def validate_slug(value: str) -> str:
+    slug = slugify(value)
+    if not re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", slug):
+        raise ValueError(f"Invalid process slug: {value}")
+    return slug
+
+
+LC_NAME_RE = re.compile(r"[a-z0-9][a-z0-9-]*")
+
+
+def validate_name(value: str, kind: str = "name") -> str:
+    """Validate a Lincoln identifier (workflow, role, skill, scenario key)."""
+    if not LC_NAME_RE.fullmatch(value):
+        raise ValueError(f"Invalid {kind}: {value!r}")
+    return value
+
+
+def assert_contained(path: Path, parent: Path, desc: str = "path") -> Path:
+    """Raise ValueError if resolved path escapes parent directory."""
+    resolved = path.resolve()
+    base = parent.resolve()
+    if base not in resolved.parents and resolved != base:
+        raise ValueError(f"{desc} escapes allowed directory: {path}")
+    return resolved
+
+
+def atomic_write_text(path: Path, content: str, encoding: str = "utf-8") -> None:
+    """Atomically write text to path using a temporary file and rename."""
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    try:
+        tmp.write_text(content, encoding=encoding)
+        tmp.replace(path)
+    except Exception:
+        if tmp.exists():
+            tmp.unlink()
+        raise
+
+
+def branch_slug(project_root: Path = PROJECT_ROOT) -> str:
+    try:
+        branch = subprocess.check_output(
+            ["git", "branch", "--show-current"],
+            cwd=project_root,
+            text=True,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except Exception:
+        branch = ""
+    if branch.startswith("lincoln/"):
+        branch = branch.split("/", 1)[1]
+    return slugify(branch or project_root.name)
+
+
+def default_process_slug(project_root: Path = PROJECT_ROOT) -> str:
+    """Return a sensible default process package slug for a Conductor workspace."""
+    env_slug = os.environ.get("LINCOLN_PROCESS_SLUG") or os.environ.get("CONDUCTOR_WORKSPACE_NAME")
+    if env_slug:
+        return validate_slug(env_slug)
+
+    # Conductor paths commonly look like .../workspaces/<workspace-slug>/<repo-name>.
+    if project_root.parent.name and project_root.parent.parent.name == "workspaces":
+        return validate_slug(project_root.parent.name)
+
+    return validate_slug(branch_slug(project_root))
+
+
+def discover_process_state_paths(project_root: Path = PROJECT_ROOT) -> list[Path]:
+    """Find branch process package state files at <process_slug>/workflow-stage.yaml."""
+    paths: list[Path] = []
+    for candidate in project_root.iterdir():
+        if not candidate.is_dir() or candidate.name in RESERVED_PROCESS_DIRS:
+            continue
+        state_path = candidate / STATE_FILENAME
+        if state_path.is_file():
+            paths.append(state_path)
+    return sorted(paths, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def discover_solo_state_paths(project_root: Path = PROJECT_ROOT) -> list[Path]:
+    """Find session-scoped solo workflow instances under .context/workflow/."""
+    solo_dir = project_root / SOLO_STATE_DIR
+    if not solo_dir.is_dir():
+        return []
+    paths = [p for p in solo_dir.glob("*.yaml") if p.is_file()]
+    return sorted(paths, key=lambda p: p.stat().st_mtime, reverse=True)
+
+
+def resolve_state_path(path: Path | None = None, project_root: Path = PROJECT_ROOT) -> Path:
+    """Resolve canonical process state, falling back to legacy root state files."""
+    env_path = os.environ.get("LINCOLN_STATE_FILE")
+    if path is None and env_path:
+        path = Path(env_path)
+
+    if path is not None:
+        path = path if path.is_absolute() else project_root / path
+        if path.exists():
+            return path
+        if path not in (ROOT_STATE_PATH, LEGACY_STATE_PATH):
+            return path
+
+    discovered = discover_process_state_paths(project_root)
+    if discovered:
+        return discovered[0]
+    solo = discover_solo_state_paths(project_root)
+    if solo:
+        return solo[0]
+    if ROOT_STATE_PATH.exists():
+        return ROOT_STATE_PATH
+    if LEGACY_STATE_PATH.exists():
+        return LEGACY_STATE_PATH
+    return ROOT_STATE_PATH
+
+
+def load_yaml(path: Path) -> Any:
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def get_process_slug(state: dict[str, Any] | None = None, state_path: Path | None = None) -> str:
+    if state:
+        variables = state.get("current_run", {}).get("variables", {})
+        if variables.get("process_slug"):
+            raw = str(variables["process_slug"])
+            if raw == SOLO_PROCESS_SLUG:
+                return raw
+            return validate_slug(raw)
+    if state_path and state_path.name == STATE_FILENAME and state_path.parent != PROJECT_ROOT / ".claude":
+        return validate_slug(state_path.parent.name)
+    return default_process_slug(PROJECT_ROOT)
+
+
+def interpolate_process_path(path: str, state: dict[str, Any] | None = None, state_path: Path | None = None) -> str:
+    return path.replace("{process_slug}", get_process_slug(state, state_path))
+
+
+def process_package_root(
+    process_slug: str | None = None,
+    state: dict[str, Any] | None = None,
+    state_path: Path | None = None,
+    project_root: Path = PROJECT_ROOT,
+) -> Path:
+    slug = process_slug or get_process_slug(state, state_path)
+    if slug == SOLO_PROCESS_SLUG:
+        return project_root / SOLO_PROCESS_SLUG
+    return project_root / validate_slug(slug)
+
+
+def is_process_state_path(path: Path, project_root: Path = PROJECT_ROOT) -> bool:
+    try:
+        rel = path.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        return False
+    return len(rel.parts) == 2 and rel.parts[1] == STATE_FILENAME and rel.parts[0] not in RESERVED_PROCESS_DIRS

package/framework/scripts/lincoln_prd.py

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""PRD lifecycle helper: freeze snapshots, read current version, migrate legacy paths."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from scripts.lincoln_index import VERSION_COMMENT_RE
+from scripts.lincoln_paths import (
+    atomic_write_text,
+    get_process_slug,
+    load_yaml,
+    process_package_root,
+    resolve_state_path,
+)
+
+
+def extract_prd_version(prd_path: Path) -> str | None:
+    """Return the version marker from an HTML PRD or a legacy Markdown PRD."""
+    if not prd_path.exists():
+        return None
+    text = prd_path.read_text(encoding="utf-8")
+    match = VERSION_COMMENT_RE.search(text)
+    return match.group(1) if match else None
+
+
+# Backwards-compatible alias used by early tests.
+extract_version = extract_prd_version
+
+VERSION_MARKER_RE = re.compile(r"\n?\s*\n?\Z", re.MULTILINE)
+
+
+def _error(message: str) -> None:
+    raise RuntimeError(message)
+
+
+def _package_root(args: argparse.Namespace) -> Path:
+    if args.package:
+        return PROJECT_ROOT / args.package
+
+    env_slug = os.environ.get("LINCOLN_PROCESS_SLUG")
+    if env_slug:
+        root = PROJECT_ROOT / env_slug
+        if root.exists():
+            return root
+        cwd_root = Path.cwd() / env_slug
+        if cwd_root.exists():
+            return cwd_root
+        return cwd_root
+
+    state_path = resolve_state_path(None, PROJECT_ROOT)
+    if state_path is not None and state_path.parent.exists():
+        try:
+            if state_path.exists():
+                state = load_yaml(state_path)
+                return process_package_root(
+                    state=state, state_path=state_path, project_root=PROJECT_ROOT
+                )
+            return state_path.parent
+        except Exception:
+            pass
+
+    _error(
+        "Could not determine package root. "
+        "Use --package or run from a Lincoln project with a state file."
+    )
+
+
+def _prd_path(root: Path) -> Path:
+    """Return the primary HTML PRD path, falling back to legacy root prd.md."""
+    html_path = root / "pages" / "docs" / "prd.html"
+    if html_path.exists():
+        return html_path
+    legacy_path = root / "prd.md"
+    if legacy_path.exists():
+        return legacy_path
+    return html_path
+
+
+def _snapshot_path(prd_path: Path, version: str) -> Path:
+    """Return the immutable snapshot path next to the PRD source."""
+    if prd_path.name == "prd.html":
+        return prd_path.parent / "snapshots" / f"prd-{version}.html"
+    return prd_path.with_name(f"prd-{version}.md")
+
+
+def freeze(package_root: Path | None = None, *, args: argparse.Namespace | None = None) -> Path:
+    """Copy the PRD to an immutable versioned snapshot based on its version marker."""
+    root = package_root or (args and _package_root(args))
+    if not root:
+        _error("package_root is required")
+    prd_path = _prd_path(root)
+    if not prd_path.exists():
+        _error(f"PRD not found: {prd_path}")
+
+    version = extract_prd_version(prd_path)
+    if not version:
+        _error(f"No version marker found in {prd_path}; add '<!-- version: vX.Y -->' before freezing.")
+
+    snapshot_path = _snapshot_path(prd_path, version)
+    snapshot_path.parent.mkdir(parents=True, exist_ok=True)
+    if snapshot_path.exists():
+        _error(
+            f"Snapshot already exists: {snapshot_path}. "
+            "PRD snapshots are protected by an immutability guarantee. "
+            "Bump the version marker in the PRD and freeze again."
+        )
+
+    atomic_write_text(snapshot_path, prd_path.read_text(encoding="utf-8"))
+    print(f"Frozen {snapshot_path}")
+    return snapshot_path
+
+
+def current_version(package_root: Path | None = None, *, args: argparse.Namespace | None = None) -> str:
+    """Print the version marker from the PRD."""
+    root = package_root or (args and _package_root(args))
+    if not root:
+        _error("package_root is required")
+    prd_path = _prd_path(root)
+    if not prd_path.exists():
+        _error(f"PRD not found: {prd_path}")
+
+    version = extract_prd_version(prd_path)
+    if not version:
+        _error(f"No version marker found in {prd_path}.")
+
+    print(version)
+    return version
+
+
+def _render_prd_html(title: str, version: str, markdown: str) -> str:
+    """Wrap legacy Markdown PRD content in the page-doc HTML template."""
+    template_path = PROJECT_ROOT / ".claude" / "templates" / "issue-package" / "page-doc.html.tpl"
+    if not template_path.exists():
+        return markdown
+    template = template_path.read_text(encoding="utf-8")
+    replacements = {
+        "{TITLE}": title,
+        "{NAV_GROUP}": "Docs",
+        "{VERSION}": version,
+        "{STAGE}": "clarify",
+        "{UID}": "",
+        "{MARKDOWN_SOURCE}": markdown,
+    }
+    for placeholder, value in replacements.items():
+        template = template.replace(placeholder, value)
+    return template
+
+
+def migrate(
+    package_root: Path | None = None,
+    session_id: str | None = None,
+    *,
+    args: argparse.Namespace | None = None,
+) -> Path:
+    """Move a legacy requirements/{session_id}/prd.md into the HTML portal."""
+    root = package_root or (args and _package_root(args))
+    if not root:
+        _error("package_root is required")
+
+    sid = session_id or (args and args.session_id)
+    if not sid:
+        _error("--session-id is required for migrate")
+
+    legacy_path = root / "requirements" / sid / "prd.md"
+    if not legacy_path.exists():
+        _error(f"Legacy PRD not found: {legacy_path}")
+
+    target_path = root / "pages" / "docs" / "prd.html"
+    if target_path.exists():
+        _error(f"Root PRD already exists: {target_path}. Manual merge required.")
+
+    content = legacy_path.read_text(encoding="utf-8")
+    version = extract_prd_version(legacy_path)
+    if not version:
+        version = "v1.0"
+        content = f"<!-- version: {version} -->\n\n" + content.lstrip("\n")
+    else:
+        # Avoid duplicating the version marker once the template injects it.
+        content = VERSION_COMMENT_RE.sub("", content, count=1).strip("\n")
+
+    html = _render_prd_html("PRD", version, content)
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(target_path, html)
+    legacy_path.unlink()
+    print(f"Migrated {legacy_path} -> {target_path}")
+    return target_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Lincoln PRD lifecycle helper")
+    parser.add_argument("--package", help="Process package slug (e.g., issue-85)")
+    parser.add_argument("--session-id", help="Interview session id (required for migrate)")
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    subparsers.add_parser("freeze", help="Freeze pages/docs/prd.html into an immutable versioned snapshot")
+    subparsers.add_parser("current-version", help="Print the current PRD version marker")
+    migrate_parser = subparsers.add_parser("migrate", help="Move legacy requirements/{session_id}/prd.md into pages/docs/prd.html")
+    migrate_parser.add_argument("--session-id", required=True, help="Legacy session directory name")
+
+    args = parser.parse_args()
+
+    try:
+        if args.action == "freeze":
+            freeze(args=args)
+        elif args.action == "current-version":
+            current_version(args=args)
+        elif args.action == "migrate":
+            migrate(args=args)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/framework/scripts/lincoln_role.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Print the content of a Lincoln agent role.
+
+Usage:
+    python3 scripts/lincoln_role.py --role pm [topic words...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from lincoln_paths import PROJECT_ROOT, assert_contained, validate_name  # noqa: E402
+
+AGENTS_DIR = PROJECT_ROOT / ".claude" / "agents"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Print a Lincoln agent role")
+    parser.add_argument("--role", required=True, help="Agent role filename stem")
+    parser.add_argument("topic", nargs="*", help="Optional topic/context")
+    args = parser.parse_args()
+
+    try:
+        validate_name(args.role, "role name")
+        path = AGENTS_DIR / f"{args.role}.md"
+        assert_contained(path, AGENTS_DIR, "agent role path")
+        if not path.exists():
+            print(f"ERROR: agent role not found: {path}", file=sys.stderr)
+            return 1
+
+        text = path.read_text(encoding="utf-8")
+        if args.topic:
+            print(f"Topic/context: {' '.join(args.topic)}\n")
+        print(text)
+        return 0
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_scenario.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Print the prompt for a Lincoln scenario.
+
+Usage:
+    python3 scripts/lincoln_scenario.py --scenario make-prd [topic words...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from lincoln_paths import PROJECT_ROOT, validate_name  # noqa: E402
+
+SCENARIOS_PATH = PROJECT_ROOT / ".claude" / "harnesses" / "scenarios.yaml"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Print a Lincoln scenario prompt")
+    parser.add_argument("--scenario", required=True, help="Scenario id")
+    parser.add_argument("topic", nargs="*", help="Optional topic/context")
+    args = parser.parse_args()
+
+    if not SCENARIOS_PATH.exists():
+        print(f"ERROR: scenarios file not found: {SCENARIOS_PATH}", file=sys.stderr)
+        return 1
+
+    try:
+        validate_name(args.scenario, "scenario id")
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    data = yaml.safe_load(SCENARIOS_PATH.read_text(encoding="utf-8")) or {}
+    scenarios = data.get("scenarios", {})
+    scenario = scenarios.get(args.scenario)
+    if not scenario:
+        available = ", ".join(sorted(scenarios))
+        print(f"ERROR: scenario '{args.scenario}' not found. Available: {available}", file=sys.stderr)
+        return 1
+
+    if args.topic:
+        print(f"Topic/context: {' '.join(args.topic)}\n")
+    print(f"# Scenario: {args.scenario}")
+    print(f"\nDescription: {scenario.get('description', '')}")
+    print(f"Recommended role: {scenario.get('role', '')}")
+    print(f"Skills: {', '.join(scenario.get('skills', []))}")
+    print(f"\nGoal: {scenario.get('goal', '')}")
+    print("\nExecute the recommended skills in order. Follow Lincoln stage gates and human_gate rules.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_session_start_metrics.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Estimate the token cost of a Lincoln session-start hook output (#63).
+
+Tries tiktoken for an accurate count; falls back to a stable heuristic
+(CJK characters as one token each, whitespace-separated non-CJK words as
+tokens) so the metric stays deterministic without requiring an extra dependency.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+CJK_RE = re.compile(
+    r"[一-鿿぀-ゟ゠-ヿ가-힯]"
+)
+
+
+def estimate_tokens(text: str) -> int:
+    """Return a deterministic token estimate for *text*."""
+    try:
+        import tiktoken  # type: ignore
+
+        enc = tiktoken.get_encoding("cl100k_base")
+        return len(enc.encode(text))
+    except Exception:
+        pass
+
+    cjk_tokens = len(CJK_RE.findall(text))
+    non_cjk = CJK_RE.sub(" ", text)
+    word_tokens = len(non_cjk.split())
+    return cjk_tokens + word_tokens
+
+
+def compute_metrics(text: str, stage: str = "", status: str = "") -> dict[str, Any]:
+    return {
+        "schema_version": "1.0.0",
+        "stage": stage,
+        "status": status,
+        "bytes": len(text.encode("utf-8")),
+        "chars": len(text),
+        "tokens": estimate_tokens(text),
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Estimate token count for a Lincoln session-start output."
+    )
+    parser.add_argument("--input", type=Path, required=True, help="File to analyze.")
+    parser.add_argument("--output", type=Path, required=True, help="JSON output path.")
+    parser.add_argument("--stage", default="", help="Current stage id.")
+    parser.add_argument("--status", default="", help="Current stage status.")
+    args = parser.parse_args(argv)
+
+    text = args.input.read_text(encoding="utf-8")
+    metrics = compute_metrics(text, stage=args.stage, status=args.status)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(
+        json.dumps(metrics, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_skill_prompt.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Print the content of a Lincoln skill.
+
+Usage:
+    python3 scripts/lincoln_skill_prompt.py --skill lc-first-principles
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from lincoln_paths import PROJECT_ROOT, assert_contained, validate_name  # noqa: E402
+
+SKILLS_DIR = PROJECT_ROOT / ".claude" / "skills"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Print a Lincoln skill prompt")
+    parser.add_argument("--skill", required=True, help="Skill folder name")
+    args = parser.parse_args()
+
+    try:
+        validate_name(args.skill, "skill name")
+        skill_dir = SKILLS_DIR / args.skill
+        skill_md = skill_dir / "SKILL.md"
+        assert_contained(skill_md, SKILLS_DIR, "skill path")
+        if not skill_md.exists():
+            print(f"ERROR: skill not found: {skill_dir}", file=sys.stderr)
+            return 1
+
+        parts = [skill_md.read_text(encoding="utf-8")]
+        prompt_path = skill_dir / "prompts" / "main.md"
+        if prompt_path.exists():
+            parts.append(prompt_path.read_text(encoding="utf-8"))
+
+        print("\n\n".join(parts))
+        return 0
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())