.spec-driver

Author: davidlee

.contracts/all/supekku/cli/edit.py.md

@@ -17,14 +17,17 @@ Returns normally on success.
 IMPORTANT: typer.Exit inherits from RuntimeError. Callers with
 ``except RuntimeError`` MUST guard with ``except typer.Exit: raise``
 first, or use an early ``return`` after this call.
+- `_verify_memory(memory_id, path) -> None`: Stamp verification SHA and dates on a memory artifact.
+
+Raises typer.Exit(EXIT_FAILURE) if git is unavailable.
 - @app.command(adr) `edit_adr(decision_id, status, root) -> None`: Edit ADR in editor.
 - @app.command(audit) `edit_audit(audit_id, status, root) -> None`: Edit audit in editor.
 - @app.command(card) `edit_card(card_id, status, anywhere, root) -> None`: Edit card in editor.
 - @app.command(delta) `edit_delta(delta_id, status, root) -> None`: Edit delta in editor.
 - @app.command(drift) `edit_drift(ledger_id, status, root) -> None`: Edit drift ledger in editor.
 - @app.command(improvement) `edit_improvement(improvement_id, status, root) -> None`: Edit improvement in editor.
 - @app.command(issue) `edit_issue(issue_id, status, root) -> None`: Edit issue in editor.
-- @app.command(memory) `edit_memory(memory_id, status, root) -> None`: Edit memory record in editor.
+- @app.command(memory) `edit_memory(memory_id, status, verify, root) -> None`: Edit memory record in editor.
 - @app.command(plan) `edit_plan(plan_id, status, root) -> None`: Edit implementation plan in editor.
 - @app.command(policy) `edit_policy(policy_id, status, root) -> None`: Edit policy in editor.
 - @app.command(problem) `edit_problem(problem_id, status, root) -> None`: Edit problem in editor.

.contracts/all/supekku/cli/list.py.md

@@ -12,6 +12,7 @@ Display formatting is delegated to supekku.scripts.lib.formatters
 
 ## Functions
 
+- `_format_stale_memories(records, root) -> str`: Compute staleness and format as tiered table.
 - `_parse_relation_filter(value) -> tuple[Tuple[str, str]]`: Parse ``TYPE:TARGET`` from ``--relation`` flag.
 
 Splits on the first colon. Raises :class:`typer.BadParameter` if no colon
@@ -77,7 +78,7 @@ By default, resolved/implemented items are excluded. Use --all to show all.
 Shortcut for: list backlog --kind issue
 
 By default, resolved/implemented items are excluded. Use --all to show all.
-- @app.command(memories) `list_memories(root, status, memory_type, tag, path, command, match_tag, include_draft, limit, substring, regexp, case_insensitive, format_type, json_output, links_to, truncate) -> None`: List memory records with optional filtering and scope matching.
+- @app.command(memories) `list_memories(root, status, memory_type, tag, path, command, match_tag, include_draft, limit, substring, regexp, case_insensitive, format_type, json_output, links_to, truncate, stale) -> None`: List memory records with optional filtering and scope matching.
 
 The --filter flag does substring matching (case-insensitive).
 Metadata pre-filters (--type, --status, --tag) apply first (AND logic).

.contracts/all/supekku/scripts/lib/formatters/memory_formatters.py.md

@@ -5,6 +5,11 @@ Memory display formatters.
 Pure formatting functions with no business logic.
 Formatters take MemoryRecord objects and return formatted strings for display.
 
+## Constants
+
+- `_STALENESS_HEADER`
+- `_TIER_LABELS`
+
 ## Functions
 
 - `_calculate_column_widths(terminal_width) -> dict[Tuple[int, int]]`: Calculate column widths for memory table based on terminal width.
@@ -15,6 +20,10 @@ Formatters take MemoryRecord objects and return formatted strings for display.
 - `_format_provenance(provenance) -> list[str]`: Format provenance dict as indented sub-lines.
 - `_format_relations(relations) -> list[str]`: Format relations list as indented entries.
 - `_format_scope(scope) -> list[str]`: Format scope dict as indented sub-lines.
