Project Overview

Dominant Variable

Does the registered project list (projects-registry.md) point to paths that actually exist, and does each project's handoff file contain a state-snapshot v1 block? If neither is true, the generated map is empty.

Key Assumptions

1. session-handoff-LATEST.md is a hint, not a fact — parsed results (ts/ctx) are carried over as-is without fact-checking. The generated overview reflects "what each project last reported," not "current ground truth."
2. Registry is opt-in — never pull in unowned projects or auto-scanned directories. Only projects explicitly listed in projects-registry.md are in scope. Write exactly one - name: /abs/path line per project. The script matches one line at a time and accepts only a value that is an absolute path (/..., ~/..., C:\... or C:/...); any other bullet (a note, a URL, a relative path) is ignored and reported as a WARN line on stderr.
3. AUTO block generation is fully deterministic — a regex-based script (scripts/generate_overview.py) does all the parsing/rendering, including neutralizing markdown-table-breaking characters in the text it pulls from other projects' handoffs, isolating a single non-UTF-8 handoff file so it can't abort the whole run, and refusing (BLOCKED, no write) instead of guessing when the AUTO marker pair itself is mangled. The model only triggers execution and reports the result — no LLM inference in the parsing/rendering logic itself.

Trigger

• /project-overview
• "project map"
• "overall status"

Discard If

• Zero registered projects (projects-registry.md missing or empty list) → instruct the user to add a project to the registry first, then stop
• Already run recently with no state change across projects (the modification time of the generated OVERVIEW.md is later than that of every registered project's handoff file — compare them directly with stat or ls -l) → suggest skipping the re-run (not forced — run if the user wants)

File formats (registry, handoff snapshot block, OVERVIEW.md): https://github.com/AlexZio00/sovereign-skills/blob/master/docs/FILE-CONVENTIONS.md

Workflow

1. Confirm ~/.claude/projects-registry.md exists. If missing, report BLOCKED: "registry missing — create it with one - name: /absolute/path line per project." (The script reports the same thing on stderr and exits 1.)
2. Run this skill's own script (no arguments — it uses the default registry and output paths on its own):

   python3 "${CLAUDE_SKILL_DIR}/scripts/generate_overview.py"

   ${CLAUDE_SKILL_DIR} is this skill's folder; Claude Code fills it in. In other agents, replace it with the path where you installed the skill. Use python instead of python3 where only that exists (common on Windows). If the script file is missing or Python cannot start it, report BLOCKED with the error text and stop; do not write OVERVIEW.md by hand.
3. Check the exit code:
   • 0 → report the stdout's first line verbatim to the user. Both WORKING: N project(s) -> <output> and PARTIAL: N project(s) -> <output> (M with no snapshot) are valid values the script itself produces (it counts the no-snapshot projects and picks the label itself) — don't assume exit 0 always means WORKING.
   • 1 → report the stderr BLOCKED: ... message verbatim to the user. Never proceed on assumption.
4. On success, tell the user the ~/.claude/OVERVIEW.md path.
5. Report snapshot age in chat only, never in the file: compare each project's Last Update timestamp in the generated AUTO block with today's date. For every row older than 7 days, report stale: <name> <N> days ago (ts). If a timestamp cannot be read as a date, report age unknown for that row. Do not add this as an Age column in generate_overview.py: a date-dependent value would make the AUTO block change every day even when the inputs are the same, which breaks Invariant 4 (byte-identical output).

Output

• Chat report: relay the script's own stdout/stderr line verbatim (WORKING: N project(s) -> <path>, PARTIAL: ... or BLOCKED: ...) — don't paraphrase it or invent a project count of your own.
• Disk write: the script writes exactly one file, and only the AUTO:START~AUTO:END region inside it — ~/.claude/OVERVIEW.md. Nothing else on disk is touched, and text outside the markers in that file is never rewritten.
• Final status label: state one of WORKING / PARTIAL / BLOCKED (definitions in Truthful Reporting below) at the end of every run — never leave it implicit.

Scope Boundary

Safety Layers

• L1 (Invariants): Invariant 1 — preserve text outside AUTO markers. Invariant 2 — never scan unregistered projects.
• L3 (User Approval): manual-trigger only — runs only when the user explicitly invokes it (no auto-wiring is itself the approval gate).

Invariants (never violate)

1. Text outside AUTO markers is always preserved: if apply_auto_markers() alters any text outside the markers, that's a bug. Violation → notes a human wrote directly into OVERVIEW.md get lost on re-run.
2. Only scan explicitly registered projects: never add auto directory-discovery logic to this script. Violation → information about unowned projects leaks into the map.
3. STATE.md is absolutely untouched: no code path in this skill reads or writes STATE.md. Violation → direct Scope Boundary violation, risk of contaminating the cross-project blocker list.
4. Idempotency: re-running with identical input (unchanged registry + handoff files) must produce a byte-identical AUTO block. Violation → undermines the entire "deterministic auto-generation" design goal.
5. Cross-project text is data, not markup: ts/ctx values come from another project's handoff file and are untrusted — a stray | or newline in there must not be allowed to split table columns or break rows. Violation → a single malformed handoff field corrupts the whole table for every other project listed in it.

Error Recovery

Truthful Reporting

• no mock deception: before reporting "generation complete," actually read OVERVIEW.md to confirm project entries landed in the AUTO block.
• no silent brokenness: a parsing failure for a specific project's handoff is never silently skipped — it's shown explicitly as "no snapshot".
• Final status label: WORKING (generated normally) / PARTIAL (some projects show no snapshot) / BLOCKED (registry missing/empty).

Rationalization Table