@sushanglewis/lincoln 1.5.0 → 1.5.2

package/framework/.claude/hooks/on-session-start.sh

@@ -0,0 +1,427 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# On-session-start hook for Lincoln workflow.
+# Loads stage context, checks dependencies, parses <process_slug>/workflow-stage.yaml,
+# reads previous node handoff, and injects current node driving context.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOCAL_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT_ROOT="$(pwd)"
+
+FRAMEWORK_ROOT="${CLAUDE_PLUGIN_ROOT:-${LINCOLN_HOME:-}}"
+if [[ -z "$FRAMEWORK_ROOT" ]]; then
+  # If this hook file lives inside a vendored project framework, prefer that.
+  if [[ "$SCRIPT_DIR" == "$LOCAL_ROOT/.claude/hooks"* && -d "$LOCAL_ROOT/.claude/stages" ]]; then
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  elif [[ -d "$HOME/.lincoln/current" ]]; then
+    FRAMEWORK_ROOT="$HOME/.lincoln/current"
+  else
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  fi
+fi
+
+if [[ "$FRAMEWORK_ROOT" != "$LOCAL_ROOT" ]]; then
+  # Global plugin mode: only activate if the project has opted in.
+  MARKER_FOUND="false"
+  SEARCH_DIR="$PROJECT_ROOT"
+  while [[ "$SEARCH_DIR" != "/" ]]; do
+    if [[ -f "$SEARCH_DIR/.lincoln.yaml" || -f "$SEARCH_DIR/.claude/workflow-state.yaml" ]]; then
+      MARKER_FOUND="true"
+      break
+    fi
+    SEARCH_DIR="$(dirname "$SEARCH_DIR")"
+  done
+  if [[ "$MARKER_FOUND" != "true" && -z "${LINCOLN_ALWAYS_ON:-}" ]]; then
+    echo "Lincoln inactive: no .lincoln.yaml in $PROJECT_ROOT"
+    exit 0
+  fi
+fi
+
+ROOT="$PROJECT_ROOT"
+
+if [ -x "$FRAMEWORK_ROOT/.venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/.venv/bin/python3"
+elif [ -x "$FRAMEWORK_ROOT/venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/venv/bin/python3"
+elif [ -x "$HOME/.lincoln/venv/bin/python3" ]; then
+    PYTHON="$HOME/.lincoln/venv/bin/python3"
+else
+    PYTHON="python3"
+fi
+
+STATE_FILE="${LINCOLN_STATE_FILE:-}"
+LEGACY_STATE_FILE="$FRAMEWORK_ROOT/.claude/workflow-state.yaml"
+
+# Runtime state captured for optional machine-readable JSON output
+# (LINCOLN_SESSION_START_JSON=1). Updated at key decision points.
+_LINCOLN_SETUP_COMPLETE="false"
+_LINCOLN_HAS_STATE="false"
+_LINCOLN_GUIDANCE_INJECTED="false"
+_LINCOLN_CURRENT_STAGE="not_started"
+_LINCOLN_STATUS="not_started"
+_LINCOLN_WORKFLOW_TEMPLATE="unknown"
+_LINCOLN_PROCESS_SLUG=""
+
+# Capture the full hook stdout so we can quantify the session-start token cost (#63).
+HOOK_OUTPUT_CAPTURE="$(mktemp)"
+trap 'rm -f "$HOOK_OUTPUT_CAPTURE"' EXIT
+exec > >(tee "$HOOK_OUTPUT_CAPTURE")
+
+emit_session_start_json() {
+    if [[ "${LINCOLN_SESSION_START_JSON:-}" != "1" ]]; then
+        return 0
+    fi
+    "$PYTHON" - "$_LINCOLN_SETUP_COMPLETE" "$_LINCOLN_HAS_STATE" "$_LINCOLN_GUIDANCE_INJECTED" "$_LINCOLN_CURRENT_STAGE" "$_LINCOLN_STATUS" "$_LINCOLN_WORKFLOW_TEMPLATE" "$_LINCOLN_PROCESS_SLUG" <<'PY'
+import sys, json
+setup_complete = sys.argv[1] == "true"
+has_state = sys.argv[2] == "true"
+guidance_injected = sys.argv[3] == "true"
+current_stage = sys.argv[4]
+status = sys.argv[5]
+workflow_template = sys.argv[6]
+process_slug = sys.argv[7]
+print(json.dumps({
+    "schema_version": "1.0.0",
+    "has_state": has_state,
+    "guidance_injected": guidance_injected,
+    "setup_complete": setup_complete,
+    "current_stage": current_stage,
+    "status": status,
+    "workflow_template": workflow_template,
+    "process_slug": process_slug,
+}))
+PY
+}
+
+# Reset any stale task-tool burst counter from a previous session
+rm -f "$ROOT/.context/task-tool-burst.json"
+
+echo ""
+echo "=== Lincoln Session Start ==="
+echo ""
+
+# 1. Dependency check + first-run prompt (LINCOLN_SKIP_DEP_CHECK=1 seals this off for tests)
+if [[ "${LINCOLN_SKIP_DEP_CHECK:-}" != "1" && -f "$FRAMEWORK_ROOT/.claude/skills/dependencies.yaml" ]]; then
+    echo "[Lincoln] Checking dependencies..."
+    if ! "$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln-setup.py" check --root "$ROOT" > /dev/null 2>&1; then
+        SETUP_COMPLETE="false"
+        if [[ -f "$ROOT/.context/lc-setup-state.yaml" ]]; then
+            if "$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln-setup.py" is-setup-complete --root "$ROOT" > /dev/null 2>&1; then
+                SETUP_COMPLETE="true"
+                _LINCOLN_SETUP_COMPLETE="true"
+            fi
+        fi
+        if [[ "$SETUP_COMPLETE" != "true" ]]; then
+            echo ""
+            echo "Lincoln 依赖未就绪。请调用 lc-setup 技能完成一次性安装；安装完成前不要进行其他 Lincoln 工作流操作。"
+            echo ""
+            emit_session_start_json
+            exit 0
+        fi
+    else
+        _LINCOLN_SETUP_COMPLETE="true"
+    fi
+    echo ""
+else
+    # Even when dependency check is skipped, surface setup completeness in the JSON shape.
+    if [[ -f "$ROOT/.context/lc-setup-state.yaml" ]]; then
+        if "$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln-setup.py" is-setup-complete --root "$ROOT" > /dev/null 2>&1; then
+            _LINCOLN_SETUP_COMPLETE="true"
+        fi
+    fi
+fi
+
+# Print the cold-start opening guidance block (fresh repo / unclear issue branch).
+print_opening_guidance() {
+    _LINCOLN_GUIDANCE_INJECTED="true"
+    echo ""
+    echo "=== Lincoln 开场引导 ==="
+    echo ""
+    echo "Lincoln 当前没有可驱动的工作状态。请先完成 .claude/skills/lc-workflow-router/prompts/intake-prompt.md 中的摸排 → 判断 → 确认流程。"
+    echo "如需初始化 issue 工作包，由你（Agent）代为执行 scripts/init-lincoln-branch.sh，不让用户敲命令。"
+    echo ""
+    echo "=== End Lincoln 开场引导 ==="
+    echo ""
+}
+
+# 2. Determine state file (process package preferred, legacy fallback)
+STATE_FILE=$("$PYTHON" - "$FRAMEWORK_ROOT" "$ROOT" "$STATE_FILE" <<'PY'
+import sys
+from pathlib import Path
+framework_root = Path(sys.argv[1])
+project_root = Path(sys.argv[2])
+provided = sys.argv[3]
+sys.path.insert(0, str(framework_root))
+from scripts.lincoln_paths import resolve_state_path
+path = Path(provided) if provided else None
+print(resolve_state_path(path, project_root))
+PY
+)
+
+CURRENT_BRANCH="$(git branch --show-current 2>/dev/null || true)"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    echo "No Lincoln state file found ($STATE_FILE)."
+    if [[ "$CURRENT_BRANCH" == issue-* ]]; then
+        ISSUE_NUMBER="${CURRENT_BRANCH#issue-}"
+        # Strip any suffix after the issue number (e.g. issue-33-follow-up -> 33)
+        ISSUE_NUMBER="${ISSUE_NUMBER%%-*}"
+        if [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+            echo "Auto-initializing issue work package for branch $CURRENT_BRANCH..."
+            "$FRAMEWORK_ROOT/scripts/init-lincoln-branch.sh" --issue-number "$ISSUE_NUMBER" --no-commit --auto || {
+                echo "Failed to auto-initialize issue work package. Run manually:"
+                echo "  scripts/init-lincoln-branch.sh --issue-number $ISSUE_NUMBER"
+                echo "=== End Lincoln Session Start ==="
+                echo ""
+                emit_session_start_json
+                exit 0
+            }
+            # Re-resolve state file after initialization
+            STATE_FILE=$("$PYTHON" - "$FRAMEWORK_ROOT" "$ROOT" "" <<'PY'
+import sys
+from pathlib import Path
+framework_root = Path(sys.argv[1])
+project_root = Path(sys.argv[2])
+sys.path.insert(0, str(framework_root))
+from scripts.lincoln_paths import resolve_state_path
+print(resolve_state_path(None, project_root))
+PY
+)
+        else
+            echo "Current branch looks like an issue branch but issue number is unclear."
+            print_opening_guidance
+            echo "=== End Lincoln Session Start ==="
+            echo ""
+            emit_session_start_json
+            exit 0
+        fi
+    else
+        print_opening_guidance
+        echo "=== End Lincoln Session Start ==="
+        echo ""
+        emit_session_start_json
+        exit 0
+    fi
+fi
+
+_LINCOLN_HAS_STATE="true"
+
+# 3. Read current stage and node info
+STATE_JSON=$("$PYTHON" - "$STATE_FILE" <<'PY'
+import sys, yaml, json
+state = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+current = state.get("current_run", {}).get("current_stage") or "not_started"
+status = state.get("current_run", {}).get("status") or "not_started"
+workflow_name = state.get("workflow", {}).get("name") or "unknown"
+workflow_template = state.get("workflow", {}).get("template") or workflow_name
+nodes = state.get("nodes", [])
+last_node = nodes[-1] if nodes else {}
+waiting_for = last_node.get("status") if last_node else None
+if waiting_for in ("completed", "merged"):
+    waiting_for = "next_stage"
+variables = state.get("current_run", {}).get("variables", {})
+process_slug = variables.get("process_slug", "")
+if not process_slug and sys.argv[1].endswith("/workflow-stage.yaml"):
+    process_slug = __import__("pathlib").Path(sys.argv[1]).parent.name
+print(json.dumps({
+    "current_stage": current,
+    "status": status,
+    "workflow_name": workflow_name,
+    "workflow_template": workflow_template,
+    "last_node": last_node,
+    "waiting_for": waiting_for,
+    "session_id": variables.get("session_id", ""),
+    "design_id": variables.get("design_id", ""),
+    "process_slug": process_slug,
+}))
+PY
+)
+
+CURRENT_STAGE=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['current_stage'])")
+STATUS=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['status'])")
+WORKFLOW_NAME=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['workflow_name'])")
+WORKFLOW_TEMPLATE=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['workflow_template'])")
+LAST_NODE=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.dumps(json.load(sys.stdin)['last_node']))")
+WAITING_FOR=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['waiting_for'] or 'none')")
+SESSION_ID=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['session_id'])")
+DESIGN_ID=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['design_id'])")
+PROCESS_SLUG=$(echo "$STATE_JSON" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin)['process_slug'])")
+
+_LINCOLN_CURRENT_STAGE="$CURRENT_STAGE"
+_LINCOLN_STATUS="$STATUS"
+_LINCOLN_WORKFLOW_TEMPLATE="$WORKFLOW_TEMPLATE"
+_LINCOLN_PROCESS_SLUG="$PROCESS_SLUG"
+
+echo "Workflow: $WORKFLOW_NAME ($WORKFLOW_TEMPLATE)"
+echo "Process package: ${PROCESS_SLUG:-(unset)}"
+echo "State file: ${STATE_FILE#$ROOT/}"
+echo "Current stage: $CURRENT_STAGE"
+echo "Stage status: $STATUS"
+echo "Session ID: ${SESSION_ID:-(unset)}"
+echo "Design ID: ${DESIGN_ID:-(unset)}"
+echo "Waiting for: $WAITING_FOR"
+echo ""
+
+# 4. Load stage context, agent role, and workflow template (summaries only)
+if [[ "$CURRENT_STAGE" != "not_started" ]]; then
+    STAGE_YAML="$FRAMEWORK_ROOT/.claude/stages/$CURRENT_STAGE.yaml"
+    if [[ -f "$STAGE_YAML" ]]; then
+        echo "=== Lincoln Stage Context ==="
+        echo ""
+        echo "Stage YAML: ${STAGE_YAML#$FRAMEWORK_ROOT/}"
+        "$PYTHON" - "$STAGE_YAML" <<'PY'
+import sys, yaml
+data = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+ctx = data.get("context", {})
+goal = ctx.get("goal", "")
+if goal:
+    summary = goal.splitlines()[0]
+    print(f"Goal: {summary}")
+agent = data.get("agent", {}).get("primary", "")
+if agent:
+    print(f"Primary agent: {agent}")
+skills = data.get("skills", {})
+if isinstance(skills, dict):
+    skill_names = skills.get("required", []) + skills.get("optional", [])
+elif isinstance(skills, list):
+    skill_names = skills
+else:
+    skill_names = []
+if skill_names:
+    print(f"Skills: {', '.join(skill_names[:5])}{'...' if len(skill_names) > 5 else ''}")
+print("Use Read to inspect the full stage YAML if needed.")
+PY
+        echo ""
+        echo "=== End Lincoln Stage Context ==="
+        echo ""
+    fi
+
+    # Print agent file pointers instead of full text to keep session-start lean.
+    PRIMARY_AGENT=$("$PYTHON" - "$STAGE_YAML" <<'PY' 2>/dev/null || true
+import sys, yaml
+data = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+print(data.get("agent", {}).get("primary", ""))
+PY
+    )
+    # Stage YAML uses role IDs like lc-pm; agent files omit the lc- prefix.
+    AGENT_FILE="${PRIMARY_AGENT#lc-}.md"
+    if [[ -n "$PRIMARY_AGENT" && -f "$FRAMEWORK_ROOT/.claude/agents/$AGENT_FILE" ]]; then
+        echo "=== Agent Context ($PRIMARY_AGENT) ==="
+        echo "Agent file: .claude/agents/$AGENT_FILE"
+        echo "Default contract: .claude/agents/default.md"
+        echo "Behavioral contract: .claude/agents/_contract.md"
+        echo "Use Read to inspect the agent role if needed."
+        echo ""
+        echo "=== End Agent Context ==="
+        echo ""
+    fi
+
+    # Load workflow template summary
+    WORKFLOW_FILE="$FRAMEWORK_ROOT/.claude/workflows/${WORKFLOW_TEMPLATE}.yaml"
+    if [[ -f "$WORKFLOW_FILE" ]]; then
+        echo "=== Workflow Template ($WORKFLOW_TEMPLATE) ==="
+        echo "File: ${WORKFLOW_FILE#$FRAMEWORK_ROOT/}"
+        "$PYTHON" - "$WORKFLOW_FILE" <<'PY'
+import sys, yaml
+data = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+wf = data.get("workflow", data)
+print("Name:", wf.get("name", "unknown"))
+print("Description:", wf.get("description", ""))
+print("Steps:")
+for step in wf.get("steps", []):
+    print(f"  - {step.get('id', 'unknown')}: {step.get('name', '')}")
+PY
+        echo ""
+        echo "=== End Workflow Template ==="
+        echo ""
+    fi
+else
+    NEEDS_OPENING_GUIDANCE="true"
+fi
+
+# 5. Load Conductor / OMC context
+if [[ -d "$ROOT/.context" || -d "$ROOT/.omc" ]]; then
+    echo "=== Conductor / OMC Context ==="
+    for dir in "$ROOT/.context" "$ROOT/.omc"; do
+        if [[ -d "$dir" ]]; then
+            for f in $(find "$dir" -maxdepth 2 -type f \( -name '*.md' -o -name '*.yaml' -o -name '*.json' -o -name '*.txt' \) 2>/dev/null | sort); do
+                size=$(stat -f%z "$f" 2>/dev/null || stat -c%s "$f" 2>/dev/null || echo 0)
+                if [[ "$size" -lt 8192 ]]; then
+                    echo ""
+                    echo "--- ${f#$ROOT/} ---"
+                    cat "$f"
+                else
+                    echo ""
+                    echo "--- ${f#$ROOT/} (too large to print: $size bytes) ---"
+                fi
+            done
+        fi
+    done
+    echo ""
+    echo "=== End Conductor / OMC Context ==="
+    echo ""
+fi
+
+# 6. Read last node handoff
+HANDOFF_FILE=""
+if [[ "$LAST_NODE" != "{}" ]]; then
+    HANDOFF_FILE=$(echo "$LAST_NODE" | "$PYTHON" -c "import sys,json; print(json.load(sys.stdin).get('handoff_file',''))" 2>/dev/null || echo "")
+fi
+
+if [[ -n "$HANDOFF_FILE" && -f "$ROOT/$HANDOFF_FILE" ]]; then
+    echo "=== Last Node Handoff ==="
+    cat "$ROOT/$HANDOFF_FILE"
+    echo ""
+    echo "=== End Handoff ==="
+    echo ""
+fi
+
+if [[ -n "$PROCESS_SLUG" && -d "$ROOT/$PROCESS_SLUG/handoffs" ]]; then
+    LATEST_HANDOFF=$(ls -t "$ROOT/$PROCESS_SLUG/handoffs"/*.md 2>/dev/null | head -1 || true)
+    if [[ -n "$LATEST_HANDOFF" ]]; then
+        echo "=== Latest Process Handoff ==="
+        cat "$LATEST_HANDOFF"
+        echo ""
+        echo "=== End Latest Process Handoff ==="
+        echo ""
+    fi
+fi
+
+# 7. Run status summary
+STATUS_OUTPUT=$("$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln-status.py" --format markdown --state-file "$STATE_FILE" 2>/dev/null) || STATUS_OUTPUT=""
+if [[ -n "$STATUS_OUTPUT" ]]; then
+    echo "=== Lincoln Status Summary ==="
+    echo "$STATUS_OUTPUT"
+    echo "=== End Lincoln Status Summary ==="
+    echo ""
+fi
+
+# 8. Opening guidance for a work package that has not started yet
+if [[ "${NEEDS_OPENING_GUIDANCE:-}" == "true" ]]; then
+    _LINCOLN_GUIDANCE_INJECTED="true"
+    echo "=== Lincoln 开场引导 ==="
+    echo ""
+    echo "工作包已就绪但尚未启动（current_stage: not_started）。请先完成 .claude/skills/lc-workflow-router/prompts/intake-prompt.md 中的确认流程，再运行 validate-entry 进入第一阶段。"
+    echo ""
+    echo "=== End Lincoln 开场引导 ==="
+    echo ""
+fi
+
+echo "=== End Lincoln Session Start ==="
+echo ""
+
+emit_session_start_json
+
+# Quantify the session-start token cost and make it available to benchmark reports (#63).
+if [[ -n "$PROCESS_SLUG" && -f "$HOOK_OUTPUT_CAPTURE" ]]; then
+    METRICS_DIR="$ROOT/$PROCESS_SLUG/.trace"
+    mkdir -p "$METRICS_DIR"
+    "$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln_session_start_metrics.py" \
+        --input "$HOOK_OUTPUT_CAPTURE" \
+        --output "$METRICS_DIR/session-start-metrics.json" \
+        --stage "$CURRENT_STAGE" \
+        --status "$STATUS" >/dev/null 2>&1 || true
+fi
+
+exit 0

package/framework/.claude/hooks/on-stop.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# On-stop hook for Lincoln workflow.
+# Updates last_updated_at in the workflow stage file when a session ends.
+#
+# The operational state file is branch-scoped: <process_slug>/workflow-stage.yaml
+# (falls back to legacy .claude/workflow-state.yaml if present).
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOCAL_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT_ROOT="$(pwd)"
+
+FRAMEWORK_ROOT="${CLAUDE_PLUGIN_ROOT:-${LINCOLN_HOME:-}}"
+if [[ -z "$FRAMEWORK_ROOT" ]]; then
+  # If this hook file lives inside a vendored project framework, prefer that.
+  if [[ "$SCRIPT_DIR" == "$LOCAL_ROOT/.claude/hooks"* && -d "$LOCAL_ROOT/.claude/stages" ]]; then
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  elif [[ -d "$HOME/.lincoln/current" ]]; then
+    FRAMEWORK_ROOT="$HOME/.lincoln/current"
+  else
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  fi
+fi
+
+if [[ "$FRAMEWORK_ROOT" != "$LOCAL_ROOT" ]]; then
+  MARKER_FOUND="false"
+  SEARCH_DIR="$PROJECT_ROOT"
+  while [[ "$SEARCH_DIR" != "/" ]]; do
+    if [[ -f "$SEARCH_DIR/.lincoln.yaml" || -f "$SEARCH_DIR/.claude/workflow-state.yaml" ]]; then
+      MARKER_FOUND="true"
+      break
+    fi
+    SEARCH_DIR="$(dirname "$SEARCH_DIR")"
+  done
+  if [[ "$MARKER_FOUND" != "true" && -z "${LINCOLN_ALWAYS_ON:-}" ]]; then
+    echo "Lincoln inactive: no .lincoln.yaml in $PROJECT_ROOT"
+    exit 0
+  fi
+fi
+
+ROOT="$PROJECT_ROOT"
+
+if [ -x "$FRAMEWORK_ROOT/.venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/.venv/bin/python3"
+elif [ -x "$FRAMEWORK_ROOT/venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/venv/bin/python3"
+elif [ -x "$HOME/.lincoln/venv/bin/python3" ]; then
+    PYTHON="$HOME/.lincoln/venv/bin/python3"
+else
+    PYTHON="python3"
+fi
+
+STATE_FILE=$("$PYTHON" - "$FRAMEWORK_ROOT" "$ROOT" "${LINCOLN_STATE_FILE:-}" <<'PY'
+import sys
+from pathlib import Path
+framework_root = Path(sys.argv[1])
+project_root = Path(sys.argv[2])
+provided = sys.argv[3]
+sys.path.insert(0, str(framework_root))
+from scripts.lincoln_paths import resolve_state_path
+path = Path(provided) if provided else None
+print(resolve_state_path(path, project_root))
+PY
+)
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    exit 0
+fi
+
+# Update last_updated_at through the canonical state mutation layer.
+"$PYTHON" "$FRAMEWORK_ROOT/scripts/stage_loader.py" \
+    --state-file "$STATE_FILE" \
+    --action update-last-updated \
+    2>/dev/null || true
+
+CURRENT_STAGE=$("$PYTHON" - "$STATE_FILE" <<'PY' 2>/dev/null
+import sys, yaml
+state = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+print(state.get("current_run", {}).get("current_stage") or "")
+PY
+) || CURRENT_STAGE=""
+
+STAGE_STATUS=$("$PYTHON" - "$STATE_FILE" <<'PY' 2>/dev/null
+import sys, yaml
+state = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+stage = state.get("current_run", {}).get("current_stage")
+nodes = [n for n in state.get("nodes", []) if n.get("stage_id") == stage]
+if nodes:
+    print(nodes[-1].get("status") or state.get("current_run", {}).get("status") or "")
+else:
+    print(state.get("current_run", {}).get("status") or "")
+PY
+) || STAGE_STATUS=""
+
+if [[ -n "$CURRENT_STAGE" && ( "$STAGE_STATUS" == "waiting_for_human" || "$STAGE_STATUS" == "validation_failed" ) ]]; then
+    "$PYTHON" "$FRAMEWORK_ROOT/scripts/stage_loader.py" \
+        --state-file "$STATE_FILE" \
+        --stage "$CURRENT_STAGE" \
+        --action handoff-report \
+        >/dev/null 2>&1 || true
+fi
+
+exit 0

package/framework/.claude/hooks/post-tool-use.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PostToolUse hook for Lincoln workflow.
+# Tracks artifacts produced by side-effect tools and detects PR/branch sync events.
+#
+# Usage (manual):
+#   .claude/hooks/post-tool-use.sh "Write" '{"file_path": "foo.md"}' 0
+#
+# Expected arguments:
+#   $1: tool name
+#   $2: JSON-encoded tool arguments
+#   $3: tool exit code
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LOCAL_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PROJECT_ROOT="$(pwd)"
+
+FRAMEWORK_ROOT="${CLAUDE_PLUGIN_ROOT:-${LINCOLN_HOME:-}}"
+if [[ -z "$FRAMEWORK_ROOT" ]]; then
+  # If this hook file lives inside a vendored project framework, prefer that.
+  if [[ "$SCRIPT_DIR" == "$LOCAL_ROOT/.claude/hooks"* && -d "$LOCAL_ROOT/.claude/stages" ]]; then
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  elif [[ -d "$HOME/.lincoln/current" ]]; then
+    FRAMEWORK_ROOT="$HOME/.lincoln/current"
+  else
+    FRAMEWORK_ROOT="$LOCAL_ROOT"
+  fi
+fi
+
+if [[ "$FRAMEWORK_ROOT" != "$LOCAL_ROOT" ]]; then
+  MARKER_FOUND="false"
+  SEARCH_DIR="$PROJECT_ROOT"
+  while [[ "$SEARCH_DIR" != "/" ]]; do
+    if [[ -f "$SEARCH_DIR/.lincoln.yaml" || -f "$SEARCH_DIR/.claude/workflow-state.yaml" ]]; then
+      MARKER_FOUND="true"
+      break
+    fi
+    SEARCH_DIR="$(dirname "$SEARCH_DIR")"
+  done
+  if [[ "$MARKER_FOUND" != "true" && -z "${LINCOLN_ALWAYS_ON:-}" ]]; then
+    echo "Lincoln inactive: no .lincoln.yaml in $PROJECT_ROOT"
+    exit 0
+  fi
+fi
+
+ROOT="$PROJECT_ROOT"
+
+mkdir -p "$ROOT/.context"
+
+if [ -x "$FRAMEWORK_ROOT/.venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/.venv/bin/python3"
+elif [ -x "$FRAMEWORK_ROOT/venv/bin/python3" ]; then
+    PYTHON="$FRAMEWORK_ROOT/venv/bin/python3"
+elif [ -x "$HOME/.lincoln/venv/bin/python3" ]; then
+    PYTHON="$HOME/.lincoln/venv/bin/python3"
+else
+    PYTHON="python3"
+fi
+
+TOOL_NAME="${1:-}"
+TOOL_ARGS="${2:-}"
+EXIT_CODE="${3:-0}"
+STATE_FILE=$("$PYTHON" - "$FRAMEWORK_ROOT" "$ROOT" "${LINCOLN_STATE_FILE:-}" <<'PY'
+import sys
+from pathlib import Path
+framework_root = Path(sys.argv[1])
+project_root = Path(sys.argv[2])
+provided = sys.argv[3]
+sys.path.insert(0, str(framework_root))
+from scripts.lincoln_paths import resolve_state_path
+path = Path(provided) if provided else None
+print(resolve_state_path(path, project_root))
+PY
+)
+
+if [[ ! -f "$STATE_FILE" ]]; then
+    exit 0
+fi
+
+# Trace logging: record (nearly) every tool invocation to the session trace.
+# This runs before the early success-only exit so failures are captured too.
+# Skip no-op/recursive tools and any call already flagged with LINCOLN_SKIP_TRACE=1.
+if [[ "${LINCOLN_SKIP_TRACE:-}" != "1" ]]; then
+    if [[ "$TOOL_NAME" != "Read" && "$TOOL_NAME" != "Grep" && "$TOOL_NAME" != "Glob" ]]; then
+        LINCOLN_SKIP_TRACE=1 "$PYTHON" "$FRAMEWORK_ROOT/scripts/lincoln_trace.py" \
+            --state-file "$STATE_FILE" \
+            --tool "$TOOL_NAME" \
+            --args-json "$TOOL_ARGS" \
+            --exit-code "$EXIT_CODE" \
+            2>>"$ROOT/.context/lc-trace-errors.log" || true
+    fi
+fi
+
+# Only track successful side-effect tool uses
+if [[ "$EXIT_CODE" != "0" ]]; then
+    exit 0
+fi
+
+SIDE_EFFECT_TOOLS=(
+    "Bash"
+    "Edit"
+    "Write"
+    "mcp__pencil__batch_design"
+    "mcp__pencil__export_nodes"
+    "mcp__pencil__export_html"
+    "mcp__plugin_ecc_github__create_pull_request"
+    "mcp__plugin_ecc_github__merge_pull_request"
+)
+
+is_side_effect() {
+    local tool="$1"
+    for t in "${SIDE_EFFECT_TOOLS[@]}"; do
+        if [[ "$tool" == "$t" ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+if is_side_effect "$TOOL_NAME"; then
+    "$PYTHON" "$FRAMEWORK_ROOT/scripts/track-artifacts.py" \
+        --state-file "$STATE_FILE" \
+        --tool "$TOOL_NAME" \
+        --args "$TOOL_ARGS" \
+        --project-root "$ROOT" \
+        2>/dev/null || true
+fi
+
+# Determine the current stage so PR lifecycle nodes are attached to the stage
+# that actually produced the PR, instead of hardcoding "implement".
+CURRENT_STAGE=$("$PYTHON" - "$STATE_FILE" <<'PY' 2>/dev/null
+import sys, yaml
+state = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+print(state.get("current_run", {}).get("current_stage") or "implement")
+PY
+) || CURRENT_STAGE="implement"
+
+# Detect PR/branch sync events, append a node record, and queue the matching
+# benchmark trigger in a single mapping to avoid duplicated logic.
+BENCHMARK_TRIGGER=""
+EVENT_STATUS=""
+if [[ "$TOOL_NAME" == "mcp__plugin_ecc_github__create_pull_request" ]]; then
+    BENCHMARK_TRIGGER="pr_created"
+    EVENT_STATUS="pr_submitted"
+elif [[ "$TOOL_NAME" == "mcp__plugin_ecc_github__merge_pull_request" ]]; then
+    BENCHMARK_TRIGGER="pr_merged"
+    EVENT_STATUS="merged"
+fi
+
+if [[ -n "$BENCHMARK_TRIGGER" ]]; then
+    EVENT_NODE="${CURRENT_STAGE:-implement}"
+    "$PYTHON" "$FRAMEWORK_ROOT/scripts/stage_loader.py" \
+        --state-file "$STATE_FILE" \
+        --action append-node \
+        --node-id "$EVENT_NODE" \
+        --status "$EVENT_STATUS" \
+        2>/dev/null || true
+fi
+
+exit 0