@sushanglewis/lincoln 1.5.4 → 1.6.1

package/framework/scripts/stage_loader.py

@@ -37,6 +37,7 @@ if str(PROJECT_ROOT) not in sys.path:
 import yaml
 
 from scripts import lincoln_trace
+from scripts import lincoln_render
 from scripts.lincoln_documents import write_documents_index
 from scripts.lincoln_index import write_package_index
 from scripts.lincoln_paths import (
@@ -192,6 +193,21 @@ def interpolate(value: str, variables: dict[str, Any]) -> str:
     return re.sub(r"\{(\w+)\}", replacer, value)
 
 
+def interpolate_value(value: Any, variables: dict[str, Any]) -> Any:
+    """Recursively interpolate {var} placeholders in nested str/dict/list values.
+
+    Non-string scalars are returned unchanged so new optional structured
+    stage fields (e.g. context.execution, references) pass through gracefully.
+    """
+    if isinstance(value, str):
+        return interpolate(value, variables)
+    if isinstance(value, dict):
+        return {key: interpolate_value(val, variables) for key, val in value.items()}
+    if isinstance(value, list):
+        return [interpolate_value(item, variables) for item in value]
+    return value
+
+
 def interpolate_artifact(value: str, state: dict[str, Any], state_file: Path | None = None) -> str:
     value = interpolate(value, get_variables(state))
     return interpolate_process_path(value, state, resolve_state_path(state_file))
@@ -328,9 +344,8 @@ def resolve_stage_context(
 
     context = stage.get("context", {})
     interpolated_context = {
-        key: interpolate(value, variables)
+        key: interpolate_value(value, variables)
         for key, value in context.items()
-        if isinstance(value, str)
     }
 
     artifacts = stage.get("artifacts", {})
@@ -343,6 +358,20 @@ def resolve_stage_context(
         for art in artifacts.get("optional", [])
     ]
 
+    # Schema 3.0.0 optional structured fields; emitted with defaults when absent.
+    raw_artifact_templates = stage.get("artifact_templates", {}) or {}
+    artifact_templates = {
+        interpolate_artifact(str(art_path), state, state_file): interpolate(str(tpl), variables)
+        for art_path, tpl in raw_artifact_templates.items()
+    }
+    stage_variables = list(stage.get("variables", []) or [])
+    execution_mode = stage.get("execution_mode", "both")
+    primary_action = stage.get("primary_action")
+    references = {
+        str(key): interpolate(str(val), variables)
+        for key, val in (stage.get("references", {}) or {}).items()
+    }
+
     agent = stage.get("agent", {})
     skills = stage.get("skills", {})
 
@@ -359,6 +388,11 @@ def resolve_stage_context(
         "optional_skills": skills.get("optional", []),
         "required_artifacts": required_artifacts,
         "optional_artifacts": optional_artifacts,
+        "artifact_templates": artifact_templates,
+        "variables": stage_variables,
+        "execution_mode": execution_mode,
+        "primary_action": primary_action,
+        "references": references,
         "context": interpolated_context,
         "context_path": str((STAGES_DIR / f"{stage_id}.yaml").relative_to(PROJECT_ROOT)),
         "workflow_template": template_name,
@@ -389,6 +423,11 @@ def action_load(stage_id: str, state: dict[str, Any], state_file: Path | None =
         "context_paths": [context["context_path"]],
         "required_skills": context["required_skills"],
         "optional_skills": context["optional_skills"],
+        "artifact_templates": context["artifact_templates"],
+        "variables": context["variables"],
+        "execution_mode": context["execution_mode"],
+        "primary_action": context["primary_action"],
+        "references": context["references"],
     }
 
 
@@ -935,6 +974,72 @@ def action_update_last_updated(state_file: Path) -> None:
     save_state(state, state_file)
 
 
+def action_render_page(
+    stage_id: str,
+    target: str,
+    state: dict[str, Any],
+    state_file: Path,
+    *,
+    title: str = "",
+    nav_label: str = "",
+    nav_group: str = "Docs",
+    version: str = "",
+    uid: str = "",
+    stage_mark: str = "",
+    markdown_path: str = "",
+    extra_variables: dict[str, str] | None = None,
+) -> Path:
+    """Render a single HTML page using lincoln_render and record it as an artifact."""
+    markdown_source = ""
+    if markdown_path:
+        md_path = PROJECT_ROOT / markdown_path
+        if not md_path.exists():
+            raise FileNotFoundError(f"Markdown source not found: {md_path}")
+        markdown_source = md_path.read_text(encoding="utf-8")
+
+    html = lincoln_render.render_page(
+        stage_id=stage_id,
+        target=target,
+        title=title,
+        nav_label=nav_label,
+        nav_group=nav_group,
+        version=version,
+        uid=uid,
+        stage_mark=stage_mark or stage_id,
+        markdown_source=markdown_source,
+        extra_variables=extra_variables,
+        state_file=state_file,
+    )
+
+    target_path = PROJECT_ROOT / target
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    lincoln_render.atomic_write_text(target_path, html)
+
+    # Record the rendered artifact under the current stage node.
+    latest_node = get_latest_node_for_stage(state, stage_id)
+    if latest_node is None:
+        latest_node = {
+            "stage_id": stage_id,
+            "node_id": f"{stage_id}-{now_iso()}",
+            "status": "in_progress",
+            "started_at": now_iso(),
+            "completed_at": None,
+            "gate_passed": False,
+            "approved_by": None,
+            "artifacts": [],
+            "handoff_file": None,
+        }
+        state.setdefault("nodes", []).append(latest_node)
+
+    existing = set(latest_node.get("artifacts", []))
+    existing.add(str(target_path.relative_to(PROJECT_ROOT)))
+    latest_node["artifacts"] = sorted(existing)
+
+    save_state(state, state_file)
+    print(f"Rendered {target_path.relative_to(PROJECT_ROOT)}")
+    return target_path
+
+
 def action_benchmark_report(state_file: Path, trigger: str) -> dict[str, str] | None:
     """Generate a benchmark report for the current process state."""
     from scripts import lincoln_benchmark
@@ -976,6 +1081,7 @@ def main() -> int:
             "recover",
             "status",
             "handoff-report",
+            "render-page",
             "benchmark-report",
             "update-last-updated",
         ],
@@ -988,6 +1094,16 @@ def main() -> int:
     parser.add_argument("--handoff-file", help="Handoff file path for append-node")
     parser.add_argument("--artifacts", help="Comma-separated artifact paths for append-node")
     parser.add_argument("--trigger", default="manual", help="Trigger type for benchmark-report")
+    # render-page arguments
+    parser.add_argument("--target", help="Repo-relative target artifact path for render-page")
+    parser.add_argument("--title", default="", help="Page title for render-page")
+    parser.add_argument("--nav-label", default="", help="Navigation label for render-page")
+    parser.add_argument("--nav-group", default="Docs", help="Navigation group for render-page")
+    parser.add_argument("--version", default="", help="Version marker for render-page")
+    parser.add_argument("--uid", default="", help="Stable page/doc UID for render-page")
+    parser.add_argument("--stage-mark", default="", help="Stage label for render-page")
+    parser.add_argument("--markdown", default="", help="Markdown source path for render-page")
+    parser.add_argument("--set", action="append", default=[], help="Extra variable key=value for render-page")
     args = parser.parse_args()
 
     state_file = resolve_state_path(args.state_file)
@@ -1056,6 +1172,37 @@ def main() -> int:
         action_update_last_updated(state_file)
         return 0
 
+    if args.action == "render-page":
+        if not args.stage:
+            parser.error("--stage is required for render-page")
+        if not args.target:
+            parser.error("--target is required for render-page")
+        extra: dict[str, str] = {}
+        for item in args.set:
+            if "=" not in item:
+                parser.error(f"--set value must be key=value: {item}")
+            key, value = item.split("=", 1)
+            extra[key] = value
+        try:
+            action_render_page(
+                stage_id=args.stage,
+                target=args.target,
+                state=state,
+                state_file=state_file,
+                title=args.title,
+                nav_label=args.nav_label,
+                nav_group=args.nav_group,
+                version=args.version,
+                uid=args.uid,
+                stage_mark=args.stage_mark,
+                markdown_path=args.markdown,
+                extra_variables=extra,
+            )
+        except Exception as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 1
+        return 0
+
     if args.action == "benchmark-report":
         result = action_benchmark_report(state_file, args.trigger)
         if result is None:

package/framework/scripts/static-check.sh

@@ -163,6 +163,42 @@ if errors:
 print("All agent frontmatters valid.")
 PY
 
+echo "==> Validate imported external agents are in sync with manifests"
+"$PYTHON" - "$ROOT" <<'PY'
+import sys, yaml
+from pathlib import Path
+
+root = Path(sys.argv[1])
+external_dir = root / ".claude" / "agents" / "external"
+errors = []
+
+for manifest_path in sorted(external_dir.glob("*.manifest.yaml")):
+    docs = list(yaml.safe_load_all(manifest_path.read_text(encoding="utf-8")))
+    data = docs[0] if docs else {}
+    if not isinstance(data, dict):
+        continue
+    framework = manifest_path.stem.replace(".manifest", "")
+    prefix = data.get("prefix", framework)
+    imported = data.get("imported_agents", []) or []
+    target_dir = external_dir / framework / "agents"
+    expected_names = {f"{prefix}-{Path(agent.replace('.md', '')).name}.md" for agent in imported}
+    actual_names = {p.name for p in target_dir.glob("*.md")} if target_dir.exists() else set()
+
+    missing = expected_names - actual_names
+    extra = actual_names - expected_names
+    if missing:
+        errors.append(f"{manifest_path.name}: missing imported agents: {sorted(missing)}")
+    if extra:
+        errors.append(f"{manifest_path.name}: unexpected agents on disk: {sorted(extra)}")
+
+if errors:
+    print("External agent sync issues:")
+    for e in errors:
+        print(f"  - {e}")
+    sys.exit(1)
+print("All imported external agents are present.")
+PY
+
 echo "==> Validate Python syntax"
 "$PYTHON" -m py_compile scripts/validate_stage.py
 
@@ -245,7 +281,7 @@ for stage_yaml in sorted((root / ".claude" / "stages").glob("*.yaml")):
     if not isinstance(data, dict):
         errors.append(f"{stage_yaml.name}: root is not a mapping")
         continue
-    for key in ["schema_version", "id", "name", "description", "templates", "prerequisite_stage", "next_stage", "human_gate", "agent", "skills", "artifacts", "context", "gates"]:
+    for key in ["schema_version", "id", "name", "description", "workflows", "prerequisite_stage", "next_stage", "human_gate", "agent", "skills", "artifacts", "context", "gates"]:
         if key not in data:
             errors.append(f"{stage_yaml.name}: missing key '{key}'")
 
@@ -341,6 +377,9 @@ echo "==> Check plugin package manifest"
 find .claude scripts tools -type d -name __pycache__ -prune -exec rm -rf {} + 2>/dev/null || true
 "$PYTHON" scripts/package-lincoln-plugin.py check
 
+echo "==> Check prompt drift (PM stages only; non-PM drift reported separately)"
+"$PYTHON" scripts/check-prompt-drift.py --strict --focus pm
+
 echo "==> Run pytest"
 "$PYTHON" -m pytest tests/ -v
 pytest_exit=$?

package/framework/scripts/sync-external-agents.sh

@@ -19,6 +19,8 @@ AGENTS_DIR="$ROOT/.claude/agents/external"
 mkdir -p "$AGENTS_DIR"
 
 "$ROOT/.venv/bin/python3" - "$AGENTS_DIR" "$DRY_RUN" <<'PY'
+from __future__ import annotations
+
 import sys
 from pathlib import Path
 import re

package/framework/scripts/update_readme_version.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""README 版本引用锁步工具(配合 bump_version.py 的事实源 `.version-bump.json`)。
+
+README.md / README.en.md 中的 release 徽章与版本公告行不属于 JSON manifest,
+无法被 bump 的 JSON Pointer 覆盖,由本脚本按正则锁步。用法:
+
+    python3 scripts/update_readme_version.py                    # 锁步更新两份 README
+    python3 scripts/update_readme_version.py --check            # CI:验证 README 与事实源一致
+    python3 scripts/update_readme_version.py --root /path/repo  # 指定仓库根(默认脚本上一级)
+    python3 scripts/update_readme_version.py --allow-downgrade  # 允许把 README 版本号改小
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+ROOT = Path(__file__).resolve().parents[1]
+SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
+VERSION_EXTRACT = re.compile(r"v(\d+\.\d+\.\d+)")
+
+BADGE = re.compile(r"(https://img\.shields\.io/badge/release-v)\d+\.\d+\.\d+(-blue)")
+CALLOUT_ZH = re.compile(r"(\*\*v)\d+\.\d+\.\d+(\*\* 已发布)")
+CALLOUT_EN = re.compile(r"(\*\*v)\d+\.\d+\.\d+(\*\* is released)")
+
+READMES = (
+    ("README.md", CALLOUT_ZH),
+    ("README.en.md", CALLOUT_EN),
+)
+
+
+def parse_semver(version: str) -> tuple[int, int, int]:
+    return tuple(int(part) for part in version.split("."))
+
+
+def is_newer(left: str, right: str) -> bool:
+    return parse_semver(left) > parse_semver(right)
+
+
+def load_version(root: Path) -> str:
+    source = root / ".version-bump.json"
+    if not source.exists():
+        sys.exit("missing version source: .version-bump.json")
+    try:
+        data = json.loads(source.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        sys.exit(f"malformed .version-bump.json: {exc}")
+    version = data.get("version", "")
+    if not SEMVER.match(version):
+        sys.exit(f".version-bump.json has invalid version: {version!r}")
+    return version
+
+
+def sync_text(text: str, version: str, patterns: Iterable[re.Pattern[str]]) -> str:
+    """把 text 中所有 pattern 命中的版本号替换为 version,返回新文本(不原地修改)。"""
+    for pattern in patterns:
+        text = pattern.sub(lambda m: m.group(1) + version + m.group(2), text)
+    return text
+
+
+def find_stale(text: str, version: str, patterns: Iterable[re.Pattern[str]]) -> str | None:
+    """返回第一个与事实源不一致的命中片段;无命中或已一致返回 None。"""
+    for pattern in patterns:
+        for match in pattern.finditer(text):
+            if match.group(0) != match.group(1) + version + match.group(2):
+                return match.group(0)
+    return None
+
+
+def readme_version(text: str) -> str | None:
+    """从 README 文本中提取第一个 vX.Y.Z 版本号(徽章或公告行)。"""
+    match = VERSION_EXTRACT.search(text)
+    return match.group(1) if match else None
+
+
+def cmd_update(root: Path, check: bool, allow_downgrade: bool) -> int:
+    version = load_version(root)
+    drifted: list[tuple[str, str]] = []
+    skipped: list[tuple[str, str]] = []
+
+    for name, callout in READMES:
+        path = root / name
+        if not path.exists():
+            sys.exit(f"missing README: {name}")
+        original = path.read_text(encoding="utf-8")
+        stale = find_stale(original, version, (BADGE, callout))
+        if stale is None:
+            continue
+
+        current = readme_version(original)
+        if current is not None and is_newer(current, version) and not allow_downgrade:
+            skipped.append((name, current))
+            continue
+
+        drifted.append((name, stale))
+        if not check:
+            path.write_text(
+                sync_text(original, version, (BADGE, callout)), encoding="utf-8"
+            )
+
+    if skipped:
+        print(
+            f"README version(s) newer than source v{version}; skipping to avoid downgrade. "
+            "Use --allow-downgrade to force.",
+            file=sys.stderr,
+        )
+        for name, current in skipped:
+            print(f"  {name}: v{current} -> v{version} skipped", file=sys.stderr)
+
+    if check:
+        if drifted:
+            print(f"README version drift detected (source: v{version}):", file=sys.stderr)
+            for name, stale in drifted:
+                print(f"  {name}: {stale!r} != v{version}", file=sys.stderr)
+            print("fix: python3 scripts/update_readme_version.py", file=sys.stderr)
+            return 1
+        print(f"README version lockstep OK: {version} ({len(READMES)} files)")
+        return 0
+
+    for name, _ in drifted:
+        print(f"  updated {name} -> v{version}")
+    if drifted:
+        print(f"updated {len(drifted)} README(s) to v{version}")
+    elif not skipped:
+        print(f"READMEs already at v{version}; nothing to do")
+    return 0 if not skipped else 1
+
+
+def main(argv: list[str], root: Path = ROOT) -> int:
+    parser = argparse.ArgumentParser(
+        description="Sync README version badges and callouts with .version-bump.json."
+    )
+    parser.add_argument("--check", action="store_true", help="verify lockstep without writing")
+    parser.add_argument("--root", type=Path, default=root, help="repository root")
+    parser.add_argument(
+        "--allow-downgrade",
+        action="store_true",
+        help="allow rewriting README version to an older version",
+    )
+    args = parser.parse_args(argv[1:])
+    return cmd_update(args.root, check=args.check, allow_downgrade=args.allow_downgrade)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/framework/scripts/validate_stage.py

@@ -23,7 +23,11 @@ if str(PROJECT_ROOT) not in sys.path:
     sys.path.insert(0, str(PROJECT_ROOT))
 
 from scripts.lincoln_documents import extract_markdown_version
-from scripts.lincoln_index import VERSION_COMMENT_RE, extract_html_markdown
+from scripts.lincoln_index import (
+    VERSION_COMMENT_RE,
+    extract_html_markdown,
+    extract_html_meta,
+)
 from scripts.lincoln_paths import get_process_slug, load_yaml, resolve_state_path
 
 
@@ -246,6 +250,75 @@ def check_portal_index_exists() -> None:
     pass_check(f"portal index exists: {target}")
 
 
+# ---------------------------------------------------------------------------
+# Schema 3.0.0 placeholder checks (registered but not yet implemented)
+# ---------------------------------------------------------------------------
+
+
+def check_artifact_meta_complete() -> None:
+    """Verify that declared HTML artifacts carry the meta tags the portal needs."""
+    state_file = resolve_state_path(None, PROJECT_ROOT)
+    if not state_file or not state_file.exists():
+        fail("No state file found")
+    state = load_yaml(state_file)
+    stage_id = state.get("current_run", {}).get("current_stage")
+    if not stage_id:
+        fail("No current stage in state")
+
+    stage_path = PROJECT_ROOT / ".claude" / "stages" / f"{stage_id}.yaml"
+    if not stage_path.exists():
+        fail(f"Stage YAML not found: {stage_path}")
+    stage = load_yaml(stage_path)
+
+    variables = state.get("current_run", {}).get("variables", {})
+    process_slug = str(variables.get("process_slug") or get_process_slug(state, state_file))
+
+    artifacts = stage.get("artifacts", {})
+    required = artifacts.get("required", [])
+    html_artifacts = [str(art) for art in required if str(art).endswith(".html")]
+    if not html_artifacts:
+        pass_check("no HTML artifacts to check")
+
+    missing: list[str] = []
+    for art in html_artifacts:
+        path = art.replace("{process_slug}", process_slug)
+        for key, value in variables.items():
+            path = path.replace(f"{{{key}}}", str(value))
+        target = PROJECT_ROOT / path
+        if "*" in path:
+            # Glob artifact: check all present matches.
+            for match in PROJECT_ROOT.glob(path):
+                meta = extract_html_meta(match)
+                rel = str(match.relative_to(PROJECT_ROOT))
+                if not meta.get("nav_label"):
+                    missing.append(f"{rel}: missing nav-label")
+                if not meta.get("uid"):
+                    missing.append(f"{rel}: missing doc-uid/page-uid")
+            continue
+        if not target.exists():
+            missing.append(f"{path}: file not found")
+            continue
+        meta = extract_html_meta(target)
+        if not meta.get("nav_label"):
+            missing.append(f"{path}: missing nav-label")
+        if not meta.get("uid"):
+            missing.append(f"{path}: missing doc-uid/page-uid")
+
+    if missing:
+        fail("Artifact meta incomplete:\n  - " + "\n  - ".join(missing))
+    pass_check("all HTML artifacts have required meta tags")
+
+
+def check_ids_valid() -> None:
+    """Placeholder: verify referenced IDs (session/design/change/etc.) are valid. Not yet implemented."""
+    pass_check("not implemented")
+
+
+def check_portal_index_fresh() -> None:
+    """Placeholder: verify portal index is up to date with artifacts. Not yet implemented."""
+    pass_check("not implemented")
+
+
 # ---------------------------------------------------------------------------
 # PRD checks
 # ---------------------------------------------------------------------------
@@ -310,6 +383,9 @@ ENTRY_CHECKS = {
     "artifact_exists": check_artifact_exists,
     "audio_format_supported": check_audio_format_supported,
     "previous_stage_completed": check_previous_stage_completed,
+    "artifact_meta_complete": check_artifact_meta_complete,
+    "ids_valid": check_ids_valid,
+    "portal_index_fresh": check_portal_index_fresh,
 }
 
 EXIT_CHECKS = {
@@ -322,6 +398,9 @@ EXIT_CHECKS = {
     "prd_has_required_sections": check_prd_has_required_sections,
     "prd_snapshot_present": check_prd_snapshot_present,
     "portal_index_exists": check_portal_index_exists,
+    "artifact_meta_complete": check_artifact_meta_complete,
+    "ids_valid": check_ids_valid,
+    "portal_index_fresh": check_portal_index_fresh,
 }
 
 

package/framework/tools/lincoln/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@sushanglewis/lincoln",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@sushanglewis/lincoln",
-      "version": "1.5.4",
+      "version": "1.6.1",
       "license": "MIT",
       "dependencies": {
         "ink": "^5.2.0",

package/framework/tools/lincoln/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sushanglewis/lincoln-recorder",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "description": "Cross-tool terminal UI for recording Lincoln interviews",
   "type": "module",
   "main": "./dist/index.js",

package/framework/tools/lincoln-installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lincoln-install",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "description": "Terminal TUI installer for the Lincoln AI-Native R&D workflow system",
   "type": "module",
   "main": "dist/main.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sushanglewis/lincoln",
-  "version": "1.5.4",
+  "version": "1.6.1",
   "description": "Global Lincoln agent harness plugin CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
     "typecheck:tests": "tsc -p tsconfig.tests.json",
     "lint": "echo 'lint not configured'",
     "prepack": "npm run build && node ../../scripts/sync-framework-package.mjs",
-    "postinstall": "node dist/postinstall.js"
+    "postinstall": "node -e \"const fs=require('fs'); if(fs.existsSync('dist/postinstall.js')){import('./dist/postinstall.js').then(m=>m.runPostinstall()).then(c=>process.exit(c)).catch(()=>process.exit(0))}\""
   },
   "dependencies": {
     "js-yaml": "^4.1.0"