aid-installer 1.1.0 → 2.0.0

package/dashboard/reader/derivation.py

@@ -16,11 +16,11 @@
 # MIGRATION STATUS (task-013 M6 cutover audit):
 #
 #   NORMALIZED (producer-emitted, feature-001 M1-M6 complete):
-#   - Running          -- M4: aid-interview, aid-specify, aid-plan, aid-detail,
+#   - Running          -- M4: aid-describe, aid-define, aid-specify, aid-plan, aid-detail,
 #                        aid-execute, aid-deploy (state-idle.md) emit at phase entry.
 #   - Paused-Awaiting-Input + Pause Reason -- M5: aid-specify (state-blocked.md,
 #                        state-spike.md), aid-execute (state-delivery-gate.md),
-#                        aid-interview (state-completion.md) emit on pause transitions.
+#                        aid-describe (state-completion.md) emit on pause transitions.
 #   - Blocked + Block Reason/Artifact -- M5: aid-execute (state-execute.md,
 #                        state-review.md), aid-execute (state-delivery-gate.md)
 #                        emit on impediment/failed-gate transitions.
@@ -60,7 +60,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
-from .models import KbBaseline, KbStatus, Lifecycle, PendingInput, SourceMode, TaskModel, TaskStatus
+from .models import DocFreshness, KbBaseline, KbStatus, Lifecycle, PendingInput, SourceMode, TaskModel, TaskStatus
 
 
 # ---------------------------------------------------------------------------
@@ -96,9 +96,10 @@ def _normalize_to_utc_ms(iso_str: str) -> Optional[int]:
 # FF-A2: git freshness check (task-064, LC-A2 reader subprocess)
 # ---------------------------------------------------------------------------
 
-# Allowed git verbs: ONLY rev-parse, symbolic-ref, log (read-only)
+# Allowed git verbs: ONLY rev-parse, symbolic-ref, log, merge-base (read-only)
+# merge-base added task-042 (f007): --is-ancestor comparison for per-doc freshness.
 # NEVER: fetch, pull, commit, checkout, reset, push, merge, rebase, add, rm
-_GIT_ALLOWED_VERBS = frozenset({"rev-parse", "symbolic-ref", "log"})
+_GIT_ALLOWED_VERBS = frozenset({"rev-parse", "symbolic-ref", "log", "merge-base"})
 
 # Degradation timeout (seconds) -- bounded read, never blocks indefinitely
 _GIT_TIMEOUT_S = 2
