@sushanglewis/lincoln 1.5.5 → 1.6.2

package/framework/scripts/extract_release_notes.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""从 RELEASE.md 抽取指定版本的发布说明,供 GitHub Release 等发布流程复用。
+
+匹配的节标题形态:`# Lincoln vX.Y.Z ...`、`# vX.Y.Z ...`、`## vX.Y.Z ...`;
+抽取范围从节标题起到下一个同级或更高级标题之前。用法:
+
+    python3 scripts/extract_release_notes.py 1.6.0
+    python3 scripts/extract_release_notes.py v1.6.0 --root /path/to/repo
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
+HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+RELEASE_FILE = "RELEASE.md"
+
+
+def section_matcher(version: str) -> re.Pattern:
+    """匹配节标题文本:`Lincoln ` 前缀可选,版本号后必须是空白或行尾。"""
+    return re.compile(rf"^(?:Lincoln\s+)?v{re.escape(version)}(?=\s|$)")
+
+
+def extract_section(text: str, version: str) -> str | None:
+    """抽取 version 对应章节;找不到返回 None。"""
+    matcher = section_matcher(version)
+    lines = text.splitlines()
+    start: int | None = None
+    level = 0
+    for i, line in enumerate(lines):
+        heading = HEADING.match(line)
+        if heading and len(heading.group(1)) <= 2 and matcher.match(heading.group(2)):
+            start, level = i, len(heading.group(1))
+            break
+    if start is None:
+        return None
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        heading = HEADING.match(lines[j])
+        if heading and len(heading.group(1)) <= level:
+            end = j
+            break
+    return "\n".join(lines[start:end]).rstrip()
+
+
+def main(argv: list[str], root: Path = ROOT) -> int:
+    args = argv[1:]
+    if "--root" in args:
+        index = args.index("--root")
+        if index + 1 >= len(args):
+            print("--root requires a path", file=sys.stderr)
+            return 2
+        root = Path(args[index + 1])
+        del args[index : index + 2]
+    if len(args) != 1:
+        print(__doc__, file=sys.stderr)
+        return 2
+    version = args[0].removeprefix("v")
+    if not SEMVER.match(version):
+        print(f"invalid semver (want X.Y.Z): {args[0]!r}", file=sys.stderr)
+        return 2
+    release = root / RELEASE_FILE
+    if not release.exists():
+        print(f"missing release notes: {RELEASE_FILE}", file=sys.stderr)
+        return 1
+    section = extract_section(release.read_text(encoding="utf-8"), version)
+    if section is None:
+        print(f"section for v{version} not found in {RELEASE_FILE}", file=sys.stderr)
+        return 1
+    print(section)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/framework/scripts/init-lincoln-branch.sh

@@ -253,11 +253,17 @@ for dir in \
     "$PROCESS_ROOT/openspec/changes" \
     "$PROCESS_ROOT/openspec/specs" \
     "$PROCESS_ROOT/recordings" \
+    "$PROCESS_ROOT/.lincoln/one-id" \
     ".github/lincoln-sync-queue"; do
     mkdir -p "$dir"
     touch "$dir/.gitkeep"
 done
 
+# Initialize empty one-id index files for the issue package.
+for idx in docs features stories models apis flows fields pages; do
+    echo "{}" > "$PROCESS_ROOT/.lincoln/one-id/${idx}.yaml"
+done
+
 # Copy the HTML portal scaffold from read-only templates.
 # Templates stay in .claude/templates/issue-package/; only the rendered shell and
 # shared assets are copied into the package.

package/framework/scripts/lincoln_command_map.py

@@ -105,7 +105,7 @@ def list_workflows() -> dict[str, dict[str, Any]]:
 
 def list_agents() -> dict[str, dict[str, Any]]:
     agents: dict[str, dict[str, Any]] = {}
-    excluded = {"default.md", "_contract.md"}
+    excluded = {"default.md"}
     for path in sorted(AGENTS_DIR.glob("*.md")):
         if path.name in excluded:
             continue

package/framework/scripts/lincoln_id.py

