aid-installer 1.0.0 → 1.1.0

package/dashboard/reader/locator.py

@@ -0,0 +1,228 @@
+# dashboard/reader/locator.py
+# LC-1 Locator: resolve .aid/ root, enumerate work-NNN-*/ dirs, stat manifest/KB.
+#
+# Responsibility: filesystem listing + read-only git worktree enumeration.
+# No parse (beyond worktree-list output), no write, no derivation.
+# Read-only by construction: stat + iterdir + read-only git worktree list;
+# the git subprocess is delegated to derivation.py (the one module permitted
+# to call subprocess per the existing architecture contract; see FR35).
+# This module does NOT use subprocess directly.
+#
+# Python 3.11+ stdlib only. Zero third-party deps.
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import NamedTuple, Optional
+
+# Work-folder glob pattern: exactly work-[0-9]*-* (FR12 / feature-002 LC-1)
+# Matches work-NNN-{slug} directories only; excludes .temp/, .heartbeat/, etc.
+_WORK_GLOB = "work-[0-9]*-*"
+
+# Compiled pattern for the same rule (used to double-check against symlinks or files)
+_WORK_RE = re.compile(r"^work-[0-9]+-")
+
+
+class LocatorResult(NamedTuple):
+    """Output of locate_aid_root()."""
+    aid_dir: Path          # resolved .aid/ path (always set; may not exist)
+    aid_exists: bool       # whether .aid/ actually exists on disk
+    manifest_path: Path    # .aid/.aid-manifest.json (may not exist)
+    version_path: Path     # .aid/.aid-version (may not exist; fallback for ToolInfo)
+    settings_path: Path    # .aid/settings.yml
+    kb_dir: Path           # .aid/knowledge/ (may not exist)
+    work_dirs: list[Path]  # .aid/work-NNN-*/ directories (sorted, dirs only)
+    heartbeat_dir: Path    # .aid/.heartbeat/ (stat-only; may not exist)
+
+
+def locate_aid_root(repo_root: str | Path) -> LocatorResult:
+    """Resolve the .aid/ tree from repo_root and enumerate work folders.
+
+    Structurally excludes .aid/.temp/ and .aid/.heartbeat/ -- only work-NNN-*
+    dirs are returned as works (the work-glob is the only filter needed; no
+    special-casing of .temp or .heartbeat is required because they don't match
+    the glob).
+
+    Never throws. If .aid/ is absent, aid_exists=False and work_dirs=[].
+    """
+    root = Path(repo_root).resolve()
+    aid_dir = root / ".aid"
+
+    manifest_path = aid_dir / ".aid-manifest.json"
+    version_path = aid_dir / ".aid-version"
+    settings_path = aid_dir / "settings.yml"
+    kb_dir = aid_dir / "knowledge"
+    heartbeat_dir = aid_dir / ".heartbeat"
+
+    aid_exists = aid_dir.is_dir()
+    work_dirs: list[Path] = []
+
+    if aid_exists:
+        work_dirs = _enumerate_work_dirs(aid_dir)
+
+    return LocatorResult(
+        aid_dir=aid_dir,
+        aid_exists=aid_exists,
+        manifest_path=manifest_path,
+        version_path=version_path,
+        settings_path=settings_path,
+        kb_dir=kb_dir,
+        work_dirs=work_dirs,
+        heartbeat_dir=heartbeat_dir,
+    )
+
+
+def _enumerate_work_dirs(aid_dir: Path) -> list[Path]:
+    """Return sorted list of .aid/work-NNN-*/ directories.
+
+    Uses the exact glob work-[0-9]*-* (FR12). Returns only entries that:
+    - match the glob
+    - are actual directories (not files, not symlinks to non-dirs)
+    - match the _WORK_RE pattern (belt-and-suspenders: glob already filters,
+      but explicit check guards against oddly-named dirs on case-insensitive FS)
+
+    .aid/.temp/ and .aid/.heartbeat/ are structurally excluded by the glob --
+    they do not start with "work-[0-9]" so they are never yielded.
+    """
+    try:
+        candidates = list(aid_dir.glob(_WORK_GLOB))
+    except OSError:
+        return []
+
+    result = []
+    for p in candidates:
+        if p.is_dir() and _WORK_RE.match(p.name):
+            result.append(p)
+
+    result.sort(key=lambda p: p.name)
+    return result
+
+
+def stat_path(path: Path) -> Optional[int]:
+    """Return file size in bytes if path exists and is a regular file; else None."""
+    try:
+        st = path.stat()
+        if path.is_file():
+            return st.st_size
+        return None
+    except OSError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# SD-3: Worktree enumeration (work-004 Pillar 4)
+#
+# The git subprocess calls (worktree list, symbolic-ref) are delegated to
+# derivation.py -- the one reader module permitted to use the subprocess module
+# per the existing architecture contract (FR35, SEC-A1).  This module contains
+# only the pure-Python parsing and filesystem-traversal logic; it never calls
+# subprocess directly.
+# ---------------------------------------------------------------------------
+
+# Regex to detect "worktree <path>" lines in --porcelain output.
+_RE_WORKTREE_LINE = re.compile(r"^worktree\s+(.+)$")
+# Regex to detect "branch refs/heads/<name>" lines.
+_RE_BRANCH_LINE = re.compile(r"^branch\s+refs/heads/(.+)$")
+# Label used for detached-HEAD worktrees (no branch line in --porcelain output).
+_DETACHED_LABEL = "(detached)"
+
+
+def enumerate_worktree_roots(repo_root: str | Path) -> list[tuple[str, Path]]:
+    """Enumerate all persistent git worktrees for repo_root and return per-worktree roots.
+
+    Delegates the read-only `git -C <root> worktree list --porcelain` call to
+    derivation.run_worktree_list() (the fixed-argv / no-shell pattern, twin of
+    _run_git_log).  The verb is hard-coded in the argv list inside derivation.py;
+    no shell and no user-supplied string is ever executed.
+
+    For each worktree, locates its .aid/ directory (worktree_path/.aid/).  The main
+    worktree (first record in --porcelain output) is ALWAYS included.
+
+    Returns a list of (branch_label, aid_dir) pairs, one per worktree.  The main
+    worktree is always the first element.
+
+    Degradation (SD-3 DD-A2): git absent / non-git / timeout / parse failure ->
+    returns [(main_branch_label, main_aid_dir)] (main-root-only fallback).
+    Never throws.
+    """
+    # Lazy import to avoid circular imports (locator -> derivation; derivation
+    # imports models but NOT locator, so this direction is safe).
+    from .derivation import detect_main_branch_label, run_worktree_list  # noqa: PLC0415
+
+    root = Path(repo_root).resolve()
+    main_aid = root / ".aid"
+    # Main-root-only fallback (returned on any failure mode)
+    main_label = detect_main_branch_label(root)
+    main_fallback: list[tuple[str, Path]] = [(main_label, main_aid)]
+
+    porcelain = run_worktree_list(root)
+    if porcelain is None:
+        return main_fallback
+
+    parsed = _parse_worktree_porcelain(porcelain)
+    if not parsed:
+        return main_fallback
+
+    results: list[tuple[str, Path]] = []
+    for wt_path, branch_label in parsed:
+        wt_aid = wt_path / ".aid"
+        results.append((branch_label, wt_aid))
+
+    if not results:
+        return main_fallback
+
+    return results
+
+
+def _parse_worktree_porcelain(output: str) -> list[tuple[Path, str]]:
+    """Parse `git worktree list --porcelain` output into (worktree_path, branch_label) pairs.
+
+    The --porcelain format groups records by blank lines:
+        worktree /abs/path/to/worktree
+        HEAD <sha>
+        branch refs/heads/<branch>    # absent for detached HEADs
+
+    Returns list of (Path, branch_label) pairs; detached HEADs get label "(detached)".
+    Returns [] on any parse failure (caller degrades to main-root-only).
+    Never throws.  No subprocess calls; no I/O.
+    """
+    try:
+        records: list[tuple[Path, str]] = []
+        current_path: Optional[Path] = None
+        current_branch: Optional[str] = None
+
+        for raw_line in output.splitlines():
+            line = raw_line.rstrip()
+
+            if not line:
+                # Blank line: flush the current record (if any)
+                if current_path is not None:
+                    label = current_branch if current_branch is not None else _DETACHED_LABEL
+                    records.append((current_path, label))
+                current_path = None
+                current_branch = None
+                continue
+
+            wt_m = _RE_WORKTREE_LINE.match(line)
+            if wt_m:
+                # If we have a pending record without a trailing blank, flush it.
+                if current_path is not None:
+                    label = current_branch if current_branch is not None else _DETACHED_LABEL
+                    records.append((current_path, label))
+                    current_branch = None
+                current_path = Path(wt_m.group(1).strip())
+                continue
+
+            br_m = _RE_BRANCH_LINE.match(line)
+            if br_m:
+                current_branch = br_m.group(1).strip()
+
+        # Flush any trailing record (output may not end with a blank line)
+        if current_path is not None:
+            label = current_branch if current_branch is not None else _DETACHED_LABEL
+            records.append((current_path, label))
+
+        return records
+    except Exception:  # noqa: BLE001 -- never throws
+        return []

