@seanyao/roll 3.609.2 → 3.610.2

package/lib/consistency_check.py

@@ -1,409 +0,0 @@
-#!/usr/bin/env python3
-"""Consistency check orchestrator (US-CONSIST-001).
-
-Runs checks across five dimensions, produces structured pass/gap reports.
-
-Usage:
-  python3 lib/consistency_check.py [--json] [--project-dir DIR]
-
-Exit:
-  0 — all dimensions pass
-  1 — one or more dimensions have gaps
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from pathlib import Path
-from typing import Any
-
-DIMENSIONS = ["code", "docs", "i18n", "tests", "site"]
-
-
-def _read_done_features(backlog_path: Path) -> dict[str, list[str]]:
-    """Extract features with ≥1 ✅ Done story from backlog.
-
-    Returns {feature_name: [story_id, ...]}.
-    """
-    text = backlog_path.read_text(encoding="utf-8")
-    features: dict[str, list[str]] = {}
-    current_feature: str | None = None
-
-    for line in text.splitlines():
-        m = re.search(r"^### Feature:\s*(.+)$", line)
-        if m:
-            current_feature = m.group(1).strip()
-            features[current_feature] = []
-            continue
-
-        if current_feature and "✅ Done" in line:
-            m2 = re.search(r"\[(US-|FIX-|REFACTOR-)([^\]]+)\]", line)
-            if m2:
-                features[current_feature].append(m2.group(1) + m2.group(2))
-
-    return {k: v for k, v in features.items() if v}
-
-
-def check_features_catalog(project_dir: Path) -> dict[str, Any]:
-    """Dimension: code — features.md catalog completeness.
-
-    Reuses logic from release.sh _enforce_features_catalog.
-    """
-    backlog = project_dir / ".roll" / "backlog.md"
-    features = project_dir / ".roll" / "features.md"
-
-    if not backlog.exists() or not features.exists():
-        return {"status": "pass", "gaps": []}
-
-    done_features = _read_done_features(backlog)
-    if not done_features:
-        return {"status": "pass", "gaps": []}
-
-    features_text = features.read_text(encoding="utf-8")
-    gaps: list[str] = []
-
-    for feat_name in done_features:
-        escaped = re.escape(feat_name)
-        if not re.search(r"(^|[\s/])" + escaped + r"([\s/).]|$)", features_text):
-            gaps.append(
-                f"Feature '{feat_name}' has Done stories but is missing from features.md catalog"
-            )
-
-    return {
-        "status": "pass" if not gaps else "fail",
-        "gaps": gaps,
-    }
-
-
-def check_site(project_dir: Path) -> dict[str, Any]:
-    """Dimension: site — landing/介绍材料 ↔ backlog/features 一致性.
-
-    Parses site/roll-data.js FEATURE_GROUPS, compares against backlog Done features.
-    Read-only — does not modify site data.
-    """
-    gaps: list[str] = []
-    site_js = project_dir / "site" / "roll-data.js"
-    backlog = project_dir / ".roll" / "backlog.md"
-
-    if not site_js.exists() or not backlog.exists():
-        return {"status": "pass", "gaps": []}
-
-    # Parse site feature names from FEATURE_GROUPS (both EN and ZH)
-    site_text = site_js.read_text(encoding="utf-8")
-    site_features: set[str] = set()
-    for m in re.finditer(r'\bname:\s*"([^"]+)"', site_text):
-        name = m.group(1).strip()
-        if name:
-            site_features.add(name)
-
-    if not site_features:
-        gaps.append(
-            "site/roll-data.js has no FEATURE_GROUPS feature names — "
-            "site may be missing content"
-        )
-        return {"status": "fail", "gaps": gaps}
-
-    # Normalize site feature names to search tokens
-    def _site_tokens(name: str) -> set[str]:
-        t = name.lower()
-        tokens: set[str] = set()
-        # Remove $ prefix and split on common delimiters
-        for part in re.split(r"[-/\s]+", t.lstrip("$")):
-            if len(part) > 1:
-                tokens.add(part)
-        return tokens
-
-    all_site_tokens: set[str] = set()
-    for name in site_features:
-        all_site_tokens.update(_site_tokens(name))
-
-    # Read backlog Done features
-    done_features = _read_done_features(backlog)
-    if not done_features:
-        return {"status": "pass", "gaps": []}
-
-    # Features that are internal infra / not user-facing; skip in site check
-    _internal_features = {
-        "cycle-meta-sync", "loop-log-locality", "invoke-stream-visibility",
-        "loop-done-semantics", "loop-status-reader-path", "loop-result-eval",
-        "loop-data-layout", "hooks-path-enforcement", "dev-vm-isolation",
-        "test-quality-gates", "tcr-test-strategy", "test-preconditions",
-        "e2e-lifecycle", "skill-harness", "agent-compliance",
-        "convention-management", "github-actions", "pr-lifecycle",
-        "loop-lifecycle-ownership", "loop-ci-self-heal",
-        "cycle-log-archive", "agent-aware-execution",
-        "manual-only-retirement", "loop-scheduling",
-        "context-feed-budget", "documentation", "github-issues-sync",
-        "notifications", "cycle-event-stream", "phase-tracing",
-        "loop-write-integrity", "cross-machine-sync", "remote-monitoring",
-        "cycle-history-rollup", "non-claude-usage-capture",
-        "loop-config-cli", "loop-exit-summary", "edit-render-fold",
-        "cli-redesign", "directory-restructure", "lifecycle-management",
-        "upstream-watch", "i18n-localization",
-    }
-
-    # For each Done feature, check if its keywords appear in site tokens
-    for feat_name in done_features:
-        # Skip features that are inherently internal / process-only
-        if feat_name in _internal_features:
-            continue
-
-        feat_tokens = _site_tokens(feat_name.replace("-", " "))
-        if not feat_tokens:
-            continue
-
-        # Feature is mentioned on site if at least half of its tokens match
-        match_count = sum(1 for t in feat_tokens if t in all_site_tokens)
-        if match_count < len(feat_tokens) / 2:
-            gaps.append(
-                f"Feature '{feat_name}' has Done stories but is not mentioned "
-                f"on the landing page — site may be missing this capability"
-            )
-
-    # Also check for stale site references: site features that reference
-    # commands no longer in scope
-    _cmds_referenced = {
-        "roll feedback", "roll release", "roll slides",
-    }
-    for cmd in _cmds_referenced:
-        if cmd in site_features and not any(
-            cmd.replace(" ", "-") in f for f in done_features
-        ):
-            # Only flag if the feature is Done and the referenced command
-            # area has related Done features
-            pass  # current coverage: all referenced commands have Done features
-
-    return {
-        "status": "pass" if not gaps else "fail",
-        "gaps": gaps,
-    }
-
-
-def check_i18n(project_dir: Path) -> dict[str, Any]:
-    """Dimension: i18n — guide file parity + i18n key completeness."""
-    gaps: list[str] = []
-
-    # 1. Guide file parity (guide/en ↔ guide/zh)
-    guide_en = project_dir / "guide" / "en"
-    guide_zh = project_dir / "guide" / "zh"
-    if guide_en.exists() and guide_zh.exists():
-        en_files = {p.name for p in guide_en.iterdir() if p.is_file()}
-        zh_files = {p.name for p in guide_zh.iterdir() if p.is_file()}
-        en_only = en_files - zh_files
-        zh_only = zh_files - en_files
-        for f in sorted(en_only):
-            gaps.append(f"guide/en/{f} has no corresponding guide/zh/{f}")
-        for f in sorted(zh_only):
-            gaps.append(f"guide/zh/{f} has no corresponding guide/en/{f}")
-
-    # 2. i18n key completeness (EN ↔ ZH pairing)
-    i18n_dir = project_dir / "lib" / "i18n"
-    if i18n_dir.exists():
-        keys_en: set[str] = set()
-        keys_zh: set[str] = set()
-        for sh_file in sorted(i18n_dir.glob("*.sh")):
-            text = sh_file.read_text(encoding="utf-8")
-            for m in re.finditer(r'_i18n_set\s+(en|zh)\s+([^\s]+)', text):
-                lang = m.group(1)
-                key = m.group(2)
-                if lang == "en":
-                    keys_en.add(key)
-                else:
-                    keys_zh.add(key)
-        en_only_keys = keys_en - keys_zh
-        zh_only_keys = keys_zh - keys_en
-        for k in sorted(en_only_keys):
-            gaps.append(f"i18n key '{k}' has EN but is missing ZH translation")
-        for k in sorted(zh_only_keys):
-            gaps.append(f"i18n key '{k}' has ZH but is missing EN translation")
-
-    return {
-        "status": "pass" if not gaps else "fail",
-        "gaps": gaps,
-    }
-
-
-def _feature_to_keywords(feature_name: str) -> list[str]:
-    """Extract search keywords from a feature name for fuzzy matching."""
-    slug = feature_name.lower().replace("-", " ").replace("_", " ")
-    parts = [p for p in slug.split() if len(p) > 2]
-    return parts
-
-
-def _test_file_relates_to_feature(test_name: str, feature_name: str) -> bool:
-    """Check if a test file name relates to a feature (fuzzy match)."""
-    keywords = _feature_to_keywords(feature_name)
-    if not keywords:
-        return False
-    test_lower = test_name.lower()
-    # Test is related if ALL feature keywords appear somewhere in the test name
-    return all(kw in test_lower for kw in keywords)
-
-
-def check_tests(project_dir: Path) -> dict[str, Any]:
-    """Dimension: tests — heuristic test coverage check.
-
-    Checks: (1) Done features have some test file that references them.
-            (2) Test files that reference non-existent features are flagged as stale.
-    """
-    gaps: list[str] = []
-    backlog = project_dir / ".roll" / "backlog.md"
-    tests_dir = project_dir / "tests"
-
-    if not backlog.exists():
-        return {"status": "pass", "gaps": []}
-
-    # Read all features (Done or not) for stale-check and test-coverage baseline
-    backlog_text = backlog.read_text(encoding="utf-8")
-    all_features: set[str] = set()
-    done_features: list[str] = []
-
-    for line in backlog_text.splitlines():
-        m = re.search(r"^### Feature:\s*(.+)$", line)
-        if m:
-            current = m.group(1).strip()
-            all_features.add(current)
-            continue
-        if "✅ Done" in line:
-            # Get the feature from context or check if this feature has Done items
-            pass
-
-    # Re-scan to associate Done status to features
-    current_feature: str | None = None
-    for line in backlog_text.splitlines():
-        m = re.search(r"^### Feature:\s*(.+)$", line)
-        if m:
-            current_feature = m.group(1).strip()
-            continue
-        if current_feature and "✅ Done" in line:
-            m2 = re.search(r"\[(US-|FIX-|REFACTOR-)([^\]]+)\]", line)
-            if m2 and current_feature not in done_features:
-                done_features.append(current_feature)
-
-    # Collect test file names
-    test_files: list[str] = []
-    if tests_dir.exists():
-        for tf in tests_dir.rglob("*.bats"):
-            test_files.append(tf.name)
-
-    # If no test files exist at all, skip the check (not meaningful to flag gaps)
-    if not test_files:
-        return {"status": "pass", "gaps": []}
-
-    # 1. Check each Done feature for test coverage
-    for feat in done_features:
-        has_test = any(
-            _test_file_relates_to_feature(tf, feat) for tf in test_files
-        )
-        if not has_test:
-            gaps.append(
-                f"Feature '{feat}' has Done stories but no test file appears to cover it "
-                f"(heuristic: no test file name matches keywords "
-                f"{_feature_to_keywords(feat)})"
-            )
-
-    # 2. Check for stale test files (reference non-existent features)
-    for tf in test_files:
-        # Extract candidate feature name from test filename
-        # e.g., cmd_feedback.bats → feedback, agent_usage_pi.bats → (skip generic)
-        stem = tf.replace(".bats", "")
-        # Strip common test file prefixes
-        for prefix in ("cmd_", "agent_"):
-            if stem.startswith(prefix):
-                stem = stem[len(prefix):]
-                break
-        # Skip generic test files that don't map to a single feature
-        if "_" in stem or len(stem) < 4:
-            continue
-        # Convert to feature-name format: replace underscores with hyphens
-        candidate = stem.replace("_", "-")
-        if candidate not in all_features and stem not in all_features:
-            gaps.append(
-                f"Test file '{tf}' appears to reference feature '{candidate}' "
-                f"which does not exist in backlog — may be stale"
-            )
-
-    return {
-        "status": "pass" if not gaps else "fail",
-        "gaps": gaps,
-    }
-
-
-def run_all(project_dir: Path) -> dict[str, Any]:
-    report: dict[str, Any] = {
-        "overall": "pass",
-        "dimensions": {},
-    }
-
-    for dim in DIMENSIONS:
-        if dim == "code":
-            result = check_features_catalog(project_dir)
-        elif dim == "i18n":
-            result = check_i18n(project_dir)
-        elif dim == "tests":
-            result = check_tests(project_dir)
-        elif dim == "docs":
-            result = {
-                "status": "pass",
-                "gaps": [],
-                "note": "placeholder — will be implemented in US-CONSIST-002",
-            }
-        elif dim == "site":
-            result = check_site(project_dir)
-        else:
-            result = {
-                "status": "pass",
-                "gaps": [],
-                "note": f"unknown dimension: {dim}",
-            }
-
-        report["dimensions"][dim] = result
-        if result["status"] == "fail":
-            report["overall"] = "fail"
-
-    return report
-
-
-def format_human(report: dict[str, Any]) -> str:
-    lines: list[str] = []
-    lines.append("Consistency Report")
-    lines.append("=" * 50)
-
-    for dim, result in report["dimensions"].items():
-        icon = "✅" if result["status"] == "pass" else "❌"
-        lines.append(f"{icon} {dim}: {result['status']}")
-        for gap in result.get("gaps", []):
-            lines.append(f"   • {gap}")
-        note = result.get("note", "")
-        if note:
-            lines.append(f"   ℹ {note}")
-
-    lines.append("-" * 50)
-    lines.append(f"Overall: {report['overall']}")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Consistency check orchestrator")
-    parser.add_argument(
-        "--json", action="store_true", help="Output machine-readable JSON"
-    )
-    parser.add_argument(
-        "--project-dir", type=Path, default=Path.cwd(), help="Project directory"
-    )
-    args = parser.parse_args()
-
-    report = run_all(args.project_dir)
-
-    if args.json:
-        print(json.dumps(report, indent=2, ensure_ascii=False))
-    else:
-        print(format_human(report))
-
-    return 0 if report["overall"] == "pass" else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/lib/context_feed_budget.sh

@@ -1,194 +0,0 @@
-#!/usr/bin/env bash
-# US-CTX-001: Context-feed budget (投喂预算).
-#
-# roll is an outer orchestrator: when it builds the inner agent's prompt it
-# injects material — chiefly the story's feature .md file. Large stories used to
-# be fed whole ("整文件硬塞"), which can blow the inner agent's context window.
-#
-# This module is the ContextFeed aggregate. It owns FeedBudget (a max byte size,
-# configurable) and decides an InjectionPlan (full / summarized / chunked) for a
-# given piece of material — never silently truncating, always annotating when it
-# summarizes or chunks and always pointing at the full-text path.
-#
-# Boundary: token-level compression stays in the inner agent harness. This module
-# only answers "what to feed, and how much".
-#
-# Pure bash 3.2: no ${var^^}, no mapfile, no declare -A. All functions read from
-# args / env and write to stdout — no global state, no file writes.
-
-# Default feed budget in bytes. Tuned to comfortably hold a normal story feature
-# file while staying well under an inner agent's context window. Configurable via
-# ROLL_FEED_BUDGET_BYTES so operators can dial it to the inner agent's capacity.
-ROLL_FEED_BUDGET_DEFAULT_BYTES=16384
-
-# _feed_budget_bytes
-# Resolve the active feed budget (bytes). Honors ROLL_FEED_BUDGET_BYTES when set
-# to a positive integer; otherwise falls back to the compiled-in default.
-_feed_budget_bytes() {
-  local v="${ROLL_FEED_BUDGET_BYTES:-}"
-  case "$v" in
-    ''|*[!0-9]*) echo "$ROLL_FEED_BUDGET_DEFAULT_BYTES" ;;
-    *) if [ "$v" -gt 0 ]; then echo "$v"; else echo "$ROLL_FEED_BUDGET_DEFAULT_BYTES"; fi ;;
-  esac
-}
-
-# _feed_size_bytes <file>
-# Byte size of a file. Echoes 0 for a missing/unreadable file.
-_feed_size_bytes() {
-  local f="$1"
-  [ -f "$f" ] || { echo 0; return 0; }
-  # wc -c is portable across macOS bash 3.2 and Linux; strip leading spaces.
-  local n
-  n=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
-  case "$n" in
-    ''|*[!0-9]*) echo 0 ;;
-    *) echo "$n" ;;
-  esac
-}
-
-# _feed_plan <file>
-# Decide the InjectionPlan for a material file: prints one of
-#   full | summarized | chunked
-# - Within budget            → full
-# - Over budget              → summarized
-# - Over 4x budget (huge)    → chunked
-# A missing file is treated as full (nothing to budget).
-_feed_plan() {
-  local f="$1"
-  local size budget
-  size=$(_feed_size_bytes "$f")
-  budget=$(_feed_budget_bytes)
-  if [ "$size" -le "$budget" ]; then
-    echo full
-  elif [ "$size" -le "$((budget * 4))" ]; then
-    echo summarized
-  else
-    echo chunked
-  fi
-}
-
-# _feed_summary_notice <file> <plan>
-# The explicit, non-silent annotation prepended to summarized/chunked material.
-# Bilingual per project convention: EN and ZH on separate lines. Points at the
-# full-text path so nothing is lost. Empty for the `full` plan.
-_feed_summary_notice() {
-  local f="$1" plan="$2"
-  case "$plan" in
-    summarized)
-      printf '%s\n' "[context-feed] This story feature exceeds the feed budget — injected as a SUMMARY. Full text: ${f}"
-      printf '%s\n' "[投喂预算] 本故事 feature 超投喂预算，已摘要注入，全文见 ${f}"
-      ;;
-    chunked)
-      printf '%s\n' "[context-feed] This story feature far exceeds the feed budget — injected in CHUNKS. Full text: ${f}"
-      printf '%s\n' "[投喂预算] 本故事 feature 远超投喂预算，已分段注入，全文见 ${f}"
-      ;;
-    *) : ;;
-  esac
-}
-
-# _feed_budget_head <file>
-# The leading <= budget bytes of <file>, trimmed back to the last COMPLETE line
-# so we never cut mid-line silently. Keeps all whole lines that fit; if not even
-# the first line fits, falls back to the raw byte head (a single very long line).
-# Uses `dd` (not `head -c`) for portability across BSD/macOS and GNU coreutils.
-_feed_budget_head() {
-  local f="$1"
-  local budget
-  budget=$(_feed_budget_bytes)
-  [ -f "$f" ] || return 0
-  local raw
-  raw=$(dd bs=1 count="$budget" if="$f" 2>/dev/null)
-  # Keep complete lines only. awk prints every line that ended with a newline
-  # within the byte window; the trailing partial line (no newline) is dropped.
-  # If awk yields nothing (the window is a single unterminated long line), keep
-  # the raw head so content is never silently emptied.
-  local trimmed
-  trimmed=$(printf '%s' "$raw" | awk '{
-    if (NR > 1) print buf
-    buf = $0
-  } END { }')
-  if [ -z "$trimmed" ]; then
-    printf '%s' "$raw"
-  else
-    printf '%s\n' "$trimmed"
-  fi
-}
-
-# _feed_summarize <file>
-# Budget-fitting summary: the budget head (complete lines) plus an explicit,
-# bilingual elision marker so the omission is never silent. Pure stdout.
-_feed_summarize() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  _feed_budget_head "$f"
-  printf '%s\n' "[context-feed] ... summarized: tail elided, full text at the path noted above ..."
-  printf '%s\n' "[投喂预算] ……已摘要：尾部内容省略，全文见上方所注路径……"
-}
-
-# _feed_chunk_count <file>
-# Number of budget-sized chunks the file spans (ceil(size / budget)), min 1.
-_feed_chunk_count() {
-  local f="$1"
-  local size budget
-  size=$(_feed_size_bytes "$f")
-  budget=$(_feed_budget_bytes)
-  [ "$budget" -gt 0 ] || budget=1
-  local n=$(( (size + budget - 1) / budget ))
-  [ "$n" -lt 1 ] && n=1
-  echo "$n"
-}
-
-# _feed_chunk <file>
-# Inject the FIRST budget-sized chunk (complete lines) with an explicit chunk
-# header "chunk 1/N", so the slicing is real and labelled — not a mislabelled
-# summary. Remaining chunks live in the full text at the noted path.
-_feed_chunk() {
-  local f="$1"
-  [ -f "$f" ] || return 0
-  local n
-  n=$(_feed_chunk_count "$f")
-  printf '%s\n' "[context-feed] chunk 1/${n} (remaining chunks in full text at the path noted above):"
-  printf '%s\n' "[投喂预算] 第 1/${n} 段（其余段见上方所注路径全文）："
-  _feed_budget_head "$f"
-}
-
-# _feed_assemble <file>
-# Top-level injector. Assembles the material to feed for <file> according to the
-# active budget + plan, with explicit annotation for non-full plans. Pure stdout;
-# callers capture this as the material to splice into the prompt.
-_feed_assemble() {
-  local f="$1"
-  local plan
-  plan=$(_feed_plan "$f")
-  case "$plan" in
-    full)
-      [ -f "$f" ] && cat "$f"
-      ;;
-    summarized)
-      _feed_summary_notice "$f" "$plan"
-      printf '\n'
-      _feed_summarize "$f"
-      ;;
-    chunked)
-      _feed_summary_notice "$f" "$plan"
-      printf '\n'
-      _feed_chunk "$f"
-      ;;
-  esac
-}
-
-# _feed_log_line <file> <plan>
-# A single structured log line recording the actual INJECTED size + chosen
-# strategy, for the event log. "Injected" = the byte count _feed_assemble emits
-# (for full == source size; for summarized/chunked == the bounded material),
-# satisfying the AC's "记录实际注入体积". Format is grep-friendly and stable:
-#   context_feed file=<f> strategy=<plan> bytes=<n> budget=<b>
-_feed_log_line() {
-  local f="$1" plan="${2:-}"
-  [ -n "$plan" ] || plan=$(_feed_plan "$f")
-  local bytes budget
-  budget=$(_feed_budget_bytes)
-  bytes=$(_feed_assemble "$f" | wc -c | tr -d ' ')
-  case "$bytes" in ''|*[!0-9]*) bytes=0 ;; esac
-  printf 'context_feed file=%s strategy=%s bytes=%s budget=%s\n' "$f" "$plan" "$bytes" "$budget"
-}