@@ -367,6 +368,228 @@ def derive_kb_status(
         return KbStatus.unknown
 
 
+# ---------------------------------------------------------------------------
+# f007 / task-042: per-doc freshness read
+# ---------------------------------------------------------------------------
+
+def derive_doc_freshness(kb_dir: Path, repo_root: Path) -> list[DocFreshness]:
+    """f007: Per-doc freshness read for all hand-authored primary/extension KB docs.
+
+    Same algorithm as kb-freshness-check.sh (task-040):
+      - Same doc routing (skip INDEX.md, README.md, STATE.md, meta, generated)
+      - Same absence gate (no approved_at_commit: -> unknown; no/empty sources: -> current)
+      - Same git verbs: git-log -1 --format=%H -- <src>  +  merge-base --is-ancestor
+      - Same fold rule: suspect > current > unknown
+      - Same degrade-to-unknown matrix (any git failure -> unknown, never false suspect)
+
+    Returns list[DocFreshness] sorted by doc path (same deterministic order as script).
+    Never raises (NFR7). No writes. No LLM. Read-only git only.
+
+    merge-base is in _GIT_ALLOWED_VERBS (added task-042; still read-only).
+    """
+    from .parsers import parse_doc_frontmatter, is_url_source
+
+    results: list[DocFreshness] = []
+
+    if not kb_dir.is_dir():
+        return results
+
+    # Collect docs: skip INDEX.md, README.md, STATE.md + meta + generated
+    # (same routing as build-kb-index.sh / lint-frontmatter.sh / kb-freshness-check.sh)
+    try:
+        candidate_paths = sorted(
+            p for p in kb_dir.iterdir()
+            if p.is_file() and p.suffix == ".md" and not p.name.startswith(".")
+        )
+    except OSError:
+        return results
+
+    # Always-skipped names
+    _SKIP_NAMES = {"INDEX.md", "README.md", "STATE.md"}
+
+    for doc_path in candidate_paths:
+        if doc_path.name in _SKIP_NAMES:
+            continue
+
+        # Check routing fields: kb-category and source
+        # Re-use parse_doc_frontmatter but we need the routing fields too.
+        # Read routing separately via a quick line-scan (same tolerance posture).
+        kb_cat, src_field = _read_routing_fields(doc_path)
+
+        if kb_cat == "meta":
+            continue
+        if src_field == "generated":
+            continue
+        # Only primary and extension with hand-authored (or absent) source
+        if kb_cat not in ("primary", "extension", ""):
+            continue
+
+        rel = doc_path.name  # relative path within kb_dir (top-level only)
+
+        # Parse frontmatter: approved_at_commit + sources
+        approved_at_commit, sources_list, sources_field_present = parse_doc_frontmatter(doc_path)
+
+        # Absence gate: missing/empty approved_at_commit -> unknown (never suspect)
+        if not approved_at_commit:
+            results.append(DocFreshness(doc=rel, verdict="unknown", suspect_sources=[]))
+            continue
+
+        # sources: absent or empty -> current (nothing to drift against)
+        if not sources_field_present or not sources_list:
+            results.append(DocFreshness(doc=rel, verdict="current", suspect_sources=[]))
+            continue
+
+        # Per-source staleness checks
+        n_current = 0
+        n_suspect = 0
+        n_unknown = 0
+        suspect_sources: list[str] = []
+
+        for entry in sources_list:
+            src_verdict = _check_source(entry, approved_at_commit, repo_root)
+            if src_verdict == "current":
+                n_current += 1
+            elif src_verdict == "suspect":
+                n_suspect += 1
+                suspect_sources.append(entry)
+            else:
+                n_unknown += 1
+
+        # Fold rule (identical to script)
+        if n_suspect > 0:
+            verdict = "suspect"
+        elif n_current > 0:
+            verdict = "current"
+        else:
+            verdict = "unknown"
+
+        results.append(DocFreshness(doc=rel, verdict=verdict, suspect_sources=suspect_sources))
+
+    return results
+
+
+def _read_routing_fields(doc_path: Path) -> tuple[str, str]:
+    """Read kb-category and source frontmatter scalars for routing.
+
+    Returns (kb_category, source_field). Absent fields return "".
+    Same degrade posture: any failure -> ("", "") -> treated as primary/hand-authored.
+    Never raises.
+    """
+    try:
+        raw = doc_path.read_bytes()
+        text = raw.decode("utf-8", errors="replace")
+    except OSError:
+        return "", ""
+
+    kb_cat = ""
+    src_field = ""
+    in_fm = False
+    fm_entered = False
+
+    for line in text.splitlines():
+        stripped_line = line.rstrip()
+        if stripped_line == "---":
+            if not fm_entered:
+                in_fm = True
+                fm_entered = True
+                continue
+            else:
+                break
+        if not in_fm:
+            break
+
+        m = re.match(r"^kb-category:\s*(.*)", stripped_line)
+        if m:
+            kb_cat = m.group(1).strip().strip('"').strip("'")
+            continue
+
+        m = re.match(r"^source:\s*(.*)", stripped_line)
+        if m:
+            src_field = m.group(1).strip().strip('"').strip("'")
+            continue
+
+    return kb_cat, src_field
+
+
+def _check_source(entry: str, approved_at_commit: str, repo_root: Path) -> str:
+    """Check one sources: entry against approved_at_commit.
+
+    Returns "current" | "suspect" | "unknown".
+    Same algorithm as check_source() in kb-freshness-check.sh:
+      - URL -> unknown (cannot git log a URL)
+      - Path/glob -> git log -1 --format=%H -- <entry>; empty -> unknown
+      - Compare with merge-base --is-ancestor C_src <approved_at_commit>
+        exit 0 -> current, exit 1 -> suspect, other -> unknown (never false suspect)
+
+    Uses the existing _GIT_TIMEOUT_S bound (same 2s limit as other git calls).
+    Never raises; any failure degrades to unknown.
+    """
+    from .parsers import is_url_source
+
+    # URL source -> unknown (cannot git log a URL)
+    if is_url_source(entry):
+        return "unknown"
+
+    # Path/glob source: get last-changed commit
+    c_src = _run_git_log_hash(repo_root, entry)
+    if c_src is None:
+        # Empty output (untracked / never existed) or git failure -> unknown
+        return "unknown"
+
+    # Compare: is C_src an ancestor of (or equal to) approved_at_commit?
+    return _run_merge_base_is_ancestor(repo_root, c_src, approved_at_commit)
+
+
+def _run_git_log_hash(repo_root: Path, pathspec: str) -> Optional[str]:
+    """Run: git -C <repo_root> log -1 --format=%H -- <pathspec>
+
+    Returns the commit SHA on success, None on every failure mode.
+    Same subprocess pattern as _run_git_log (bounded, no-shell).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "log", "-1", "--format=%H", "--", pathspec],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+        )
+        if result.returncode != 0:
+            return None
+        sha = result.stdout.strip()
+        return sha if sha else None
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def _run_merge_base_is_ancestor(repo_root: Path, c_src: str, baseline: str) -> str:
+    """Run: git -C <repo_root> merge-base --is-ancestor <c_src> <baseline>
+
+    Returns:
+      "current"  -- exit 0 (c_src is ancestor of baseline; source unchanged since approval)
+      "suspect"  -- exit 1 (c_src is NOT ancestor; source changed after approval)
+      "unknown"  -- any other exit code (bad object, git absent, timeout, etc.)
+
+    Uses merge-base verb which is now in _GIT_ALLOWED_VERBS (task-042).
+    Never raises; unexpected exit codes degrade to unknown (never a false suspect).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "merge-base", "--is-ancestor", c_src, baseline],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT_S,
+        )
+        if result.returncode == 0:
+            return "current"
+        elif result.returncode == 1:
+            return "suspect"
+        else:
+            # exit 128 (bad object), etc. -> unknown (never a false suspect)
+            return "unknown"
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return "unknown"
+
+
 # ---------------------------------------------------------------------------
 # SM-2: derive_lifecycle -- unified preferred + fallback entry point
 #