package/dashboard/reader/models.py

@@ -0,0 +1,408 @@
+# dashboard/reader/models.py
+# Normalized in-memory display model for the AID state reader (feature-002).
+#
+# These types are the single source of truth for the reader's output shape.
+# They mirror the enum vocabularies declared in feature-001's work-state-template.md (DM-6).
+#
+# Python 3.11+ stdlib only. Read-only data records; no persistence, no I/O.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# DM-6: Enum definitions
+# Single source of truth = feature-001 (canonical/templates/work-state-template.md).
+# Members reproduced here verbatim so the reader's switch is total.
+# The reader adds one reader-only sentinel per enum (Unknown) per DM-6 contract.
+# ---------------------------------------------------------------------------
+
+class Lifecycle(str, Enum):
+    """FR16 lifecycle states for a work folder.
+
+    Members from feature-001 work-state-template.md:
+        Running | Paused-Awaiting-Input | Blocked | Completed | Canceled
+    Reader-only:
+        Unknown -- returned when the normalized block is absent and no fallback fires.
+                   Never written to disk. See task-011 for the full fallback adapter.
+    """
+    Running = "Running"
+    PausedAwaitingInput = "Paused-Awaiting-Input"
+    Blocked = "Blocked"
+    Completed = "Completed"
+    Canceled = "Canceled"
+    Unknown = "Unknown"  # reader-only sentinel; never written to disk
+
+
+class Phase(str, Enum):
+    """Pipeline phase enum.
+
+    Members from feature-001 work-state-template.md:
+        Interview | Specify | Plan | Detail | Execute | Deploy | Monitor
+    Reader-only:
+        Unknown -- for an unrecognized Phase literal.
+    """
+    Interview = "Interview"
+    Specify = "Specify"
+    Plan = "Plan"
+    Detail = "Detail"
+    Execute = "Execute"
+    Deploy = "Deploy"
+    Monitor = "Monitor"
+    Unknown = "Unknown"  # reader-only sentinel; never written to disk
+
+
+class TaskStatus(str, Enum):
+    """Per-task status enum.
+
+    Members from feature-001 work-state-template.md (closed; single source of truth):
+        Pending | In Progress | In Review | Blocked | Done | Failed | Canceled
+    Reader-only:
+        Unknown -- for a row whose Status string matches no enum member (NFR7: never throws).
+                   Never written to disk.
+    """
+    Pending = "Pending"
+    InProgress = "In Progress"
+    InReview = "In Review"
+    Blocked = "Blocked"
+    Done = "Done"
+    Failed = "Failed"
+    Canceled = "Canceled"
+    Unknown = "Unknown"  # reader-only sentinel; never written to disk
+
+
+class SourceMode(str, Enum):
+    """Records which derivation path produced WorkModel.lifecycle."""
+    Normalized = "normalized"   # ## Pipeline Status block was present
+    Fallback = "fallback"       # legacy derivation (task-011)
+    Mixed = "mixed"             # rare: partial migration (task-011)
+
+
+# ---------------------------------------------------------------------------
+# DM-2: Level 0 -- ToolInfo
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ToolInfo:
+    """Level-0 tool / installation metadata parsed from .aid/.aid-manifest.json.
+
+    manifest_present=False means the manifest file was absent; fields are then None.
+    Never errors on absent manifest -- render 'tool info unavailable'.
+    """
+    manifest_present: bool
+    aid_version: Optional[str] = None
+    installed_at: Optional[str] = None
+    tools_installed: list[str] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# DM-3: Level 1 -- RepoInfo + KbStateRef
+# ---------------------------------------------------------------------------
+
+class KbStatus(str, Enum):
+    """FR32 5-state KB status enum (feature-007 DM-A2).
+
+    Derived by the reader (FF-A3 waterfall); never written to disk (NFR2).
+    Members:
+        pending    -- .aid/knowledge/ absent or empty
+        generating -- KB present but not yet User Approved: yes (safe default, SPEC residual-#1)
+        preparing  -- KB approved but kb.html absent OR summary not yet V1-approved
+        approved   -- KB + kb.html ready, current, approved
+        outdated   -- approved but default branch has advanced past kb_baseline (FR35)
+    Reader-only:
+        unknown    -- un-derivable combination falls back to pending treatment; never thrown
+    """
+    pending    = "pending"
+    generating = "generating"
+    preparing  = "preparing"
+    approved   = "approved"
+    outdated   = "outdated"
+    unknown    = "unknown"  # reader-only sentinel; never written to disk
+
+
+@dataclass
+class KbBaseline:
+    """Parsed projection of .aid/settings.yml kb_baseline block (DM-A4).
+
+    branch:   the default branch the KB reflects (e.g. 'master'); None if absent
+    tip_date: ISO-8601 commit date of that branch's tip at KB generation time; None if absent
+    """
+    branch: Optional[str] = None
+    tip_date: Optional[str] = None
+
+
+@dataclass
+class KbStateRef:
+    """KB state reference (feature-007 DM-A1 extended KbStateRef).
+
+    Populated from .aid/knowledge/STATE.md + .aid/knowledge/README.md + derivation.
+    Absent KB (.aid/knowledge/ missing) -> null in RepoInfo.
+
+    Retained fields (feature-002 DM-3):
+        summary_approved  -- from STATE.md ## Knowledge Summary Status **User Approved:** yes/no
+        last_summary_date -- parenthesized date on that line
+        doc_count         -- rows in README.md ## Completeness table
+
+    New fields (feature-007 DM-A1, task-064):
+        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
+    """
+    summary_approved: bool
+    last_summary_date: Optional[str] = None  # from STATE.md "User Approved: yes (YYYY-MM-DD...)"
+    doc_count: Optional[int] = None          # rows in README.md ## Completeness table
+    # feature-007 DM-A1 new fields (task-064):
+    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
+
+
+@dataclass
+class RepoInfo:
+    """Level-1 project / .aid/ state."""
+    project_name: str           # from .aid/settings.yml project.name; fallback: dir basename
+    aid_dir: str                # resolved .aid/ root path (as string)
+    kb_state: Optional[KbStateRef] = None
+
+
+# ---------------------------------------------------------------------------
+# DM-5: Level 3 -- TaskModel
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TaskModel:
+    """One row from ## Tasks Status in STATE.md.
+
+    Table columns (work-state-template.md):
+        # | Task | Type | Wave | Status | Review | Elapsed | Notes
+    The _none yet_ placeholder row is skipped by the parser.
+
+    PF-3/PF-5 fields (feature-009, schema_version 3):
+        short_name -- parsed from tasks/task-NNN.md first line "# task-NNN: <title>"
+        delivery   -- integer parsed from STATE Wave "delivery-NNN" (PF-5c; STATE wins)
+        lane       -- integer derived from PLAN.md wave-map or prose fallback (PF-5a/5b)
+    """
+    task_id: str
+    type: str
+    wave: Optional[str] = None
+    status: TaskStatus = TaskStatus.Unknown
+    review_grade: Optional[str] = None
+    elapsed: Optional[str] = None
+    notes: Optional[str] = None
+    # schema_version 3 fields (PF-3 / PF-5)
+    short_name: Optional[str] = None
+    delivery: Optional[int] = None
+    lane: Optional[int] = None
+
+
+# ---------------------------------------------------------------------------
+# DM-4: Level 2 -- WorkModel (includes PendingInput)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PendingInput:
+    """A ### Q{N} entry under ## Cross-phase Q&A (Pending) with Status: Pending."""
+    question_id: str      # e.g. "Q1"
+    category: Optional[str] = None
+    impact: Optional[str] = None
+    context: Optional[str] = None
+    suggested: Optional[str] = None
+
+
+@dataclass
+class FeatureRef:
+    """A single row from ## Features Status in STATE.md (prototype field)."""
+    number: int
+    name: str
+
+
+@dataclass
+class DeliverableRef:
+    """A single row from ## Plan / Deliveries in STATE.md (prototype field).
+
+    delivery_state: the SD-8 lifecycle enum from delivery-NNN/STATE.md ## Delivery Lifecycle
+    (Pending-Spec | Specified | Executing | Gated | Done | Blocked).
+    None when the delivery STATE.md is absent or the field is unparseable (legacy works).
+    """
+    number: int
+    name: str
+    task_count: int
+    delivery_state: Optional[str] = None
+
+
+@dataclass
+class WorkModel:
+    """Level-2 work folder state. One per .aid/work-NNN-*/ directory.
+
+    Retention = folder persistence (FR12): the model contains exactly the work
+    folders that exist on disk; completed and in-flight works are represented
+    identically.
+    """
+    work_id: str                    # folder name, e.g. "work-001-aid-dashboard"
+    name: str                       # display label (slug portion)
+    lifecycle: Lifecycle = Lifecycle.Unknown
+    phase: Optional[Phase] = None
+    active_skill: Optional[str] = None
+    updated: Optional[str] = None   # ISO-8601 or None
+    created: Optional[str] = None   # date string from ## Lifecycle History "Work created" row
+    pause_reason: Optional[str] = None  # present only when lifecycle=Paused-Awaiting-Input
+    block_reason: Optional[str] = None  # present only when lifecycle=Blocked
+    block_artifact: Optional[str] = None  # e.g. "IMPEDIMENT-task-NNN.md"
+    tasks: list[TaskModel] = field(default_factory=list)
+    pending_inputs: list[PendingInput] = field(default_factory=list)
+    source_mode: SourceMode = SourceMode.Fallback
+    # --- prototype: work-overview header fields (delivery-002 prototype) ---
+    number: Optional[int] = None           # from folder prefix work-NNN-... -> NNN
+    title: Optional[str] = None            # **Name:** from REQUIREMENTS.md
+    description: Optional[str] = None      # **Description:** from REQUIREMENTS.md
+    objective: Optional[str] = None        # body under ## 1. Objective in REQUIREMENTS.md
+    work_path: Optional[str] = None        # **Path:** from STATE.md ## Triage (full/lite)
+    recipe: Optional[str] = None           # lite-path recipe from Triage, else None
+    features: list[FeatureRef] = field(default_factory=list)      # from ## Features Status
+    deliverables: list[DeliverableRef] = field(default_factory=list)  # from ## Plan / Deliveries
+    # work-004 Pillar 4: branch label from the worktree that owns this work folder.
+    # "main" for the main worktree; branch name for persistent worktrees; None if unknown.
+    branch_label: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# DM-1 (feature-008): TaskDetail sub-model (LC-TR, task-069)
+# Populated ONLY for requested task_ids (detail_task_ids param).
+# Never persisted (NFR2); all fields are read-derived.
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Finding:
+    """One bullet under STATE.md ## Quick Check Findings ### task-NNN **Findings:** (DR-2).
+
+    severity:       leading bracketed tag -- [CRITICAL] | [HIGH]; lower/unknown -> [MINOR] neutral
+    description:    bullet text up to the first ' -- ' (em-dash segment separator)
+    location:       '{source-file:line}' segment, null if absent
+    disposition:    trailing 'Fixed-on-spot' / 'Deferred-to-gate' token, null if absent
+    reviewer_tier:  the block's **Reviewer Tier:** line (always 'Small' for a quick check)
+    """
+    severity: str               # '[CRITICAL]' | '[HIGH]' | '[MINOR]' (neutral fallback)
+    description: str
+    location: Optional[str] = None
+    disposition: Optional[str] = None
+    reviewer_tier: Optional[str] = None
+
+
+@dataclass
+class DeferredIssue:
+    """One row from delivery-NNN-issues.md filtered to Source task == task_id (DR-4).
+
+    4-col table: Source task | Severity | Description | Status
+    status enum: Open | Resolved | Accepted (unknown literal -> neutral, never throws)
+    """
+    source_task: str
+    severity: str
+    description: str
+    status: str
+
+
+@dataclass
+class TaskLedger:
+    """Delivery-level grade context for a task (DR-3/DR-4). NOT a per-task grade.
+
+    delivery_id:     resolved delivery for this task (from ## Tasks Status Wave); null if unassociated
+    grade:           per-delivery grade from ## Delivery Gates (verbatim, never re-graded -- NFR7)
+    reviewer_tier:   delivery reviewer tier
+    gate_timestamp:  when the delivery gate ran
+    deferred_issues: rows from delivery-NNN-issues.md where Source task == task_id
+    """
+    delivery_id: Optional[str] = None
+    grade: Optional[str] = None
+    reviewer_tier: Optional[str] = None
+    gate_timestamp: Optional[str] = None
+    deferred_issues: list[DeferredIssue] = field(default_factory=list)
+
+
+@dataclass
+class RawStateRef:
+    """Verbatim STATE.md bytes the reader ALREADY read this pass (DR-1, DD-3, NFR4).
+
+    text:     whole work STATE.md verbatim (reused from memory, no re-read)
+    byte_len: len(text) in bytes (corroborates NFR4 payload budget)
+    path:     '.aid/{work}/STATE.md' -- read-only caption label, NOT an edit link
+    """
+    text: str
+    byte_len: int
+    path: str
+
+
+@dataclass
+class LogAvailability:
+    """Honest DM-4 log inventory for a task (DR-5, KI-008).
+
+    task_logs:           always 'none' (AID persists no per-task execution log)
+    server_log_present:  stat .aid/.temp/dashboard.log (expected-false on Windows)
+    heartbeat_present:   stat .aid/.heartbeat/ (liveness signal, corroborating-only, KI-004)
+    """
+    task_logs: str = "none"      # always "none" today (DM-4)
+    server_log_present: bool = False
+    heartbeat_present: bool = False
+
+
+@dataclass
+class TaskDetail:
+    """Forensic sub-model for one drilled task (DM-1, feature-008 LC-TR).
+
+    Populated ONLY when detail_task_ids is supplied to read_repo_detail().
+    The always-on read_repo() path does NOT populate this; TaskModel is unchanged.
+
+    task_id:   == TaskModel.task_id (the drill key)
+    findings:  from ## Quick Check Findings ### task-NNN **Findings:** bullets
+    ledger:    delivery-level grade join (## Delivery Gates + delivery-NNN-issues.md)
+    raw_state: the already-read STATE.md bytes (no re-read, NFR4/DD-3)
+    logs:      honest DM-4 log inventory
+    """
+    task_id: str
+    findings: list[Finding] = field(default_factory=list)
+    ledger: TaskLedger = field(default_factory=TaskLedger)
+    raw_state: Optional[RawStateRef] = None
+    logs: Optional[LogAvailability] = None
+
+
+# ---------------------------------------------------------------------------
+# DM-7: ReadMeta (provenance of this read pass)
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ReadMeta:
+    """Provenance and health summary for a single read_repo() pass (DM-7).
+
+    read_at:        wall-clock of this pass (the only place the reader reads the clock).
+    work_count:     works enumerated.
+    fallback_works: work_ids whose source_mode != normalized (live tech-debt surface, AC4).
+    parse_warnings: non-fatal anomalies (missing section, unparseable row) -- never raised.
+    bytes_read:     total bytes read across all files (corroborates NFR4 low overhead).
+    """
+    read_at: str                             # ISO-8601
+    work_count: int = 0
+    fallback_works: list[str] = field(default_factory=list)
+    parse_warnings: list[str] = field(default_factory=list)
+    bytes_read: int = 0
+
+
+# ---------------------------------------------------------------------------
+# DM-1: Top-level RepoModel
+# ---------------------------------------------------------------------------
+
+@dataclass
+class RepoModel:
+    """Top-level normalized in-memory display model returned by read_repo().
+
+    RepoModel
+    +-- tool:  ToolInfo         Level 0 -- machine CLI (FR7)
+    +-- repo:  RepoInfo         Level 1 -- project / .aid/ + KB-state hook
+    +-- works: list[WorkModel]  Level 2 -- one per .aid/work-NNN-*/ folder (FR12)
+    +-- read:  ReadMeta         provenance of THIS read pass
+    """
+    tool: ToolInfo
+    repo: RepoInfo
+    works: list[WorkModel] = field(default_factory=list)
+    read: ReadMeta = field(default_factory=lambda: ReadMeta(read_at=""))