$manage-codebase-refresh
$manage-codebase-refresh "--since 2026-03-15"
$manage-codebase-refresh "--deep"
$manage-codebase-refresh "--since 3d --deep"
Flags:
--since <date>-- Override change detection window (ISO date or relative like3d)--deep-- Force deeper re-scan even for minor changes
Output boundary: ALL file writes MUST target .workflow/codebase/ (doc files, doc-index.json) and .workflow/state.json (codebase_last_refreshed timestamp) only. NEVER modify source code or files outside these paths.
Step 1: Validate Preconditions
Verify .workflow/ exists (E001) and .workflow/codebase/ exists (E002 -- use codebase-rebuild instead).
Step 2: Detect Changes
Resolve baseline: --since flag > state.json.codebase_last_refreshed > codebase_last_rebuilt > 7-day fallback. Find the baseline commit via git log --since="{baseline}" --reverse --format="%H" | head -1. If no commit found, use HEAD~1. Then run git diff --name-only {baseline_commit}..HEAD. If no changes: W001, exit.
Step 3: Map Changes to Docs
Read .workflow/codebase/doc-index.json to find doc entries covering changed files. Build affected entry list.
Step 3.5: KG Impact Analysis (if KG exists)
If .workflow/codebase/knowledge-graph.json exists: run maestro kg diff-wiki --json. Parse output for affectedWiki entries. If any, log WARNING for each: "KG impact: code changes affect [entry.id] — [entry.title]". Log summary: "{directNodes} direct, {impactedNodes} impacted KG nodes, {affectedWiki.length} wiki entries flagged". If KG does not exist: skip silently.
Step 4: Refresh Affected Docs
For each affected entry: re-read changed source files, update corresponding doc in .workflow/codebase/, update timestamp in doc-index.json. With --deep: also re-scan adjacent files.
Step 5: Update State
Update doc-index.json timestamps and state.json.codebase_last_refreshed. Display summary with change/refresh/skip counts.
<error_codes>
| Code | Severity | Description |
|---|---|---|
| E001 | fatal | .workflow/ not initialized |
| E002 | fatal | No codebase docs exist -- use $manage-codebase-rebuild instead |
| W001 | warning | No changes detected since last refresh |
| </error_codes> |
<success_criteria>
- Preconditions validated (.workflow/ and .workflow/codebase/ exist)
- Change detection baseline resolved (--since flag, state.json, or 7-day fallback)
- Git changes detected and mapped to doc entries via doc-index.json
- KG impact analysis run (if knowledge-graph.json exists)
- Affected wiki entries flagged with warnings (if any)
- Affected docs refreshed with updated source content
- --deep flag triggers adjacent file re-scan
- doc-index.json timestamps and state.json codebase_last_refreshed updated
- Summary displayed with change/refresh/skip counts </success_criteria>