@sushanglewis/lincoln 1.5.0 → 1.5.1

package/framework/scripts/sync-framework-package.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Sync Lincoln framework runtime payload into packages/lincoln/framework/.
+ *
+ * This script mirrors the allowlist used by scripts/package-lincoln-plugin.py
+ * so the npm package can bundle the same files that the release tarball uses.
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const ROOT = path.resolve(path.dirname(__filename), '..')
+const PAYLOAD_DIR = path.join(ROOT, 'packages', 'lincoln', 'framework')
+const VERSION_FILE = path.join(ROOT, '.version-bump.json')
+
+const ALLOWLIST_DIRS = ['.claude', '.claude-plugin', 'scripts', 'tools']
+const ALLOWLIST_FILES = [
+  'README.md',
+  'README.en.md',
+  'USAGE.md',
+  'CONTRIBUTING.md',
+  'CLAUDE.md',
+  'LICENSE',
+  'RELEASE.md',
+  '.version-bump.json',
+  'requirements.txt',
+  'SKILL.md'
+]
+
+const DENYLIST_NAMES = new Set([
+  '.git',
+  '.context',
+  '.venv',
+  'venv',
+  'oss',
+  '.pytest_cache',
+  '__pycache__',
+  '.DS_Store',
+  'node_modules'
+])
+const DENYLIST_PREFIXES = ['issue-']
+const SKIP_PATHS = new Set([
+  '.claude/templates/issue-package',
+  'tools/lincoln-installer/dist',
+  'tools/lincoln-installer/node_modules',
+  'tools/lincoln-installer/coverage'
+])
+
+async function loadVersion() {
+  const raw = await fs.readFile(VERSION_FILE, 'utf8')
+  const data = JSON.parse(raw)
+  if (typeof data.version !== 'string') {
+    throw new Error('.version-bump.json missing version string')
+  }
+  return data.version
+}
+
+function isDenied(relativePath) {
+  const parts = relativePath.split(path.sep)
+  for (const part of parts) {
+    if (DENYLIST_NAMES.has(part)) return true
+    for (const prefix of DENYLIST_PREFIXES) {
+      if (part.startsWith(prefix)) return true
+    }
+  }
+  for (const skip of SKIP_PATHS) {
+    if (relativePath === skip || relativePath.startsWith(skip + path.sep)) {
+      return true
+    }
+  }
+  return false
+}
+
+async function* walk(dir, baseDir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true })
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name)
+    const relativePath = path.relative(baseDir, fullPath)
+    if (isDenied(relativePath)) continue
+    if (entry.isDirectory()) {
+      yield* walk(fullPath, baseDir)
+    } else if (entry.isFile()) {
+      yield { fullPath, relativePath }
+    }
+  }
+}
+
+async function sha256(filePath) {
+  const data = await fs.readFile(filePath)
+  return crypto.createHash('sha256').update(data).digest('hex')
+}
+
+async function syncPayload(version) {
+  await fs.rm(PAYLOAD_DIR, { recursive: true, force: true })
+  await fs.mkdir(PAYLOAD_DIR, { recursive: true })
+
+  const copied = []
+
+  for (const dir of ALLOWLIST_DIRS) {
+    const src = path.join(ROOT, dir)
+    try {
+      await fs.access(src)
+    } catch {
+      continue
+    }
+
+    for await (const { fullPath, relativePath } of walk(src, ROOT)) {
+      const dest = path.join(PAYLOAD_DIR, relativePath)
+      await fs.mkdir(path.dirname(dest), { recursive: true })
+      await fs.copyFile(fullPath, dest)
+      copied.push(relativePath)
+    }
+  }
+
+  for (const file of ALLOWLIST_FILES) {
+    const src = path.join(ROOT, file)
+    try {
+      await fs.access(src)
+    } catch {
+      continue
+    }
+    const dest = path.join(PAYLOAD_DIR, file)
+    await fs.mkdir(path.dirname(dest), { recursive: true })
+    await fs.copyFile(src, dest)
+    copied.push(file)
+  }
+
+  copied.sort()
+
+  const manifestFiles = []
+  for (const relativePath of copied) {
+    const filePath = path.join(PAYLOAD_DIR, relativePath)
+    manifestFiles.push({
+      path: relativePath,
+      sha256: await sha256(filePath)
+    })
+  }
+
+  const manifest = {
+    version,
+    generatedAt: new Date().toISOString(),
+    files: manifestFiles
+  }
+
+  await fs.writeFile(
+    path.join(PAYLOAD_DIR, 'manifest.json'),
+    JSON.stringify(manifest, null, 2) + '\n'
+  )
+
+  return copied
+}
+
+async function checkPayload(version) {
+  try {
+    await fs.access(PAYLOAD_DIR)
+  } catch {
+    return { ok: false, reason: 'framework payload directory missing' }
+  }
+
+  const manifestPath = path.join(PAYLOAD_DIR, 'manifest.json')
+  let manifest
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8')
+    manifest = JSON.parse(raw)
+  } catch {
+    return { ok: false, reason: 'manifest.json missing or unreadable' }
+  }
+
+  if (manifest.version !== version) {
+    return { ok: false, reason: `version mismatch: ${manifest.version} != ${version}` }
+  }
+
+  for (const entry of manifest.files) {
+    const filePath = path.join(PAYLOAD_DIR, entry.path)
+    try {
+      const actual = await sha256(filePath)
+      if (actual !== entry.sha256) {
+        return { ok: false, reason: `checksum mismatch: ${entry.path}` }
+      }
+    } catch {
+      return { ok: false, reason: `missing file: ${entry.path}` }
+    }
+  }
+
+  return { ok: true }
+}
+
+async function main() {
+  const args = process.argv.slice(2)
+  const version = await loadVersion()
+
+  if (args.includes('--dump-allowlist')) {
+    console.log(JSON.stringify({ dirs: ALLOWLIST_DIRS, files: ALLOWLIST_FILES }, null, 2))
+    return 0
+  }
+
+  if (args.includes('--check')) {
+    const result = await checkPayload(version)
+    if (result.ok) {
+      console.log(`framework payload up to date (${version})`)
+      return 0
+    }
+    console.error(`framework payload out of sync: ${result.reason}`)
+    return 1
+  }
+
+  const copied = await syncPayload(version)
+  console.log(`synced ${copied.length} files to ${PAYLOAD_DIR} (${version})`)
+  return 0
+}
+
+main().then((code) => process.exit(code)).catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/framework/scripts/task_tool_guard.py

