@seanyao/roll 2026.518.4 → 2026.519.2

package/conventions/global/AGENTS.md

@@ -44,12 +44,12 @@
     draft with user. Do not write code until approved.
   - Before claiming completion: verify in the target environment mentioned by
     user (e.g., specific CLI tool, remote server, hardware platform).
-- **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
+- **Workspace**: `.roll/backlog.md` index. `.roll/features/` for details.
 - **Backlog descriptions** (US, FIX, REFACTOR, IDEA, PROPOSAL): one sentence in plain language.
   Say what changed and why it matters — not how it works internally.
   No file paths, function names, parameter lists, or architecture jargon.
   `depends-on:` and `manual-only:` functional tags are allowed; `Domain:` annotation tags are not.
-  Technical details and AC go in `docs/features/`.
+  Technical details and AC go in `.roll/features/`.
   A well-written BACKLOG description can be used directly as a CHANGELOG entry.
 - **Convention layering**: project-level convention files extend the global SOT — see §9 below.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
@@ -101,10 +101,10 @@ Confirm each phase clean before proceeding to the next.
 - Icons: Lucide React.
 
 ## 8. Where to Look
-- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
-- **Story details**: `docs/features/` — AC, implementation specs, dependencies
-- **Design decisions**: `docs/domain/` — DDD models, architecture records
-- When `docs/domain/` or `docs/features/` don't exist yet, run `$roll-doc` to bootstrap.
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records
+- When `.roll/domain/` or `.roll/features/` don't exist yet, run `$roll-doc` to bootstrap.
 
 ## 9. Convention Architecture
 

package/conventions/templates/backend-service/AGENTS.md

@@ -29,9 +29,9 @@ src/
 ## 4. Discipline
 - **TCR**: Mandatory.
 - **Security**: Input validation (zod), Rate limiting, Secrets rotation.
-- **Workspace**: `BACKLOG.md` + `docs/features/`.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
 ## 5. Where to Look
-- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
-- **Story details**: `docs/features/` — AC, implementation specs, dependencies
-- **Design decisions**: `docs/domain/` — DDD models, architecture records
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records

package/conventions/templates/cli/AGENTS.md

@@ -31,9 +31,9 @@ tests/
 ## 4. Discipline
 - **TCR**: Mandatory.
 - **Distribution**: `bin` in `package.json`, test `npm i -g`.
-- **Workspace**: `BACKLOG.md` + `docs/features/`.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
 ## 5. Where to Look
-- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
-- **Story details**: `docs/features/` — AC, implementation specs, dependencies
-- **Design decisions**: `docs/domain/` — DDD models, architecture records
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records

package/conventions/templates/frontend-only/AGENTS.md

@@ -28,9 +28,9 @@ src/
 ## 4. Discipline
 - **TCR**: Mandatory.
 - **Testing**: Unit (hooks/logic) >80%, E2E (Playwright).
-- **Workspace**: `BACKLOG.md` + `docs/features/`.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
 ## 5. Where to Look
-- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
-- **Story details**: `docs/features/` — AC, implementation specs, dependencies
-- **Design decisions**: `docs/domain/` — DDD models, architecture records
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records

package/conventions/templates/fullstack/AGENTS.md

@@ -31,9 +31,9 @@ api/
 ## 4. Discipline
 - **TCR**: Mandatory.
 - **Testing**: Unit >80%, E2E for critical flows.
-- **Workspace**: `BACKLOG.md` + `docs/features/`.
+- **Workspace**: `.roll/backlog.md` + `.roll/features/`.
 
 ## 5. Where to Look
-- **Domain model**: `docs/domain/context-map.md` — Bounded Contexts and relationships
-- **Story details**: `docs/features/` — AC, implementation specs, dependencies
-- **Design decisions**: `docs/domain/` — DDD models, architecture records
+- **Domain model**: `.roll/domain/context-map.md` — Bounded Contexts and relationships
+- **Story details**: `.roll/features/` — AC, implementation specs, dependencies
+- **Design decisions**: `.roll/domain/` — DDD models, architecture records

package/lib/roll-backlog.py

