@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/scripts/lincoln_trace.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Lincoln session trace writer.
+
+Appends structured, immutable trace entries to a per-process JSONL file.
+Designed to be called from the PostToolUse hook for every tool invocation
+(except recursive or no-op tools).
+"""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+import logging
+import os
+import re
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Ensure project root on path when invoked as a script
+_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_paths import (  # noqa: E402
+    get_process_slug,
+    load_yaml,
+    process_package_root,
+)
+
+TRACE_SCHEMA_VERSION = "1.0.0"
+
+# Tools whose invocations are not traced to avoid recursion or noise.
+NO_TRACE_TOOLS = {"Read", "Grep", "Glob"}
+
+# Task-management tools that share the same trace category and redaction rules.
+TASK_TOOLS = frozenset({
+    "TaskCreate",
+    "TaskUpdate",
+    "TaskGet",
+    "TaskList",
+    "TaskOutput",
+    "TaskStop",
+})
+
+# Maximum length stored for a Bash command summary in the trace entry.
+COMMAND_SUMMARY_MAX_LEN = 500
+
+# Basic secret masking for Bash command strings. Values following common secret
+# flags or environment variable assignments are replaced with `***`.
+_MASK_PATTERNS = [
+    re.compile(r"(?i)((?:--api-key|-k|--token|--password|--secret|--access-token)\s+)\S+"),
+    re.compile(r"(?i)((?:--api-key|-k|--token|--password|--secret|--access-token)=)\S+"),
+    re.compile(
+        r"(?i)\b(API_KEY|TOKEN|PASSWORD|SECRET|GH_TOKEN|GITHUB_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|ACCESS_TOKEN)=\S+"
+    ),
+    re.compile(r"(?i)(Authorization:\s*(?:Bearer|Basic|Token)\s+)\S+"),
+    re.compile(r"(?i)(X-Api-Key:\s+)\S+"),
+    re.compile(r"(?i)((?:--user|-u)\s+)\S+:\S+"),
+    re.compile(r"(?i)(https?://)[^:]+:[^@]+@"),
+    re.compile(r"(?i)([\?\x26])(api_key|token|key)=[^\x26]+"),
+]
+
+
+def categorize_tool(tool: str) -> str:
+    """Bucket a Claude Code tool name into a Lincoln trace category."""
+    if tool == "Skill":
+        return "skill"
+    if tool == "Agent":
+        return "agent"
+    if tool in ("Read", "Grep", "Glob"):
+        return "read"
+    if tool == "Write":
+        return "write"
+    if tool == "Edit":
+        return "edit"
+    if tool == "Bash":
+        return "bash"
+    if tool in TASK_TOOLS:
+        return "task"
+    if tool.startswith("mcp__"):
+        return "mcp"
+    if tool == "LincolnHandoff":
+        return "handoff"
+    return "other"
+
+
+def _first_non_none(mapping: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in mapping:
+            return mapping[key]
+    return None
+
+
+def _mask_command(command: str) -> str:
+    masked = command
+    for pattern in _MASK_PATTERNS:
+        masked = pattern.sub(r"\1***", masked)
+    return masked
+
+
+def _redact_bash(args: dict[str, Any]) -> dict[str, Any]:
+    command = args.get("command", "")
+    return {"command": _mask_command(str(command))[:COMMAND_SUMMARY_MAX_LEN]}
+
+
+def _redact_file(args: dict[str, Any]) -> dict[str, Any]:
+    return {"file_path": str(args.get("file_path", ""))[:500]}
+
+
+def _redact_skill(args: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "skill": str(args.get("skill", ""))[:200],
+        "args": str(args.get("args", ""))[:500],
+    }
+
+
+def _redact_agent(args: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "subagent_type": str(args.get("subagent_type", ""))[:200] or "general-purpose",
+        "description": str(args.get("description", ""))[:300],
+    }
+
+
+def _redact_task(args: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "subject": str(_first_non_none(args, "subject", "taskId", "description") or "")[:300],
+    }
+
+
+def _redact_mcp(args: dict[str, Any]) -> dict[str, Any]:
+    summary: dict[str, Any] = {}
+    for key in ("path", "name", "url", "projectId", "skill", "query"):
+        if key in args:
+            summary[key] = str(args[key])[:200]
+    return summary
+
+
+def _redact_handoff(args: dict[str, Any]) -> dict[str, Any]:
+    return {"stage": str(args.get("stage", ""))[:100]}
+
+
+def _redact_generic(args: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: str(value)[:200]
+        for key, value in args.items()
+        if isinstance(value, (str, int, float, bool))
+    }
+
+
+def redact_args(tool: str, args: Any) -> dict[str, Any]:
+    """Produce a privacy-safe summary of tool arguments.
+
+    This implementation is intentionally conservative: it records paths and
+    high-level identifiers but does not store secrets, full command output, or
+    large payloads. It is designed as a pluggable hook for future MCP-specific
+    redaction rules.
+    """
+    if not isinstance(args, dict):
+        return {"_raw_type": type(args).__name__}
+
+    if tool == "Bash":
+        return _redact_bash(args)
+    if tool in ("Write", "Edit", "Read"):
+        return _redact_file(args)
+    if tool == "Skill":
+        return _redact_skill(args)
+    if tool == "Agent":
+        return _redact_agent(args)
+    if tool == "LincolnHandoff":
+        return _redact_handoff(args)
+    if tool in TASK_TOOLS:
+        return _redact_task(args)
+    if tool.startswith("mcp__"):
+        return _redact_mcp(args)
+    return _redact_generic(args)
+
+
+def generate_sequence_id() -> str:
+    """Return a globally unique trace sequence identifier."""
+    return uuid.uuid4().hex
+
+
+def _resolve_trace_file(state: dict[str, Any] | None, state_path: Path | None) -> Path:
+    """Decide which JSONL file to write to, honouring child-agent overrides."""
+    env_file = os.environ.get("LINCOLN_TRACE_FILE")
+    if env_file:
+        return Path(env_file)
+
+    project_root = state_path.resolve().parents[1] if state_path else _PROJECT_ROOT
+    slug = get_process_slug(state, state_path)
+    root = process_package_root(slug, state, state_path, project_root=project_root)
+    trace_dir = root / ".trace"
+
+    agent_id = os.environ.get("LINCOLN_AGENT_ID")
+    if agent_id:
+        return trace_dir / f"lc-trace-{agent_id}.jsonl"
+
+    return trace_dir / "lc-trace.jsonl"
+
+
+def _get_run_id(state: dict[str, Any] | None, run_id: str | None) -> str:
+    if run_id:
+        return run_id
+    if state:
+        return str(state.get("current_run", {}).get("run_id", "")) or "unknown"
+    return "unknown"
+
+
+def _get_stage(state: dict[str, Any] | None, stage: str | None) -> str:
+    if stage:
+        return stage
+    if state:
+        return str(state.get("current_run", {}).get("current_stage", "")) or "unknown"
+    return "unknown"
+
+
+def _safe_json_loads(value: Any) -> Any:
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except Exception as exc:
+            logging.warning("Could not parse trace args as JSON: %s", exc)
+            return {"_unparsed": value[:200]}
+    return value
+
+
+def _load_state(state_path: Path | None) -> dict[str, Any] | None:
+    if not state_path or not state_path.exists():
+        return None
+    try:
+        return load_yaml(state_path)
+    except Exception as exc:
+        logging.warning("Failed to load workflow state from %s: %s", state_path, exc)
+        return None
+
+
+def _build_trace_target(tool: str, args_summary: dict[str, Any]) -> str:
+    if tool == "Skill":
+        return str(args_summary.get("skill", ""))
+    if tool == "Agent":
+        return str(args_summary.get("subagent_type", ""))
+    if tool == "Bash":
+        return str(args_summary.get("command", ""))[:120]
+    if "file_path" in args_summary:
+        return str(args_summary["file_path"])
+    return str(args_summary.get("path", args_summary.get("name", "")))
+
+
+def _build_trace_entry(
+    tool: str,
+    args_summary: dict[str, Any],
+    exit_code: int,
+    run_id: str,
+    stage: str,
+) -> dict[str, Any]:
+    return {
+        "schema_version": TRACE_SCHEMA_VERSION,
+        "sequence_id": generate_sequence_id(),
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "run_id": run_id,
+        "stage": stage,
+        "tool": tool,
+        "category": categorize_tool(tool),
+        "target": _build_trace_target(tool, args_summary),
+        "exit_code": int(exit_code),
+        "args_summary": args_summary,
+    }
+
+
+def _append_trace_line(trace_file: Path, entry: dict[str, Any]) -> None:
+    trace_file.parent.mkdir(parents=True, exist_ok=True)
+    line = json.dumps(entry, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with open(trace_file, "a", encoding="utf-8") as fh:
+        fcntl.lockf(fh.fileno(), fcntl.LOCK_EX)
+        try:
+            fh.write(line)
+            fh.flush()
+        finally:
+            fcntl.lockf(fh.fileno(), fcntl.LOCK_UN)
+
+
+def append_trace_entry(
+    state_path: Path | None,
+    tool: str,
+    args: Any,
+    exit_code: int,
+    stage: str | None = None,
+    run_id: str | None = None,
+) -> Path | None:
+    """Append a single trace entry to the appropriate JSONL file.
+
+    The write is atomic with respect to other processes on the same host: the
+    file is locked while appending, so concurrent parent and child agents do
+    not interleave JSON lines.
+    """
+    if tool in NO_TRACE_TOOLS:
+        return None
+
+    state = _load_state(state_path)
+    resolved_run_id = _get_run_id(state, run_id)
+    resolved_stage = _get_stage(state, stage)
+    trace_file = _resolve_trace_file(state, state_path)
+    args_summary = redact_args(tool, _safe_json_loads(args))
+    entry = _build_trace_entry(tool, args_summary, exit_code, resolved_run_id, resolved_stage)
+    _append_trace_line(trace_file, entry)
+    return trace_file
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Append a Lincoln trace entry")
+    parser.add_argument("--state-file", type=Path, default=None)
+    parser.add_argument("--tool", required=True)
+    parser.add_argument("--args-json", default="{}")
+    parser.add_argument("--exit-code", type=int, default=0)
+    parser.add_argument("--stage", default=None)
+    parser.add_argument("--run-id", default=None)
+    args = parser.parse_args(argv)
+
+    append_trace_entry(
+        state_path=args.state_file,
+        tool=args.tool,
+        args=args.args_json,
+        exit_code=args.exit_code,
+        stage=args.stage,
+        run_id=args.run_id,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_workflow.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Lincoln workflow bundle CLI backing the lc-wf-* harness commands.
+
+Usage:
+    python3 scripts/lincoln_workflow.py list
+    python3 scripts/lincoln_workflow.py start --workflow <name> [--issue-number N] [--force]
+    python3 scripts/lincoln_workflow.py status
+
+- solo workflows render a session-scoped instance at .context/workflow/<name>.yaml
+- team workflows delegate to scripts/init-lincoln-branch.sh (branch + issue package)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from lincoln_paths import PROJECT_ROOT, assert_contained, validate_name  # noqa: E402
+
+WORKFLOWS_DIR = PROJECT_ROOT / ".claude" / "workflows"
+SOLO_TEMPLATE_PATH = PROJECT_ROOT / ".claude" / "templates" / "solo-workflow-context.yaml"
+SOLO_STATE_DIR = PROJECT_ROOT / ".context" / "workflow"
+INIT_BRANCH_SCRIPT = PROJECT_ROOT / "scripts" / "init-lincoln-branch.sh"
+STAGE_LOADER_SCRIPT = PROJECT_ROOT / "scripts" / "stage_loader.py"
+
+DEFAULT_EXECUTION_MODE = "team"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def run_id_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+def load_workflow_definition(name: str) -> dict[str, Any]:
+    try:
+        validate_name(name, "workflow name")
+    except ValueError as exc:
+        raise SystemExit(f"ERROR: {exc}")
+    path = WORKFLOWS_DIR / f"{name}.yaml"
+    assert_contained(path, WORKFLOWS_DIR, "workflow path")
+    if not path.is_file():
+        available = ", ".join(sorted(p.stem for p in WORKFLOWS_DIR.glob("*.yaml")))
+        raise SystemExit(f"ERROR: unknown workflow '{name}'. Available: {available}")
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return data.get("workflow", data)
+
+
+def list_workflows() -> int:
+    rows = []
+    for path in sorted(WORKFLOWS_DIR.glob("*.yaml")):
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        wf = data.get("workflow", {})
+        rows.append(
+            (
+                wf.get("name", path.stem),
+                wf.get("execution_mode", DEFAULT_EXECUTION_MODE),
+                wf.get("description", ""),
+            )
+        )
+    if not rows:
+        print("No workflows found under .claude/workflows/")
+        return 1
+    print(f"{'NAME':<32} {'MODE':<6} DESCRIPTION")
+    for name, mode, description in rows:
+        print(f"{name:<32} {mode:<6} {description}")
+    return 0
+
+
+def _default_session_id(workflow_name: str) -> str:
+    """Generate a filesystem-safe session id for solo workflows."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    safe = re.sub(r"[^a-z0-9_-]", "-", workflow_name.lower())
+    return f"{safe}-{timestamp}"
+
+
+def start_solo(workflow_name: str, wf: dict[str, Any], force: bool = False, session_id: str | None = None) -> int:
+    try:
+        validate_name(workflow_name, "workflow name")
+    except ValueError as exc:
+        raise SystemExit(f"ERROR: {exc}")
+    state_path = SOLO_STATE_DIR / f"{workflow_name}.yaml"
+    assert_contained(state_path, SOLO_STATE_DIR, "solo state path")
+    if state_path.exists() and not force:
+        raise SystemExit(f"ERROR: solo instance already exists: {state_path} (use --force to overwrite)")
+
+    state = yaml.safe_load(SOLO_TEMPLATE_PATH.read_text(encoding="utf-8"))
+    steps = wf.get("steps", [])
+    first_stage = steps[0].get("id", "not_started") if steps else "not_started"
+    now = now_iso()
+
+    state["workflow"]["name"] = wf.get("name", workflow_name)
+    state["workflow"]["version"] = wf.get("version", "1.0.0")
+    state["workflow"]["template"] = workflow_name
+
+    current_run = state["current_run"]
+    current_run["run_id"] = f"{workflow_name}-{run_id_stamp()}"
+    current_run["current_stage"] = first_stage
+    current_run["status"] = "in_progress"
+    current_run["started_at"] = now
+    current_run["last_updated_at"] = now
+    state["recovery"]["can_resume_from"] = first_stage
+
+    variables = state.setdefault("current_run", {}).setdefault("variables", {})
+    variables["session_id"] = session_id or _default_session_id(workflow_name)
+
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = state_path.with_suffix(".yaml.tmp")
+    try:
+        tmp_path.write_text(
+            yaml.dump(state, allow_unicode=True, sort_keys=False, width=120), encoding="utf-8"
+        )
+        tmp_path.replace(state_path)
+    except Exception:
+        if tmp_path.exists():
+            tmp_path.unlink()
+        raise
+
+    try:
+        display_path = state_path.relative_to(PROJECT_ROOT)
+    except ValueError:
+        display_path = state_path
+    print(f"Solo workflow instance created: {display_path}")
+    print(f"Workflow: {workflow_name} (solo) | first stage: {first_stage}")
+    print(f"Next: python3 scripts/stage_loader.py --stage {first_stage} --action validate-entry")
+    return 0
+
+
+def start_team(workflow_name: str, issue_number: str | None) -> int:
+    if not issue_number:
+        raise SystemExit(
+            "ERROR: --issue-number is required for team workflows (branch-scoped issue package)"
+        )
+    cmd = [
+        "bash",
+        str(INIT_BRANCH_SCRIPT),
+        "--workflow",
+        workflow_name,
+        "--issue-number",
+        str(issue_number),
+    ]
+    return subprocess.run(cmd, cwd=PROJECT_ROOT).returncode
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    wf = load_workflow_definition(args.workflow)
+    mode = wf.get("execution_mode", DEFAULT_EXECUTION_MODE)
+    if mode == "solo":
+        return start_solo(args.workflow, wf, args.force, getattr(args, "session_id", None))
+    return start_team(args.workflow, args.issue_number)
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    return subprocess.run(
+        [sys.executable, str(STAGE_LOADER_SCRIPT), "--action", "status"], cwd=PROJECT_ROOT
+    ).returncode
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Lincoln workflow bundle CLI (lc-wf-* commands)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("list", help="List registered workflows with execution mode")
+
+    start = sub.add_parser("start", help="Start a workflow run (solo instance or team issue package)")
+    start.add_argument("--workflow", required=True, help="Workflow name under .claude/workflows/")
+    start.add_argument("--issue-number", help="Issue number (required for team workflows)")
+    start.add_argument("--session-id", help="Session identifier for solo artifacts (auto-generated if omitted)")
+    start.add_argument("--force", action="store_true", help="Overwrite existing solo instance")
+
+    sub.add_parser("status", help="Show current workflow run status")
+
+    args = parser.parse_args()
+    if args.command == "list":
+        return list_workflows()
+    if args.command == "start":
+        try:
+            validate_name(args.workflow, "workflow name")
+            return cmd_start(args)
+        except ValueError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 1
+    return cmd_status(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/list-active-lincoln-branches.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# List all active Lincoln feature branches and their current stage state.
+#
+# Usage:
+#   scripts/list-active-lincoln-branches.sh [--waiting-for-me <role>]
+#
+# Options:
+#   --waiting-for-me <role>  Filter by waiting_for role (pm|agent|agent-fix|next-role)
+#
+# Output:
+#   Calls lincoln-status.py --format table for each remote issue-* branch
+#   (legacy lincoln/* branches are also listed).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$ROOT"
+
+REMOTE=""
+FILTER_ROLE=""
+
+# Parse optional --waiting-for-me flag
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --waiting-for-me)
+            FILTER_ROLE="$2"
+            shift 2
+            ;;
+        *)
+            REMOTE="$1"
+            shift
+            ;;
+    esac
+done
+REMOTE="${REMOTE:-origin}"
+
+echo "==> Fetching remote branches from $REMOTE"
+git fetch "$REMOTE" '+refs/heads/issue-*:refs/remotes/'"$REMOTE"'/issue-*' 2>/dev/null || true
+git fetch "$REMOTE" '+refs/heads/lincoln/*:refs/remotes/'"$REMOTE"'/lincoln/*' 2>/dev/null || true
+
+BRANCHES=$(git branch -r --list "$REMOTE/issue-*" --list "$REMOTE/lincoln/*" 2>/dev/null || true)
+
+if [[ -z "$BRANCHES" ]]; then
+    echo "No active Lincoln branches found."
+    exit 0
+fi
+
+echo ""
+
+for ref in $BRANCHES; do
+    # Extract branch name without remote prefix
+    branch="${ref#$REMOTE/}"
+
+    # Prefer the issue work-package state file; fall back to the legacy path.
+    state_yaml=$(git show "$ref:$branch/workflow-stage.yaml" 2>/dev/null || \
+        git show "$ref:.claude/workflow-state.yaml" 2>/dev/null || true)
+
+    status_json=""
+    if [[ -n "$state_yaml" ]]; then
+        status_json=$(printf '%s' "$state_yaml" | \
+            python3 "$ROOT/scripts/lincoln-status.py" --format json --state-file /dev/stdin 2>/dev/null || true)
+    fi
+
+    if [[ -z "$status_json" ]]; then
+        printf "%-50s %-22s %-20s %-15s\n" "$branch" "unknown" "no-state-file" ""
+        continue
+    fi
+
+    # Extract fields using Python
+    python3 - "$branch" "$status_json" "$FILTER_ROLE" <<'PY'
+import json
+import sys
+
+branch, raw, filter_role = sys.argv[1:4]
+data = json.loads(raw)
+
+stage_id = data.get("current_stage") or "unknown"
+stage_status = data.get("stage_status") or "unknown"
+waiting_for = data.get("waiting_for") or ""
+
+if filter_role and waiting_for != filter_role:
+    sys.exit(0)
+
+print(f"{branch:50} {stage_id:22} {stage_status:20} {waiting_for:15}")
+PY
+done