package/dashboard/reader/models.py

@@ -134,6 +134,21 @@ class KbBaseline:
     tip_date: Optional[str] = None
 
 
+@dataclass
+class DocFreshness:
+    """Per-doc freshness verdict (feature-007 f007, task-042).
+
+    Populated by derive_doc_freshness() in derivation.py; never persisted (NFR2).
+
+    doc:             doc relative path under .aid/knowledge/ (e.g. "architecture.md")
+    verdict:         "current" | "suspect" | "unknown"
+    suspect_sources: list of sources: entries that drifted (empty unless verdict=="suspect")
+    """
+    doc: str
+    verdict: str                        # "current" | "suspect" | "unknown"
+    suspect_sources: list[str] = field(default_factory=list)
+
+
 @dataclass
 class KbStateRef:
     """KB state reference (feature-007 DM-A1 extended KbStateRef).
@@ -150,6 +165,10 @@ class KbStateRef:
         status          -- FR32 5-state KbStatus (derived, never persisted; NFR2)
         summary_present -- True if <repo>/.aid/dashboard/kb.html exists (stat only)
         kb_baseline     -- {branch, tip_date} from .aid/settings.yml; None if unset/unparseable
+
+    New fields (feature-007 f007, task-042):
+        doc_freshness   -- per-doc freshness list [{doc, verdict, suspect_sources}, ...]
+        suspect_count   -- count of docs with verdict=="suspect" (badge rollup)
     """
     summary_approved: bool
     last_summary_date: Optional[str] = None  # from STATE.md "User Approved: yes (YYYY-MM-DD...)"
@@ -158,6 +177,9 @@ class KbStateRef:
     status: KbStatus = KbStatus.unknown      # FR32 5-state derived status
     summary_present: bool = False            # True if .aid/dashboard/kb.html exists
     kb_baseline: Optional[KbBaseline] = None # {branch, tip_date} or None
+    # feature-007 f007 new fields (task-042):
+    doc_freshness: list[DocFreshness] = field(default_factory=list)  # per-doc verdicts
+    suspect_count: int = 0                   # count of suspect docs (badge rollup)
 
 
 @dataclass

package/dashboard/reader/parsers.py