+- `_format_scope_cell(info) -> str`: Format the scope summary cell.
+- `_format_stale_cell(info) -> str`: Format the staleness indicator cell.
+- `_format_staleness_row(info, records) -> str`: Format a single staleness row.
+- `_partition_tiers(infos) -> tuple[Tuple[list[StalenessInfo], list[StalenessInfo], list[StalenessInfo]]]`: Split staleness infos into three tiers.
 - `_prepare_memory_row(record) -> list[str]`: Prepare a single row for the memory table.
 - `_prepare_memory_tsv_row(record) -> list[str]`: Prepare a single memory record as a plain TSV row (no markup).
 - `format_link_graph_json(nodes) -> str`: Format link graph nodes as JSON array.
@@ -65,3 +74,18 @@ Args:
 
 Returns:
   Formatted string in requested format.
+- `format_staleness_table(infos, records) -> str`: Format staleness info as a three-tier plain-text table.
+
+Tiers:
+  1. Scoped + attested — sorted by commits_since descending
+  2. Scoped + unattested — sorted by days_since descending
+  3. Unscoped — sorted by days_since descending
+
+Empty tiers are omitted.
+
+Args:
+  infos: StalenessInfo list from compute_batch_staleness.
+  records: Mapping of memory_id → MemoryRecord for metadata.
+
+Returns:
+  Formatted multi-tier string, or empty string if no infos.

.contracts/all/supekku/scripts/lib/memory/staleness.py.md