@@ -2,7 +2,7 @@
 """
 roll-backlog — v2 terminal view for `roll backlog`.
 
-Parses BACKLOG.md and renders items grouped by type:
+Parses .roll/backlog.md and renders items grouped by type:
   Bug Fixes (red) · User Stories (blue) · Refactors (amber) · Ideas (dim)
 
 In-progress items get a ⏵ purple marker.
@@ -215,7 +215,7 @@ def main() -> None:
     no_color = "--no-color" in args or not sys.stdout.isatty() or os.getenv("NO_COLOR")
     rr.USE_COLOR = not no_color
 
-    backlog = "BACKLOG.md"
+    backlog = ".roll/backlog.md"
     if not demo and not os.path.isfile(backlog):
         print(f"Error: {backlog} not found — run 'roll init' first", file=sys.stderr)
         sys.exit(1)
@@ -244,7 +244,7 @@ def _write_demo(path: str) -> None:
 ### Feature: autonomous-evolution
 | Story | Description | Status |
 |-------|-------------|--------|
-| [US-AUTO-042](docs/features/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
+| [US-AUTO-042](.roll/features/autonomous-evolution.md) | Loop cost telemetry — write model and token data per cycle | 📋 Todo |
 
 ## ♻️ Refactor
 | ID | Description | Status |

package/lib/roll-brief.py

@@ -2,7 +2,7 @@
 """
 roll-brief — v2 terminal view for `roll brief`.
 
-Parses the latest docs/briefs/<date>.md and renders it as three sections:
+Parses the latest .roll/briefs/<date>.md and renders it as three sections:
   SUMMARY    — eyebrow + shipped/watch/decide counts
   HIGHLIGHTS — completed story list
   DECIDE     — action-required items with D1/D2/... numbering
@@ -269,7 +269,7 @@ def main() -> None:
     no_color = "--no-color" in args or not sys.stdout.isatty() or os.getenv("NO_COLOR")
     rr.USE_COLOR = not no_color
 
-    briefs_dir = "docs/briefs"
+    briefs_dir = ".roll/briefs"
     briefs = sorted(
         f for f in os.listdir(briefs_dir) if f.endswith(".md")
     ) if os.path.isdir(briefs_dir) else []

package/lib/roll-help.py

@@ -45,7 +45,7 @@ AUTONOMY = [
 ]
 
 PROJECT = [
-    ("init",      "",              "create AGENTS.md + BACKLOG.md + docs/",              "初始化项目工作流文件",         False),
+    ("init",      "",              "create AGENTS.md + .roll/backlog.md + docs/",              "初始化项目工作流文件",         False),
     ("status",    "",              "show current state and drift",                        "显示当前状态和漂移项",         False),
     ("agent",     "[use <name>]",  "per-project agent selection",                        "切换项目 agent",             False),
     ("ci",        "[--wait]",      "show or wait for current commit's CI status",         "查看 / 等待 CI 状态",        False),
@@ -132,9 +132,9 @@ def render(version: str) -> None:
     for cmd, zh in EXAMPLES:
         print("  " + c("blue", cmd) + "  " + c("dim", zh))
     print()
-    print("  " + c("dim", "docs: ") + c("blue", "github.com/seanyao/Roll") +
+    print("  " + c("dim", "docs: ") + c("blue", "github.com/seanyao/roll") +
           c("muted", "  ·  ") +
-          c("dim", "issues: ") + c("blue", "github.com/seanyao/Roll/issues"))
+          c("dim", "issues: ") + c("blue", "github.com/seanyao/roll/issues"))
     print()
 
 # ════════════════════════════════════════════════════════════════════════════

package/lib/roll-home.py

@@ -116,6 +116,26 @@ def _launchd_svc_state(service: str, slug: str) -> str:
     except Exception:
         return "installed-off"
 
+def _read_plist_schedule(service: str, slug: str) -> Optional[Dict[str, int]]:
+    """FIX-063: read actual Minute/Hour from launchd plist (truth source).
+    Returns {'minute': N, 'hour': N|None} or None if plist missing.
+    Dashboard must reflect what launchd actually fires, not a hardcoded default.
+    """
+    label = f"com.roll.{service}.{slug}"
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"{label}.plist"
+    if not plist.exists():
+        return None
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return None
+    # Parse <key>Minute</key><integer>N</integer> (and Hour)
+    m = re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    h = re.search(r"<key>Hour</key>\s*<integer>(\d+)</integer>", text)
+    if not m:
+        return None
+    return {"minute": int(m.group(1)), "hour": int(h.group(1)) if h else None}
+
 def _dream_last_hours() -> Optional[int]:
     log = _shared_root() / "dream" / "log.md"
     if not log.exists():
@@ -145,7 +165,7 @@ def _peer_last() -> Optional[Tuple[str, int]]:
 
 def _backlog_counts() -> Tuple[int, int, int, str, str, str, int]:
     """(ideas, todo, in_progress, id, title, link, refactor_pending)."""
-    bl = Path("BACKLOG.md")
+    bl = Path(".roll/backlog.md")
     if not bl.exists():
         return (0, 0, 0, "", "", "", 0)
     ideas = todo = in_prog = refactors = 0
@@ -167,7 +187,7 @@ def _backlog_counts() -> Tuple[int, int, int, str, str, str, int]:
                 parts = [p.strip() for p in line.split("|")]
                 if len(parts) >= 4:
                     ip_title = parts[2][:60]
-                m2 = re.search(r"docs/features/[^\)]+", line)
+                m2 = re.search(r".roll/features/[^\)]+", line)
                 if m2:
                     ip_link = m2.group(0)
     return (ideas, todo, in_prog, ip_id, ip_title, ip_link, refactors)
@@ -179,13 +199,13 @@ def _alert_count(slug: str) -> int:
     return sum(1 for l in af.read_text(errors="ignore").splitlines() if l.startswith("# ALERT"))
 
 def _proposal_count() -> int:
-    p = Path("PROPOSALS.md")
+    p = Path(".roll/proposals.md")
     if not p.exists():
         return 0
     return sum(1 for l in p.read_text(errors="ignore").splitlines() if l.startswith("## PROPOSAL"))
 
 def _release_ready() -> bool:
-    briefs_dir = Path("docs/briefs")
+    briefs_dir = Path(".roll/briefs")
     if not briefs_dir.exists():
         return False
     try:
@@ -417,7 +437,7 @@ def render(d: Dict[str, Any]) -> None:
                   c("dim", "          run: ") + c("blue", "roll alert"))
         if proposals:
             print("  " + c("amber", "▤") + " " + c("amber", f"{proposals} PROPOSAL", bold=True) +
-                  c("dim", "      see: ") + c("blue", "PROPOSALS.md"))
+                  c("dim", "      see: ") + c("blue", ".roll/proposals.md"))
         if rr:
             print("  " + c("green", "✓") + " " + c("green", "Release ready", bold=True) +
                   c("dim", "    run: ") + c("blue", "roll release"))