@@ -21,6 +21,7 @@ from typing import Optional
 from .models import (
     DeliverableRef,
     DeferredIssue,
+    DocFreshness,
     FeatureRef,
     Finding,
     KbBaseline,
@@ -415,6 +416,132 @@ def _parse_kb_doc_count(text: str) -> Optional[int]:
     return count if in_completeness else None
 
 
+# ---------------------------------------------------------------------------
+# f007 / task-042: per-doc frontmatter scan (sources: + approved_at_commit:)
+# ---------------------------------------------------------------------------
+
+_RE_FM_FENCE = re.compile(r"^---\s*$")
+_RE_URL = re.compile(r"^[a-z][a-z0-9+.\-]*://")
+
+
+def parse_doc_frontmatter(path: Path) -> tuple[Optional[str], list[str], bool]:
+    """Tolerant sources:/approved_at_commit: frontmatter scan for one KB doc.
+
+    Reads only the YAML frontmatter block (between the first pair of '---' lines).
+    Identical algorithm to the bash fm_scalar/fm_list/fm_sources_present helpers in
+    kb-freshness-check.sh; mirrors the Node twin in reader.mjs (byte-parity).
+
+    Returns:
+        (approved_at_commit, sources_list, sources_field_present)
+
+    approved_at_commit:
+        the trimmed scalar value, or None if absent/empty.
+    sources_list:
+        items from the sources: YAML list (inline or block); empty list if field
+        is absent, sources: [], or the value is not a list.
+    sources_field_present:
+        True if the sources: key was present (even as sources: []), False if absent.
+        Used to distinguish "sources: []" (-> current) from "no sources: field" (-> current too,
+        but noted separately for debugging; both map to current per the SPEC).
+
+    Never raises (NFR7). Handles:
+      - No frontmatter (no leading ---) -> (None, [], False)
+      - Inline list: sources: [a, b]
+      - Block list:  sources:\n  - a\n  - b
+      - Empty list:  sources: []  -> (approval, [], True)
+    """
+    if not path.is_file():
+        return None, [], False
+
+    try:
+        raw = path.read_bytes()
+        text = raw.decode("utf-8", errors="replace")
+    except OSError:
+        return None, [], False
+
+    approved_at_commit: Optional[str] = None
+    sources_list: list[str] = []
+    sources_field_present: bool = False
+
+    in_fm = False
+    fm_entered = False
+    in_sources_block = False
+
+    for line in text.splitlines():
+        if _RE_FM_FENCE.match(line):
+            if not fm_entered:
+                # Opening fence
+                in_fm = True
+                fm_entered = True
+                continue
+            else:
+                # Closing fence
+                break
+
+        if not in_fm:
+            # No opening fence yet -- not in frontmatter (or no frontmatter)
+            break
+
+        # Inside frontmatter block
+        stripped = line.rstrip()
+
+        if in_sources_block:
+            # Continuation of a block-style sources: list
+            m_item = re.match(r"^[ \t]+-[ \t]*(.*)", stripped)
+            if m_item:
+                item = m_item.group(1).strip().strip('"').strip("'")
+                if item:
+                    sources_list.append(item)
+                continue
+            else:
+                # Any non-item line ends the block
+                in_sources_block = False
+                # Fall through to check this line for other fields
+
+        # approved_at_commit: scalar
+        m_aac = re.match(r"^approved_at_commit:\s*(.*)", stripped)
+        if m_aac:
+            val = m_aac.group(1).strip().strip('"').strip("'")
+            approved_at_commit = val if val else None
+            continue
+
+        # sources: field
+        m_src = re.match(r"^sources:\s*(.*)", stripped)
+        if m_src:
+            sources_field_present = True
+            rest = m_src.group(1).strip()
+            if rest == "[]":
+                # Explicit empty inline list: sources: []
+                # sources_field_present already set; list stays []
+                continue
+            if not rest:
+                # Bare 'sources:' with nothing after -- block list follows
+                in_sources_block = True
+                continue
+            if rest.startswith("["):
+                # Inline list: [a, b, c]
+                inner = rest.lstrip("[").rstrip("]").strip()
+                if inner:
+                    for item in inner.split(","):
+                        item = item.strip().strip('"').strip("'")
+                        if item:
+                            sources_list.append(item)
+                continue
+            # Block list: next indented lines are items
+            in_sources_block = True
+            continue
+
+    return approved_at_commit, sources_list, sources_field_present
+
+
+def is_url_source(entry: str) -> bool:
+    """Return True if entry matches a URL scheme (^[a-z][a-z0-9+.-]*://).
+
+    Identical to kb-freshness-check.sh is_url() and the Node twin isUrlSource().
+    """
+    return bool(_RE_URL.match(entry))
+
+
 # ---------------------------------------------------------------------------
 # Prototype: REQUIREMENTS.md parser (work-overview header, delivery-002)
 # ---------------------------------------------------------------------------

package/dashboard/reader/reader.py

@@ -36,7 +36,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional, Union
 
-from .derivation import derive_kb_status
+from .derivation import derive_doc_freshness, derive_kb_status
 from .locator import enumerate_worktree_roots, locate_aid_root
 from .models import (
     DeferredIssue,
@@ -409,6 +409,11 @@ def _read_repo_full(
         kb_state.status = kb_status
         kb_state.kb_baseline = kb_baseline
 
+        # task-042: per-doc freshness (f007) -- additive; FF-A2 git_freshness_check retained
+        doc_freshness = derive_doc_freshness(kb_dir=loc.kb_dir, repo_root=root)
+        kb_state.doc_freshness = doc_freshness
+        kb_state.suspect_count = sum(1 for d in doc_freshness if d.verdict == "suspect")
+
     repo_info = RepoInfo(
         project_name=project_name,
         aid_dir=str(loc.aid_dir),