@@ -0,0 +1,60 @@
+# supekku.scripts.lib.memory.staleness
+
+Batched staleness computation for memory artifacts.
+
+Computes staleness by counting git commits that touched scoped paths
+since a memory's last verified SHA. Uses a single git invocation for
+all scoped memories (DEC-086-06).
+
+## Constants
+
+- `__all__`
+
+## Functions
+
+- `_assign_commit_counts(results, attested, commit_data) -> None`: Count commits affecting each attested memory's scope paths.
+- `_collect_all_pathspecs(attested) -> list[str]`: Collect deduplicated pathspecs from all attested records.
+- `_collect_scope_paths(record) -> list[str]`: Collect all scope paths and converted globs for a record.
+- `_days_since(record, today) -> <BinOp>`: Compute days since the most relevant date on a record.
+- `_find_oldest_sha(attested) -> str`: Find the verified_sha from the record with the oldest verified date.
+- `_parse_git_log_output(output) -> list[_CommitEntry]`: Parse ``git log --oneline --name-only`` output into commit entries.
+- `_path_matches_scope(file_path, scope_paths) -> bool`: Check whether a file path matches any scope path (prefix match).
+- `_query_git_log(attested, root) -> <BinOp>`: Run a single git log and parse commits with affected paths.
+
+Returns None if git is unavailable or the command fails, so callers
+can distinguish "no commits found" from "unable to query."
+- `compute_batch_staleness(records, root) -> list[StalenessInfo]`: Compute staleness for multiple memories using a single git invocation.
+
+For scoped+attested memories, runs one ``git log`` from the oldest
+verified SHA and counts commits per memory's scope paths.
+
+Unscoped and unattested memories fall back to ``days_since`` from
+their verified or updated date.
+
+Args:
+  records: Memory records to evaluate.
+  root: Repository root for git commands.
+
+Returns:
+  StalenessInfo for each input record, in the same order.
+- `glob_to_pathspec(glob) -> str`: Convert a scope glob pattern to a git pathspec.
+
+Strips trailing ``/**`` (directory wildcard) to produce a directory
+prefix that git understands. Other patterns pass through as-is.
+Leading ``./`` is also stripped.
+
+Args:
+  glob: Scope glob pattern (e.g. ``supekku/cli/**``).
+
+Returns:
+  Git-compatible pathspec string.
+
+## Classes
+
+### StalenessInfo
+
+Staleness data for a single memory.
+
+### _CommitEntry
+
+A parsed commit from git log output.

.contracts/all/supekku/scripts/lib/skills/sync.py.md

@@ -1,6 +1,6 @@
 # supekku.scripts.lib.skills.sync
 
-Allowlist-driven skills sync: install, prune, and expose skills in AGENTS.md.
+Allowlist-driven skills install: install, prune, and expose skills in AGENTS.md.
 
 Reads `.spec-driver/skills.allowlist`, installs allowlisted skills from the
 package source (`supekku/skills/`) to `.spec-driver/skills/` (the canonical

.contracts/public/supekku/cli/edit.py.md

@@ -16,7 +16,7 @@ Edit commands for opening artifacts in an editor or updating status.
 - @app.command(drift) `edit_drift(ledger_id, status, root) -> None`: Edit drift ledger in editor.
 - @app.command(improvement) `edit_improvement(improvement_id, status, root) -> None`: Edit improvement in editor.
 - @app.command(issue) `edit_issue(issue_id, status, root) -> None`: Edit issue in editor.
-- @app.command(memory) `edit_memory(memory_id, status, root) -> None`: Edit memory record in editor.
+- @app.command(memory) `edit_memory(memory_id, status, verify, root) -> None`: Edit memory record in editor.
 - @app.command(plan) `edit_plan(plan_id, status, root) -> None`: Edit implementation plan in editor.
 - @app.command(policy) `edit_policy(policy_id, status, root) -> None`: Edit policy in editor.
 - @app.command(problem) `edit_problem(problem_id, status, root) -> None`: Edit problem in editor.

.contracts/public/supekku/cli/list.py.md

@@ -72,7 +72,7 @@ By default, resolved/implemented items are excluded. Use --all to show all.
 Shortcut for: list backlog --kind issue
 
 By default, resolved/implemented items are excluded. Use --all to show all.
-- @app.command(memories) `list_memories(root, status, memory_type, tag, path, command, match_tag, include_draft, limit, substring, regexp, case_insensitive, format_type, json_output, links_to, truncate) -> None`: List memory records with optional filtering and scope matching.
+- @app.command(memories) `list_memories(root, status, memory_type, tag, path, command, match_tag, include_draft, limit, substring, regexp, case_insensitive, format_type, json_output, links_to, truncate, stale) -> None`: List memory records with optional filtering and scope matching.
 
 The --filter flag does substring matching (case-insensitive).
 Metadata pre-filters (--type, --status, --tag) apply first (AND logic).

.contracts/public/supekku/scripts/lib/formatters/memory_formatters.py.md

@@ -55,3 +55,18 @@ Args:
 
 Returns:
   Formatted string in requested format.
+- `format_staleness_table(infos, records) -> str`: Format staleness info as a three-tier plain-text table.
+
+Tiers:
+  1. Scoped + attested — sorted by commits_since descending
+  2. Scoped + unattested — sorted by days_since descending
+  3. Unscoped — sorted by days_since descending
+
+Empty tiers are omitted.
+
+Args:
+  infos: StalenessInfo list from compute_batch_staleness.
+  records: Mapping of memory_id → MemoryRecord for metadata.
+
+Returns:
+  Formatted multi-tier string, or empty string if no infos.

.contracts/public/supekku/scripts/lib/memory/staleness.py.md

@@ -0,0 +1,41 @@
+# supekku.scripts.lib.memory.staleness
+
+Batched staleness computation for memory artifacts.
+
+Computes staleness by counting git commits that touched scoped paths
+since a memory's last verified SHA. Uses a single git invocation for
+all scoped memories (DEC-086-06).
+
+## Functions
+
+- `compute_batch_staleness(records, root) -> list[StalenessInfo]`: Compute staleness for multiple memories using a single git invocation.
+
+For scoped+attested memories, runs one ``git log`` from the oldest
+verified SHA and counts commits per memory's scope paths.
+
+Unscoped and unattested memories fall back to ``days_since`` from
+their verified or updated date.
+
+Args:
+  records: Memory records to evaluate.
+  root: Repository root for git commands.
+
+Returns:
+  StalenessInfo for each input record, in the same order.
+- `glob_to_pathspec(glob) -> str`: Convert a scope glob pattern to a git pathspec.
+
+Strips trailing ``/**`` (directory wildcard) to produce a directory
+prefix that git understands. Other patterns pass through as-is.
+Leading ``./`` is also stripped.
+
+Args:
+  glob: Scope glob pattern (e.g. ``supekku/cli/**``).
+
+Returns:
+  Git-compatible pathspec string.
+
+## Classes
+
+### StalenessInfo
+
+Staleness data for a single memory.

.contracts/public/supekku/scripts/lib/skills/sync.py.md

@@ -1,6 +1,6 @@
 # supekku.scripts.lib.skills.sync
 
-Allowlist-driven skills sync: install, prune, and expose skills in AGENTS.md.
+Allowlist-driven skills install: install, prune, and expose skills in AGENTS.md.
 
 Reads `.spec-driver/skills.allowlist`, installs allowlisted skills from the
 package source (`supekku/skills/`) to `.spec-driver/skills/` (the canonical