@@ -0,0 +1,213 @@
+#!/usr/bin/env python3
+"""
+Task-tool guard for the Lincoln workflow.
+
+Prevents the agent from using TaskCreate/TaskUpdate as placeholders for
+"I will send a user message soon" in dialogue stages, and limits consecutive
+task-tool calls everywhere else so a runaway loop cannot accumulate hundreds
+of task artifacts without a non-task action in between.
+
+Intended to be invoked from .claude/hooks/pre-tool-use.sh for every tool call.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+try:
+    from scripts.lincoln_paths import resolve_state_path
+except Exception:  # pragma: no cover - standalone fallback
+    resolve_state_path = None  # type: ignore[assignment]
+
+# Stages where the agent is expected to talk to the PM, not to manage a task
+# list.  We default this from the workflow YAML (human_gate: true), but allow
+# an override for tests.
+DIALOGUE_STAGE_FALLBACK: frozenset[str] = frozenset(
+    {"clarify", "product-design-docs", "product-prototype", "implement"}
+)
+
+TASK_TOOLS: frozenset[str] = frozenset({"TaskCreate", "TaskUpdate"})
+
+DEFAULT_MAX_CONSECUTIVE = 3
+
+
+def load_yaml(path: Path) -> Any:
+    if not path.exists():
+        raise FileNotFoundError(path)
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def load_state(state_file: Path) -> dict[str, Any] | None:
+    if not state_file.exists():
+        return None
+    data = load_yaml(state_file)
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def resolve_project_root(state_file: Path) -> Path | None:
+    """Derive project root from <root>/.claude/workflow-state.yaml."""
+    resolved = state_file.resolve()
+    if len(resolved.parents) < 2:
+        return None
+    return resolved.parents[1]
+
+
+def dialogue_stages(workflow_file: Path | None, override: set[str] | None) -> set[str]:
+    if override is not None:
+        return override
+    if workflow_file is None or not workflow_file.exists():
+        return set(DIALOGUE_STAGE_FALLBACK)
+    try:
+        data = load_yaml(workflow_file)
+        workflow = data.get("workflow", data) if isinstance(data, dict) else {}
+        return {
+            step["id"]
+            for step in workflow.get("steps", [])
+            if isinstance(step, dict) and step.get("human_gate")
+        }
+    except (yaml.YAMLError, AttributeError, KeyError, TypeError):
+        return set(DIALOGUE_STAGE_FALLBACK)
+
+
+def counter_file_path(state_file: Path) -> Path:
+    root = resolve_project_root(state_file)
+    if root is None:
+        # Unusual path depth; keep the counter next to the state file.
+        return state_file.resolve().parent / ".context" / "task-tool-burst.json"
+    return root / ".context" / "task-tool-burst.json"
+
+
+def load_counter(counter_file: Path) -> dict[str, Any]:
+    if not counter_file.exists():
+        return {"count": 0, "last_stage": None, "last_tool": None}
+    try:
+        data = json.loads(counter_file.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            return data
+    except json.JSONDecodeError:
+        pass
+    return {"count": 0, "last_stage": None, "last_tool": None}
+
+
+def save_counter(counter_file: Path, data: dict[str, Any]) -> None:
+    counter_file.parent.mkdir(parents=True, exist_ok=True)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=counter_file.parent, suffix=".json.tmp")
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=2)
+        os.replace(tmp_path, counter_file)
+    except Exception:
+        try:
+            os.close(tmp_fd)
+        except OSError:
+            pass
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+
+
+def block(message: str) -> int:
+    print(f"BLOCKED: {message}", file=sys.stderr)
+    return 1
+
+
+def allow() -> int:
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Lincoln task-tool guard")
+    parser.add_argument("--state-file", type=Path, default=None)
+    parser.add_argument("--tool-name", required=True)
+    parser.add_argument("--tool-args", default="{}")
+    parser.add_argument(
+        "--dialogue-stages",
+        help="Comma-separated list of stage IDs where task tools are forbidden",
+    )
+    parser.add_argument(
+        "--max-consecutive",
+        type=int,
+        default=DEFAULT_MAX_CONSECUTIVE,
+        help="Maximum allowed consecutive TaskCreate/TaskUpdate calls",
+    )
+    args = parser.parse_args(argv)
+
+    state_file = args.state_file
+    if state_file is None:
+        env_path = os.environ.get("LINCOLN_STATE_FILE")
+        if env_path:
+            state_file = Path(env_path)
+        elif resolve_state_path is not None:
+            state_file = resolve_state_path(None, Path(__file__).resolve().parents[1])
+        else:
+            state_file = Path.cwd() / ".claude" / "workflow-state.yaml"
+
+    state = load_state(state_file)
+    if state is None:
+        # Not a Lincoln project or not initialized yet; stay out of the way.
+        return allow()
+
+    current_stage = state.get("current_run", {}).get("current_stage") or "not_started"
+
+    # Reset the burst counter whenever a non-task tool is used.
+    if args.tool_name not in TASK_TOOLS:
+        counter_file = counter_file_path(state_file)
+        save_counter(
+            counter_file,
+            {"count": 0, "last_stage": current_stage, "last_tool": args.tool_name},
+        )
+        return allow()
+
+    # We are handling a task tool from here on.
+    override_stages = None
+    if args.dialogue_stages is not None:
+        override_stages = {s.strip() for s in args.dialogue_stages.split(",") if s.strip()}
+
+    root = resolve_project_root(state_file)
+    workflow_file = None
+    if root is not None:
+        workflow_file = root / ".claude" / "workflows" / "interview-to-knowledge.yaml"
+
+    dialogue = dialogue_stages(workflow_file, override_stages)
+
+    if current_stage in dialogue:
+        return block(
+            f"TaskCreate/TaskUpdate are not allowed in the dialogue stage '{current_stage}'. "
+            "Send your message to the user directly instead of using task tools as placeholders."
+        )
+
+    counter_file = counter_file_path(state_file)
+    counter = load_counter(counter_file)
+
+    if counter.get("last_stage") != current_stage or counter.get("last_tool") not in TASK_TOOLS:
+        counter = {"count": 1, "last_stage": current_stage, "last_tool": args.tool_name}
+    else:
+        counter = {
+            **counter,
+            "count": counter.get("count", 0) + 1,
+        }
+
+    save_counter(counter_file, counter)
+
+    if counter["count"] > args.max_consecutive:
+        return block(
+            f"Too many consecutive task-tool calls ({counter['count']}) in stage '{current_stage}'. "
+            "Perform a non-task action (e.g. Read or send a user message) before creating/updating more tasks."
+        )
+
+    return allow()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/track-artifacts.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Track artifacts produced by side-effect tools and update workflow-state.yaml.
+
+Usage:
+    python scripts/track-artifacts.py --state-file .claude/workflow-state.yaml \
+        --tool Write --args '{"file_path": "designs/foo/bar.md"}'
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from scripts.lincoln_paths import get_process_slug
+
+
+# Paths that are considered workflow artifacts (relative to project root).
+ARTIFACT_PREFIXES = (
+    "interviews/",
+    "requirements/",
+    "designs/",
+    "openspec/",
+    "knowledge/",
+    ".github/linked-issues.yaml",
+    ".github/lincoln-sync-queue/",
+)
+
+
+def load_state(path: Path) -> dict:
+    return yaml.safe_load(path.read_text(encoding="utf-8"))
+
+
+def save_state(path: Path, state: dict) -> None:
+    path.write_text(yaml.dump(state, allow_unicode=True, sort_keys=False), encoding="utf-8")
+
+
+def extract_paths(tool: str, args: str, project_root: Path) -> list[str]:
+    """Extract relative file paths from tool arguments (best-effort)."""
+    paths: list[str] = []
+
+    # For Write/Edit the argument is JSON with file_path
+    if tool in ("Write", "Edit"):
+        try:
+            data = json.loads(args)
+            file_path = data.get("file_path") or data.get("path")
+            if file_path:
+                paths.append(str(file_path))
+        except json.JSONDecodeError:
+            pass
+
+    # For Bash, scan for common output paths in the command string
+    if tool == "Bash":
+        try:
+            data = json.loads(args)
+            command = data.get("command", "")
+        except json.JSONDecodeError:
+            command = args
+        # Match paths that look like output files
+        for match in re.finditer(r"(?:\s|=|>\s?)([\w\-./]+\.(?:md|yaml|yml|json|pen))", command):
+            paths.append(match.group(1))
+
+    # For Pencil MCP tools, we can't easily know exported files; skip.
+
+    # Normalize and filter to project-relative artifact paths.
+    result: list[str] = []
+    for p in paths:
+        raw = Path(p.strip())
+        if raw.is_absolute():
+            try:
+                p = str(raw.resolve().relative_to(project_root.resolve()))
+            except ValueError:
+                continue
+        else:
+            p = str(raw).lstrip("/")
+        if any(p.startswith(prefix) for prefix in ARTIFACT_PREFIXES) or "/recordings/" in p or "/requirements/" in p or "/designs/" in p or "/interviews/" in p or "/openspec/" in p:
+            result.append(p)
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--state-file", type=Path, required=True)
+    parser.add_argument("--tool", required=True)
+    parser.add_argument("--args", default="{}")
+    parser.add_argument("--project-root", type=Path, default=Path.cwd())
+    args = parser.parse_args()
+
+    if not args.state_file.exists():
+        return 0
+
+    state = load_state(args.state_file)
+    current_stage = state.get("current_run", {}).get("current_stage")
+    if not current_stage:
+        return 0
+
+    new_paths = extract_paths(args.tool, args.args, args.project_root)
+    if not new_paths:
+        return 0
+
+    if "nodes" in state:
+        matching = [n for n in state.setdefault("nodes", []) if n.get("stage_id") == current_stage]
+        if matching:
+            node = matching[-1]
+        else:
+            node = {
+                "stage_id": current_stage,
+                "node_id": f"{current_stage}-artifact-tracking",
+                "status": state.get("current_run", {}).get("status", "in_progress"),
+                "started_at": state.get("current_run", {}).get("last_updated_at"),
+                "completed_at": None,
+                "gate_passed": False,
+                "approved_by": None,
+                "artifacts": [],
+                "handoff_file": None,
+            }
+            state["nodes"].append(node)
+        existing = set(node.get("artifacts", []))
+        node["artifacts"] = sorted(existing | set(new_paths))
+    else:
+        stage_state = state.setdefault("stages", {}).setdefault(current_stage, {})
+        existing = set(stage_state.get("artifacts_produced", []))
+        stage_state["artifacts_produced"] = sorted(existing | set(new_paths))
+
+    state.setdefault("current_run", {}).setdefault("variables", {}).setdefault(
+        "process_slug",
+        get_process_slug(state, args.state_file),
+    )
+    save_state(args.state_file, state)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())