@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""One-id index manager for Lincoln issue packages.
+
+Provides stable, machine-readable identifiers for PRD themes, features, user
+stories, data models, APIs, flows, fields, and pages. Agents can query by ID
+instead of reading whole documents.
+
+Examples:
+    python scripts/lincoln_id.py lookup page/checkout-cart
+    python scripts/lincoln_id.py list --type page
+    python scripts/lincoln_id.py related feature/checkout-redesign
+    python scripts/lincoln_id.py create page/checkout-cart \
+        --title "购物车" \
+        --path "pages/prototype/web/checkout-cart/page.html" \
+        --feature feature/checkout-redesign
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+import yaml
+
+from scripts.lincoln_paths import (
+    PROJECT_ROOT as _PROJECT_ROOT,
+    get_process_slug,
+    load_yaml,
+    resolve_state_path,
+)
+
+ONE_ID_DIR = ".lincoln/one-id"
+
+ID_RE = re.compile(r"^(doc|feature|story|model|api|flow|field|page)/[a-z0-9][a-z0-9-]*$")
+
+TYPE_TO_FILE = {
+    "doc": "docs.yaml",
+    "feature": "features.yaml",
+    "story": "stories.yaml",
+    "model": "models.yaml",
+    "api": "apis.yaml",
+    "flow": "flows.yaml",
+    "field": "fields.yaml",
+    "page": "pages.yaml",
+}
+
+FILE_TO_TYPE = {v: k for k, v in TYPE_TO_FILE.items()}
+
+
+def _load_state() -> dict[str, Any] | None:
+    state_path = resolve_state_path(None, PROJECT_ROOT)
+    if not state_path.exists():
+        return None
+    try:
+        return load_yaml(state_path)
+    except Exception:
+        return None
+
+
+def _process_slug() -> str:
+    state = _load_state()
+    state_path = resolve_state_path(None, PROJECT_ROOT)
+    return get_process_slug(state, state_path)
+
+
+def _one_id_dir() -> Path:
+    return PROJECT_ROOT / _process_slug() / ONE_ID_DIR
+
+
+def _index_path(id_type: str) -> Path:
+    filename = TYPE_TO_FILE[id_type]
+    path = _one_id_dir() / filename
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _load_index(id_type: str) -> dict[str, Any]:
+    path = _index_path(id_type)
+    if not path.exists():
+        return {}
+    try:
+        data = load_yaml(path)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _save_index(id_type: str, data: dict[str, Any]) -> None:
+    path = _index_path(id_type)
+    path.write_text(yaml.safe_dump(data, allow_unicode=True, sort_keys=True), encoding="utf-8")
+
+
+def _split_id(full_id: str) -> tuple[str, str]:
+    if "/" not in full_id:
+        raise ValueError(f"Invalid ID (must contain '/'): {full_id}")
+    id_type, name = full_id.split("/", 1)
+    if id_type not in TYPE_TO_FILE:
+        raise ValueError(f"Unknown ID type '{id_type}': {full_id}")
+    if not ID_RE.match(full_id):
+        raise ValueError(f"Invalid ID format: {full_id}")
+    return id_type, name
+
+
+def _pretty_print(data: Any, indent: int = 0) -> None:
+    prefix = "  " * indent
+    if isinstance(data, dict):
+        for key, value in data.items():
+            if isinstance(value, (dict, list)):
+                print(f"{prefix}{key}:")
+                _pretty_print(value, indent + 1)
+            else:
+                print(f"{prefix}{key}: {value}")
+    elif isinstance(data, list):
+        for item in data:
+            if isinstance(item, (dict, list)):
+                print(f"{prefix}-")
+                _pretty_print(item, indent + 1)
+            else:
+                print(f"{prefix}- {item}")
+    else:
+        print(f"{prefix}{data}")
+
+
+def cmd_lookup(full_id: str) -> int:
+    """Print the complete entry for an ID, searching across all index files."""
+    try:
+        id_type, name = _split_id(full_id)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    index = _load_index(id_type)
+    entry = index.get(full_id)
+    if entry is None:
+        print(f"NOT FOUND: {full_id}")
+        return 1
+
+    print(f"{full_id}:")
+    _pretty_print(entry, indent=1)
+    return 0
+
+
+def cmd_list(id_type: str | None) -> int:
+    """List all IDs, optionally filtered by type."""
+    if id_type:
+        if id_type not in TYPE_TO_FILE:
+            print(f"ERROR: unknown type '{id_type}'", file=sys.stderr)
+            return 1
+        types = [id_type]
+    else:
+        types = list(TYPE_TO_FILE.keys())
+
+    found = False
+    for t in types:
+        index = _load_index(t)
+        for full_id in sorted(index):
+            print(full_id)
+            found = True
+    if not found:
+        print("No IDs indexed yet.")
+    return 0
+
+
+def _collect_related(
+    full_id: str,
+    visited: set[str],
+    collected: dict[str, list[dict[str, Any]]],
+) -> None:
+    """Recursively collect entries related to *full_id* via cross-reference fields."""
+    if full_id in visited:
+        return
+    visited.add(full_id)
+
+    try:
+        id_type, _ = _split_id(full_id)
+    except ValueError:
+        return
+
+    index = _load_index(id_type)
+    entry = index.get(full_id)
+    if entry is None:
+        return
+
+    collected.setdefault(id_type, []).append({full_id: entry})
+
+    relation_fields = (
+        "source",
+        "pages",
+        "flows",
+        "stories",
+        "fields",
+        "apis",
+        "models",
+        "features",
+        "docs",
+    )
+    for field in relation_fields:
+        value = entry.get(field)
+        if not value:
+            continue
+        refs = value if isinstance(value, list) else [value]
+        for ref in refs:
+            ref_id = str(ref).split("#")[0]
+            if "/" not in ref_id:
+                continue
+            try:
+                _split_id(ref_id)
+            except ValueError:
+                continue
+            _collect_related(ref_id, visited, collected)
+
+
+def cmd_related(full_id: str) -> int:
+    """Print all entries reachable from *full_id* through cross-references."""
+    try:
+        _split_id(full_id)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    collected: dict[str, list[dict[str, Any]]] = {}
+    _collect_related(full_id, set(), collected)
+
+    if not collected:
+        print(f"No related entries found for {full_id}")
+        return 0
+
+    for id_type in sorted(collected):
+        print(f"## {id_type}")
+        for item in collected[id_type]:
+            for key, value in item.items():
+                print(f"{key}:")
+                _pretty_print(value, indent=1)
+        print()
+    return 0
+
+
+def cmd_create(
+    full_id: str,
+    title: str | None,
+    path: str | None,
+    source: str | None,
+    relations: list[str],
+) -> int:
+    """Create or update a one-id entry."""
+    try:
+        id_type, name = _split_id(full_id)
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+    index = _load_index(id_type)
+    entry: dict[str, Any] = index.get(full_id, {})
+
+    if title:
+        entry["title"] = title
+    if path:
+        entry["path"] = path
+    if source:
+        entry["source"] = source
+
+    # Relations are stored as simple list values under the inferred type key.
+    for relation in relations:
+        try:
+            rel_type, _ = _split_id(relation)
+        except ValueError as exc:
+            print(f"ERROR: {exc}", file=sys.stderr)
+            return 1
+        plural = rel_type + "s"
+        existing = entry.setdefault(plural, [])
+        if relation not in existing:
+            existing.append(relation)
+
+    index[full_id] = entry
+    _save_index(id_type, index)
+    print(f"Created/updated {full_id}")
+    return 0
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Lincoln one-id index manager")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    lookup_parser = subparsers.add_parser("lookup", help="Look up an ID across all indexes")
+    lookup_parser.add_argument("id", help="Full ID (e.g. page/checkout-cart)")
+
+    list_parser = subparsers.add_parser("list", help="List indexed IDs")
+    list_parser.add_argument("--type", help=f"Filter by type ({', '.join(TYPE_TO_FILE)})")
+
+    related_parser = subparsers.add_parser("related", help="Show entries related to an ID")
+    related_parser.add_argument("id", help="Full ID (e.g. feature/checkout-redesign)")
+
+    create_parser = subparsers.add_parser("create", help="Create or update an ID entry")
+    create_parser.add_argument("id", help="Full ID (e.g. page/checkout-cart)")
+    create_parser.add_argument("--title", help="Human-readable title")
+    create_parser.add_argument("--path", help="Artifact path (repo-relative)")
+    create_parser.add_argument("--source", help="Source document ID or URL fragment")
+    create_parser.add_argument(
+        "--relation",
+        action="append",
+        default=[],
+        help="Related full ID (can be repeated)",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_argument_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "lookup":
+        return cmd_lookup(args.id)
+    if args.command == "list":
+        return cmd_list(args.type)
+    if args.command == "related":
+        return cmd_related(args.id)
+    if args.command == "create":
+        return cmd_create(args.id, args.title, args.path, args.source, args.relation)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/framework/scripts/lincoln_index.py

@@ -175,8 +175,13 @@ def build_package_data(
 
     # Build nav groups preserving scan order.
     groups: dict[str, list[dict[str, Any]]] = {}
+    meta_warnings: list[str] = []
     for rel in sorted(page_data):
         entry = page_data[rel]
+        if not entry.get("nav_label"):
+            meta_warnings.append(f"{rel}: missing <meta name=\"nav-label\">")
+        if not entry.get("uid"):
+            meta_warnings.append(f"{rel}: missing <meta name=\"doc-uid\"> or <meta name=\"page-uid\">")
         group_name = entry.get("group") or entry.get("nav_group") or "Docs"
         groups.setdefault(group_name, []).append(
             {
@@ -200,6 +205,11 @@ def build_package_data(
             }
         )
 
+    if meta_warnings:
+        print("WARN: pages with incomplete portal meta tags:", file=sys.stderr)
+        for warning in meta_warnings:
+            print(f"  - {warning}", file=sys.stderr)
+
     nav = [{"group": g, "items": items} for g, items in groups.items()]
 
     return {

package/framework/scripts/lincoln_prd.py

@@ -136,23 +136,22 @@ def current_version(package_root: Path | None = None, *, args: argparse.Namespac
     return version
 
 
-def _render_prd_html(title: str, version: str, markdown: str) -> str:
+def _render_prd_html(title: str, version: str, markdown: str, package_root: Path) -> str:
     """Wrap legacy Markdown PRD content in the page-doc HTML template."""
-    template_path = PROJECT_ROOT / ".claude" / "templates" / "issue-package" / "page-doc.html.tpl"
-    if not template_path.exists():
-        return markdown
-    template = template_path.read_text(encoding="utf-8")
-    replacements = {
-        "{TITLE}": title,
-        "{NAV_GROUP}": "Docs",
-        "{VERSION}": version,
-        "{STAGE}": "clarify",
-        "{UID}": "",
-        "{MARKDOWN_SOURCE}": markdown,
-    }
-    for placeholder, value in replacements.items():
-        template = template.replace(placeholder, value)
-    return template
+    from scripts import lincoln_render
+
+    return lincoln_render.render_page(
+        stage_id="clarify",
+        target="{process_slug}/pages/docs/prd.html",
+        title=title,
+        nav_label=title,
+        nav_group="Docs",
+        version=version,
+        uid="prd",
+        stage_mark="clarify",
+        markdown_source=markdown,
+        extra_variables={"process_slug": package_root.name},
+    )
 
 
 def migrate(
@@ -187,7 +186,7 @@ def migrate(
         # Avoid duplicating the version marker once the template injects it.
         content = VERSION_COMMENT_RE.sub("", content, count=1).strip("\n")
 
-    html = _render_prd_html("PRD", version, content)
+    html = _render_prd_html("PRD", version, content, root)
 
     target_path.parent.mkdir(parents=True, exist_ok=True)
     atomic_write_text(target_path, html)