@sushanglewis/lincoln 1.5.0 → 1.5.2

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

@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# PreToolUse hook for Lincoln workflow.
+# Blocks side-effect tools when the current stage has not passed entry checks
+# or is paused/waiting_for_human/validation_failed.
+#
+# Usage (manual):
+#   .claude/hooks/pre-tool-use.sh "Write" '{"file_path": "foo.md"}'
+#
+# Expected arguments:
+#   $1: tool name (e.g. Bash, Write, Edit, mcp__pencil__batch_design)
+#   $2: JSON-encoded tool arguments
+
+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
+
+TOOL_NAME="${1:-}"
+TOOL_ARGS="${2:-}"
+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 state file does not exist, allow everything (not a Lincoln project or not initialized)
+if [[ ! -f "$STATE_FILE" ]]; then
+    exit 0
+fi
+
+# Read current stage and status using Python for reliable YAML parsing
+read_state() {
+    "$PYTHON" - "$STATE_FILE" <<'PY'
+import sys
+import yaml
+path = sys.argv[1]
+state = yaml.safe_load(open(path, encoding="utf-8"))
+current = state.get("current_run", {}).get("current_stage") or "not_started"
+# New schema: derive status from the latest node for the current stage; legacy schema: from stages map.
+nodes = state.get("nodes", [])
+matching = [n for n in nodes if n.get("stage_id") == current]
+if matching:
+    stage_state = matching[-1]
+elif "stages" in state and current in state["stages"]:
+    stage_state = state["stages"][current]
+else:
+    stage_state = {}
+status = stage_state.get("status") or state.get("current_run", {}).get("status") or "not_started"
+print(current)
+print(status)
+PY
+}
+
+STATE_OUTPUT=$(read_state)
+CURRENT_STAGE=$(echo "$STATE_OUTPUT" | sed -n '1p')
+STAGE_STATUS=$(echo "$STATE_OUTPUT" | sed -n '2p')
+PROCESS_SLUG=$("$PYTHON" - "$FRAMEWORK_ROOT" "$ROOT" "$STATE_FILE" <<'PY'
+import sys, yaml
+from pathlib import Path
+framework_root = Path(sys.argv[1])
+project_root = Path(sys.argv[2])
+state_file = Path(sys.argv[3])
+sys.path.insert(0, str(framework_root))
+from scripts.lincoln_paths import get_process_slug
+state = yaml.safe_load(open(state_file, encoding="utf-8"))
+print(get_process_slug(state, state_file))
+PY
+)
+
+TARGET_PATH=$("$PYTHON" - "$TOOL_ARGS" <<'PY'
+import json, sys
+try:
+    data = json.loads(sys.argv[1] or "{}")
+except Exception:
+    data = {}
+print(data.get("file_path") or data.get("path") or "")
+PY
+)
+
+# Task-tool guard: prevent TaskCreate/TaskUpdate from being used as
+# placeholders for user messages in dialogue stages, and cap consecutive
+# task-tool calls everywhere else.  This is invoked for every tool so it can
+# reset the burst counter on non-task actions.
+"$PYTHON" "$FRAMEWORK_ROOT/scripts/task_tool_guard.py" \
+    --state-file "$STATE_FILE" \
+    --tool-name "$TOOL_NAME" \
+    --tool-args "$TOOL_ARGS"
+
+# Define side-effect tools
+SIDE_EFFECT_TOOLS=(
+    "Bash"
+    "Edit"
+    "Write"
+    "NotebookEdit"
+    "mcp__pencil__batch_design"
+    "mcp__pencil__export_nodes"
+    "mcp__pencil__export_html"
+    "mcp__plugin_ecc_github__create_issue"
+    "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
+}
+
+is_plain_file_tool() {
+    case "$1" in
+        Read|Write|Edit|NotebookEdit)
+            return 0
+            ;;
+    esac
+    return 1
+}
+
+if [[ -n "$TARGET_PATH" ]]; then
+    NORMALIZED_TARGET="${TARGET_PATH#$ROOT/}"
+
+    if [[ "$NORMALIZED_TARGET" == *.pen ]] && is_plain_file_tool "$TOOL_NAME"; then
+        echo "BLOCKED: .pen files must be handled through Pencil tools, not $TOOL_NAME." >&2
+        exit 1
+    fi
+
+    if [[ "$NORMALIZED_TARGET" == "$PROCESS_SLUG/prd-v"*.md ]] && is_side_effect "$TOOL_NAME"; then
+        echo "BLOCKED: PRD snapshots are immutable. Create them with 'python scripts/lincoln_prd.py freeze'." >&2
+        exit 1
+    fi
+
+    if [[ "$NORMALIZED_TARGET" == "$PROCESS_SLUG/workflow-stage.yaml" ]] && is_side_effect "$TOOL_NAME"; then
+        echo "BLOCKED: workflow state must be updated through stage_loader, not $TOOL_NAME." >&2
+        exit 1
+    fi
+
+    if [[ "$NORMALIZED_TARGET" == "$PROCESS_SLUG/recordings/"* ]] && is_side_effect "$TOOL_NAME"; then
+        echo "BLOCKED: recordings are read-only process inputs." >&2
+        exit 1
+    fi
+
+    if is_side_effect "$TOOL_NAME"; then
+        if [[ -n "$PROCESS_SLUG" ]]; then
+            case "$NORMALIZED_TARGET" in
+                recordings/*|*/recordings/*|interviews/*|*/interviews/*|requirements/*|*/requirements/*|designs/*|*/designs/*|openspec/changes/*|*/openspec/changes/*|docs/research/*|*/docs/research/*)
+                    if [[ "$NORMALIZED_TARGET" != "$PROCESS_SLUG/"* ]]; then
+                        echo "BLOCKED: process artifacts must be written under '$PROCESS_SLUG/'." >&2
+                        exit 1
+                    fi
+                    ;;
+            esac
+        else
+            case "$NORMALIZED_TARGET" in
+                recordings/*|*/recordings/*|interviews/*|*/interviews/*|requirements/*|*/requirements/*|designs/*|*/designs/*|openspec/changes/*|*/openspec/changes/*|docs/research/*|*/docs/research/*)
+                    echo "BLOCKED: process artifacts must be written under an initialized <process_slug>/." >&2
+                    exit 1
+                    ;;
+            esac
+        fi
+    fi
+fi
+
+# Block side-effect tools when entry checks have not passed
+if [[ "$STAGE_STATUS" == "not_started" || "$STAGE_STATUS" == "entry_validating" ]]; then
+    if is_side_effect "$TOOL_NAME"; then
+        echo "BLOCKED: Entry checks for stage '$CURRENT_STAGE' have not passed yet." >&2
+        echo "Run: python scripts/stage_loader.py --stage $CURRENT_STAGE --action validate-entry" >&2
+        exit 1
+    fi
+fi
+
+# When paused/waiting_for_human/validation_failed, only allow read-only tools
+if [[ "$STAGE_STATUS" == "paused" || "$STAGE_STATUS" == "waiting_for_human" || "$STAGE_STATUS" == "validation_failed" ]]; then
+    if [[ "$TOOL_NAME" != "Read" && "$TOOL_NAME" != "Grep" && "$TOOL_NAME" != "Glob" ]]; then
+        echo "BLOCKED: Stage '$CURRENT_STAGE' is $STAGE_STATUS. Only Read/Grep/Glob allowed." >&2
+        echo "To resume: run the stage's skill command or call workflow-continue." >&2
+        exit 1
+    fi
+fi
+
+# Exit gate check: block side-effect tools that would advance to the next stage
+# if the current stage's exit gate has not been approved.
+if is_side_effect "$TOOL_NAME"; then
+    GATE_STATUS=$("$PYTHON" "$FRAMEWORK_ROOT/scripts/stage_loader.py" \
+        --stage "$CURRENT_STAGE" \
+        --action validate-exit \
+        2>/dev/null | grep -c "^PASS:" || echo "0")
+    # For now, only warn rather than block to avoid breaking legitimate edits.
+    if [[ "$GATE_STATUS" == "0" && "$TOOL_NAME" != "Read" ]]; then
+        echo "[Lincoln] Warning: exit gate for '$CURRENT_STAGE' is not yet approved." >&2
+        echo "[Lincoln] Run 'python scripts/stage_loader.py --stage $CURRENT_STAGE --action validate-exit' to check." >&2
+    fi
+fi
+
+exit 0

package/framework/.claude/schemas/agent-definition.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lincoln-framework.dev/schemas/agent-definition.schema.json",
+  "title": "Lincoln Agent Definition Schema",
+  "description": "Validates agent markdown files under .claude/agents/.",
+  "type": "object",
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique agent identifier"
+    },
+    "description": {
+      "type": "string",
+      "description": "Short description of the agent's role"
+    },
+    "extends": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of agent files this agent extends"
+    },
+    "model": {
+      "type": "string",
+      "enum": ["haiku", "sonnet", "opus"]
+    },
+    "tools": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "disallowed_tools": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/framework/.claude/schemas/benchmark-report.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://lincoln-framework.dev/schemas/benchmark-report.schema.json",
+  "title": "Lincoln Benchmark Report",
+  "description": "Schema for a Lincoln benchmark report generated from session trace and workflow state.",
+  "type": "object",
+  "required": [
+    "report_id",
+    "schema_version",
+    "scenario",
+    "trigger",
+    "generated_at",
+    "metadata",
+    "metrics",
+    "confidence",
+    "evaluation"
+  ],
+  "properties": {
+    "report_id": {
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "scenario": {
+      "type": "string",
+      "enum": ["S1", "S2", "S3", "S4", "S5"]
+    },
+    "trigger": {
+      "type": "string",
+      "enum": ["handoff", "pr_created", "pr_merged", "session_stop", "manual"]
+    },
+    "generated_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "metadata": {
+      "type": "object",
+      "required": ["process_slug", "run_id", "branch", "issue_number", "current_stage", "workflow_template"],
+      "properties": {
+        "process_slug": { "type": "string" },
+        "run_id": { "type": "string" },
+        "branch": { "type": "string" },
+        "issue_number": { "type": "string" },
+        "linear_id": { "type": "string" },
+        "current_stage": { "type": "string" },
+        "trace_files": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "workflow_template": { "type": "string" }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["session", "workflow", "collaboration", "quality", "outcome"],
+      "properties": {
+        "session": {
+          "type": "object",
+          "properties": {
+            "session_duration_seconds": { "type": "integer" },
+            "trace_line_count": { "type": "integer" },
+            "total_tool_calls": { "type": "integer" },
+            "tool_calls_by_category": { "type": "object" },
+            "unique_skills": { "type": "array", "items": { "type": "string" } },
+            "unique_files_touched": { "type": "integer" },
+            "test_runs": { "type": "integer" },
+            "error_count": { "type": "integer" },
+            "retry_count": { "type": "integer" }
+          }
+        },
+        "workflow": {
+          "type": "object",
+          "properties": {
+            "stage_transition_count": { "type": "integer" },
+            "stage_durations": { "type": "object" },
+            "stage_completion_rate": { "type": "number" },
+            "stage_rework_count": { "type": "integer" },
+            "artifact_completion_rate": { "type": "number" },
+            "validation_failure_count": { "type": "integer" },
+            "workflow_adherence_score": { "type": "number" },
+            "human_gate_count": { "type": "integer" },
+            "human_gate_wait_seconds": { "type": "integer" },
+            "human_gate_pass_rate": { "type": "number" },
+            "build_codebase_knowledge_duration_seconds": { "type": "integer" }
+          }
+        },
+        "collaboration": {
+          "type": "object",
+          "properties": {
+            "handoff_count": { "type": "integer" },
+            "agent_switches": { "type": "integer" },
+            "pm_turns": { "type": "integer" },
+            "time_to_first_handoff": { "type": "integer" }
+          }
+        },
+        "quality": {
+          "type": "object",
+          "properties": {
+            "requirements_clarity_score": { "type": "integer" },
+            "design_doc_completeness": { "type": "number" },
+            "tdd_plan_red_green_refactor": { "type": "object" },
+            "openspec_task_count": { "type": "integer" },
+            "static_check_pass": { "type": ["boolean", "null"] },
+            "test_coverage": { "type": ["number", "null"] },
+            "pr_size": { "type": "integer" },
+            "audit_score": { "type": ["object", "null"] },
+            "code_review_calls": { "type": "integer" }
+          }
+        },
+        "outcome": {
+          "type": "object",
+          "properties": {
+            "issue_closed": { "type": ["boolean", "null"] },
+            "pr_merged": { "type": ["boolean", "null"] },
+            "pr_merge_latency_seconds": { "type": "integer" },
+            "knowledge_synced": { "type": ["boolean", "null"] },
+            "time_to_pr_seconds": { "type": "integer" },
+            "time_to_merge_seconds": { "type": "integer" },
+            "unique_files_touched_ratio": { "type": "number" }
+          }
+        }
+      }
+    },
+    "confidence": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["exact", "estimated", "pending"]
+      }
+    },
+    "evaluation": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "value": {},
+          "threshold": {},
+          "status": {
+            "type": "string",
+            "enum": ["green", "yellow", "red", "unknown"]
+          }
+        }
+      }
+    }
+  }
+}

package/framework/.claude/schemas/pm-to-ux-handoff.schema.yaml

@@ -0,0 +1,128 @@
+$schema: "http://json-schema.org/draft-07/schema#"
+title: PM-to-UX Handoff Contract
+description: |
+  Machine-readable contract for PM→UX handoff in Lincoln issue packages.
+  UX Agents must read this file first, then the human master doc, then the ordered context pack.
+type: object
+required:
+  - contract_version
+  - issue_number
+  - feature_slug
+  - from_stage
+  - to_stage
+  - from_agent
+  - to_agent
+  - handoff_type
+  - human_master_doc
+  - based_on
+  - context_pack
+  - reading_rules
+  - open_questions
+  - approval
+properties:
+  contract_version:
+    type: string
+    pattern: "^\\d+\\.\\d+\\.\\d+$"
+    description: Schema version of this contract file.
+  issue_number:
+    type: string
+    description: GitHub issue number.
+  feature_slug:
+    type: string
+    description: Feature/design slug used in the issue package.
+  from_stage:
+    type: string
+    enum: ["clarify", "product-design-docs"]
+  to_stage:
+    type: string
+    enum: ["product-design-docs", "product-prototype"]
+  from_agent:
+    type: string
+  to_agent:
+    type: string
+  handoff_type:
+    type: string
+    enum: ["pm-to-ux"]
+  human_master_doc:
+    type: object
+    required: [path, version]
+    properties:
+      path:
+        type: string
+      version:
+        type: string
+        pattern: "^v\\d+\\.\\d+$"
+  based_on:
+    type: array
+    items:
+      type: object
+      required: [path, version]
+      properties:
+        path:
+          type: string
+        version:
+          type: string
+          pattern: "^v\\d+\\.\\d+$"
+  context_pack:
+    type: object
+    required: [tier_0, tier_1, tier_2]
+    properties:
+      tier_0:
+        type: array
+        items:
+          type: object
+          required: [path, reason]
+          properties:
+            path: { type: string }
+            reason: { type: string }
+      tier_1:
+        type: array
+        items:
+          type: object
+          required: [path, reason]
+          properties:
+            path: { type: string }
+            reason: { type: string }
+      tier_2:
+        type: array
+        items:
+          type: object
+          required: [feature, links]
+          properties:
+            feature: { type: string }
+            links:
+              type: array
+              items:
+                type: object
+                required: [path, reason]
+                properties:
+                  path: { type: string }
+                  reason: { type: string }
+  reading_rules:
+    type: array
+    items:
+      type: string
+  open_questions:
+    type: array
+    items:
+      type: object
+      required: [id, question, owner, status]
+      properties:
+        id: { type: string }
+        question: { type: string }
+        owner: { type: string }
+        status:
+          type: string
+          enum: ["open", "resolved", "deferred"]
+  approval:
+    type: object
+    required: [pm_confirmed]
+    properties:
+      pm_confirmed:
+        type: boolean
+      approved_at:
+        type: string
+      approved_by:
+        type: string
+  notes:
+    type: string