@@ -469,12 +489,12 @@ def main() -> None:
             timestamp      = datetime.now().strftime("%H:%M"),
             state          = state,
             loop_state     = _launchd_svc_state("loop", slug),
-            loop_minute    = _ci("loop_minute", 38),
+            loop_minute    = (_read_plist_schedule("loop", slug) or {}).get("minute") or _ci("loop_minute", 38),
             loop_active_start = _ci("loop_active_start", 10),
             loop_active_end   = _ci("loop_active_end", 18),
             dream_state    = _launchd_svc_state("dream", slug),
-            dream_hour     = _ci("loop_dream_hour", 3),
-            dream_minute   = _ci("loop_dream_minute", 12),
+            dream_hour     = (_read_plist_schedule("dream", slug) or {}).get("hour") or _ci("loop_dream_hour", 3),
+            dream_minute   = (_read_plist_schedule("dream", slug) or {}).get("minute") or _ci("loop_dream_minute", 12),
             dream_last_hours = _dream_last_hours(),
             refactor_pending = refactor_pending,
             peer_last      = _peer_last(),

package/lib/roll-init.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+"""roll-init — v2 terminal view for `roll init` (US-VIEW-008)."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+_LIB_DIR = os.path.dirname(os.path.realpath(__file__))
+if _LIB_DIR not in sys.path:
+    sys.path.insert(0, _LIB_DIR)
+import roll_render
+from roll_render import c, row, COLS
+
+# ════════════════════════════════════════════════════════════════════════════
+# Demo data — 6 steps mirror cmd_init's actual phases.
+# AC text: detect → AGENTS.md → BACKLOG.md → docs/features/ → merge CLAUDE.md → link skills
+# Each entry: (label, [(op, filename)]) where op ∈ {"+", "~"}.
+# ════════════════════════════════════════════════════════════════════════════
+
+_DEMO_STEPS = [
+    ("Detect project type",          []),
+    ("Create AGENTS.md",             [("+", "AGENTS.md")]),
+    ("Create .roll/backlog.md",      [("+", ".roll/backlog.md")]),
+    ("Create .roll/features/",       [("+", ".roll/features/")]),
+    ("Merge existing CLAUDE.md",     [("~", "CLAUDE.md")]),
+    ("Link skills to AI clients",    [("+", "~/.claude/skills/roll-build"),
+                                      ("+", "~/.claude/skills/roll-fix")]),
+]
+
+_NEXT_STEPS = [
+    ("Edit .roll/backlog.md",     "open the backlog and add your first US"),
+    ("Run roll loop now",         "execute one cycle manually to test the flow"),
+    ("Enable loop scheduling",    "roll loop on  — let it run hourly"),
+]
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Render
+# ════════════════════════════════════════════════════════════════════════════
+
+def _divider(char: str = "─") -> None:
+    print(c("dim", char * min(COLS, 80)))
+
+
+def _op_marker(op: str) -> str:
+    if op == "+":
+        return c("green", "+", bold=True)
+    if op == "~":
+        return c("amber", "~", bold=True)
+    return c("dim", op)
+
+
+def render_demo(project_path: str = "~/myproject") -> None:
+    left  = "  " + c("blue", "INIT", bold=True) + c("dim", "  ·  ") + c("dim", "项目初始化")
+    right = c("dim", project_path) + "  "
+    print(row(left, right))
+    _divider()
+    print()
+
+    for i, (label, files) in enumerate(_DEMO_STEPS, start=1):
+        num  = c("dim", f"  {i}.")
+        icon = c("green", "✓")
+        print(f"{num} {icon}  {label}")
+        for op, fname in files:
+            mark = _op_marker(op)
+            color = "green" if op == "+" else "amber"
+            print("       " + mark + "  " + c(color, fname))
+
+    print()
+    _divider()
+    print("  " + c("green", "✓") + " " + c("green", "Project ready", bold=True))
+    print()
+    print("  " + c("pink", "NEXT", bold=True) + c("dim", "  ·  下一步"))
+    for i, (label, hint) in enumerate(_NEXT_STEPS, start=1):
+        num = c("dim", f"  {i}.")
+        print(f"{num} {c('fg', label, bold=True)}")
+        print("     " + c("dim", hint))
+    _divider("═")
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Entry point
+# ════════════════════════════════════════════════════════════════════════════
+
+def main() -> None:
+    ap = argparse.ArgumentParser(add_help=False)
+    ap.add_argument("--demo",     action="store_true")
+    ap.add_argument("--no-color", dest="no_color", action="store_true")
+    ap.add_argument("--en",       action="store_true")
+    ap.add_argument("--zh",       action="store_true")
+    args, _ = ap.parse_known_args()
+
+    if args.no_color or os.environ.get("NO_COLOR") or not sys.stdout.isatty():
+        roll_render.USE_COLOR = False
+
+    render_demo(project_path=os.getcwd())
+
+
+if __name__ == "__main__":
+    main()

package/lib/roll-loop-status.py

@@ -6,7 +6,7 @@ Reads (all per-project, slug = <basename>-<md5_6chars> of project root):
   $ROLL_SHARED_ROOT/loop/events-<slug>.ndjson   structured per-cycle events
   $ROLL_SHARED_ROOT/loop/cron-<slug>.log        wall-clock dur + cost per cycle
   $ROLL_SHARED_ROOT/loop/state-<slug>.yaml      idle | running | paused
-  ./BACKLOG.md                                   story id → description
+  ./.roll/backlog.md                                   story id → description
 
 Writes (stdout):
   Static 100-col colored print, EN/ZH paired rows. Designed for a 5-10s glance,
@@ -137,8 +137,8 @@ def load_state(slug: str) -> Dict[str, str]:
     return out
 
 def load_backlog(project_root: Optional[Path] = None) -> Dict[str, str]:
-    """Map story id → description from BACKLOG.md table rows."""
-    path = (project_root or Path()) / "BACKLOG.md"
+    """Map story id → description from .roll/backlog.md table rows."""
+    path = (project_root or Path()) / ".roll/backlog.md"
     if not path.exists():
         return {}
     out: Dict[str, str] = {}
@@ -414,7 +414,7 @@ def repair_orphan_cycles_from_git(cycles: List[Dict[str, Any]], git_merges: Dict
         if cy.get("outcome") in ("running", "unknown"):
             cy["outcome"] = "done"
         if m["pr"] and not cy.get("pr"):
-            cy["pr"] = f"https://github.com/seanyao/Roll/pull/{m['pr']}"
+            cy["pr"] = f"https://github.com/seanyao/roll/pull/{m['pr']}"
         # Fill stories when our existing sources didn't carry them. Filter
         # to ones that actually appear in BACKLOG so we don't pull in stray
         # tokens from the merge body (PR numbers, file paths, etc.).
@@ -688,7 +688,7 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
                  sum(1 for c0 in day_cycles if c0["outcome"] == "fail"),
                  now,
                  in_progress=(day_key == today_key and is_partial))
-        for cy in day_cycles:
+        for cy in reversed(day_cycles):
             cycle_row(cy, backlog)
         print()
 
@@ -701,11 +701,27 @@ def render(events, cron, state, backlog, *, days=3, lang="both", now=None,
           c("muted", "       ") +
           c("dim", "more   ") + c("blue", "roll loop --days 7"))
 
+def _read_plist_loop_minute() -> int:
+    """FIX-063: read actual loop Minute from launchd plist (truth source).
+    Falls back to 48 only when plist missing/unparseable.
+    """
+    import re as _re
+    slug = project_slug()
+    plist = Path(os.path.expanduser("~/Library/LaunchAgents")) / f"com.roll.loop.{slug}.plist"
+    if not plist.exists():
+        return 48
+    try:
+        text = plist.read_text(errors="ignore")
+    except Exception:
+        return 48
+    m = _re.search(r"<key>Minute</key>\s*<integer>(\d+)</integer>", text)
+    return int(m.group(1)) if m else 48
+
+
 def _next_cron_hint(state: Dict[str, str], zh: bool = False) -> str:
-    """Best-effort next-cron string. The real schedule lives in launchd/cron;
-    we only have access to last_run here, so we approximate to the next :48."""
+    """Compute next cron fire time from the actual launchd plist Minute (FIX-063)."""
     now = datetime.now().astimezone()
-    minute_target = 48  # bin/roll default; per-project may differ
+    minute_target = _read_plist_loop_minute()
     nxt = now.replace(minute=minute_target, second=0, microsecond=0)
     if nxt <= now:
         nxt += timedelta(hours=1)

package/lib/roll-plan-validate.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""
+US-ONBOARD-007: onboard-plan.yaml validator.
+
+Validates that a plan file produced by $roll-onboard is structurally complete,
+fresh (generated_at within 24h), and version-compatible with the consuming
+bin/roll. Called by `roll init --apply` before any side effects.
+
+Usage:
+    python3 roll-plan-validate.py <path-to-plan.yaml>
+
+Exit codes:
+    0   plan is valid
+    1   schema / required field error
+    2   plan is stale (generated_at > 24h)
+    3   plan version not supported
+    4   plan file unreadable / not YAML
+
+Error messages are written to stderr in both English and Chinese.
+
+Schema (v1):
+    version: 1
+    generated_at: ISO 8601 timestamp (UTC or with tz offset)
+    project_understanding:
+      type: backend-service | frontend-only | fullstack | cli
+      description: str
+      domains: [str]
+      key_modules: [str]
+    scope:
+      approved: [str]  # subset of {backlog, features, domain, briefs}
+      declined: [str]
+    include_existing: [str]
+    privacy:
+      gitignore_dot_roll: bool
+    sync_targets: [str]
+    enable_loop: bool
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+
+try:
+    import yaml  # PyYAML
+except ImportError:
+    print(
+        "[plan-validate] PyYAML not installed. Install with: pip install pyyaml\n"
+        "[plan-validate] PyYAML 未安装，请运行: pip install pyyaml",
+        file=sys.stderr,
+    )
+    sys.exit(4)
+
+
+SUPPORTED_VERSIONS = {1}
+MAX_AGE_HOURS = 24
+VALID_PROJECT_TYPES = {"backend-service", "frontend-only", "fullstack", "cli"}
+VALID_SCOPE_ITEMS = {"backlog", "features", "domain", "briefs"}
+
+
+def err(msg_en: str, msg_zh: str = "") -> None:
+    """Print bilingual error to stderr."""
+    print(f"[plan-validate] {msg_en}", file=sys.stderr)
+    if msg_zh:
+        print(f"[plan-validate] {msg_zh}", file=sys.stderr)
+
+
+def validate_required_top_level(plan: dict) -> list[str]:
+    """Return list of missing/invalid top-level fields."""
+    errors = []
+    required = ["version", "generated_at", "project_understanding", "scope", "privacy"]
+    for key in required:
+        if key not in plan:
+            errors.append(f"missing required field: {key}")
+    return errors
+
+
+def validate_version(plan: dict) -> list[str]:
+    v = plan.get("version")
+    if not isinstance(v, int):
+        return [f"version must be int, got {type(v).__name__}"]
+    if v not in SUPPORTED_VERSIONS:
+        return [f"version {v} not supported (supported: {sorted(SUPPORTED_VERSIONS)})"]
+    return []
+
+
+def validate_freshness(plan: dict) -> tuple[list[str], bool]:
+    """Returns (errors, is_stale). Stale uses exit code 2."""
+    raw = plan.get("generated_at")
+    if not raw:
+        return ["generated_at missing"], False
+    try:
+        if isinstance(raw, datetime):
+            ts = raw
+        else:
+            ts = datetime.fromisoformat(str(raw).replace("Z", "+00:00"))
+    except (ValueError, TypeError) as e:
+        return [f"generated_at not a valid ISO 8601 timestamp: {e}"], False
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    now = datetime.now(timezone.utc)
+    age = now - ts
+    if age > timedelta(hours=MAX_AGE_HOURS):
+        return [
+            f"plan is stale: generated {age.total_seconds() / 3600:.1f}h ago "
+            f"(max allowed: {MAX_AGE_HOURS}h)"
+        ], True
+    if age < timedelta(seconds=-300):
+        # Plan in future >5 min — clock skew or fabricated timestamp
+        return [
+            f"plan timestamp is in the future (clock skew?): generated_at={ts.isoformat()}"
+        ], False
+    return [], False
+
+
+def validate_project_understanding(plan: dict) -> list[str]:
+    errors = []
+    pu = plan.get("project_understanding")
+    if not isinstance(pu, dict):
+        return ["project_understanding must be a mapping"]
+    t = pu.get("type")
+    if t is None:
+        errors.append("project_understanding.type missing")
+    elif t not in VALID_PROJECT_TYPES:
+        errors.append(
+            f"project_understanding.type='{t}' not in {sorted(VALID_PROJECT_TYPES)}"
+        )
+    if "description" not in pu:
+        errors.append("project_understanding.description missing")
+    return errors
+
+
+def validate_scope(plan: dict) -> list[str]:
+    errors = []
+    scope = plan.get("scope")
+    if not isinstance(scope, dict):
+        return ["scope must be a mapping"]
+    approved = scope.get("approved", [])
+    if not isinstance(approved, list):
+        errors.append("scope.approved must be a list")
+    else:
+        for item in approved:
+            if item not in VALID_SCOPE_ITEMS:
+                errors.append(
+                    f"scope.approved contains unknown item '{item}' "
+                    f"(valid: {sorted(VALID_SCOPE_ITEMS)})"
+                )
+    return errors
+
+
+def validate_privacy(plan: dict) -> list[str]:
+    errors = []
+    privacy = plan.get("privacy")
+    if not isinstance(privacy, dict):
+        return ["privacy must be a mapping"]
+    g = privacy.get("gitignore_dot_roll")
+    if not isinstance(g, bool):
+        errors.append(
+            f"privacy.gitignore_dot_roll must be bool, got {type(g).__name__}"
+        )
+    return errors
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        err("usage: roll-plan-validate.py <plan.yaml>", "用法: roll-plan-validate.py <plan.yaml>")
+        return 4
+
+    path = Path(argv[1])
+    if not path.is_file():
+        err(f"plan file not found: {path}", f"未找到 plan 文件：{path}")
+        return 4
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            plan = yaml.safe_load(f)
+    except (yaml.YAMLError, OSError) as e:
+        err(f"failed to parse plan as YAML: {e}", "无法解析 plan YAML")
+        return 4
+
+    if not isinstance(plan, dict):
+        err("plan must be a top-level mapping", "plan 顶层必须是 mapping")
+        return 1
+
+    schema_errors: list[str] = []
+    schema_errors += validate_required_top_level(plan)
+    schema_errors += validate_version(plan)
+    schema_errors += validate_project_understanding(plan)
+    schema_errors += validate_scope(plan)
+    schema_errors += validate_privacy(plan)
+
+    freshness_errors, is_stale = validate_freshness(plan)
+
+    # Version errors take precedence — if version is wrong, the rest of the
+    # validation may be unreliable.
+    version_errors = [e for e in schema_errors if e.startswith("version")]
+    if version_errors:
+        for e in version_errors:
+            err(e)
+        return 3
+
+    if is_stale:
+        for e in freshness_errors:
+            err(e, "plan 已过期，请重新运行 $roll-onboard 生成新 plan")
+        return 2
+
+    all_errors = [e for e in schema_errors if not e.startswith("version")] + [
+        e for e in freshness_errors if not is_stale
+    ]
+    if all_errors:
+        for e in all_errors:
+            err(e)
+        return 1
+
+    # Valid — silent success (bash caller treats exit 0 as OK).
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))