Setup Status

Setup Status

Read-only cross-analysis over every setup skill in the brewcode suite. It answers one question: what is already set up in this project, what drifted, what was never installed — and hands back the exact command to run for each row.

Every probe is read-only. No file is created, edited or deleted by the report itself; allowed-tools carries no Write, no Edit, no Agent. Each probe is an existence check, a cmp, or a one-line grep. The single exception is Phase 1c's opt-in one-key merge into a settings.json, which happens only after the user picks it — see Why it does not run the setups.

Prompt contract

Position 1 of $ARGUMENTS is a free-form prompt (RU/EN). This skill has no modes to select — report is the only behavior — so the prompt carries exactly one optional decision: which plugin or skill to filter to.

1. There are no flags and no destructive path — nothing to strip.
2. Extract a plugin name (brewcode, brewtools, brewdoc) or a skill name (semble-setup, docsync, task board, ...) from the prompt if one is present; that becomes the filter. Prose naming neither is unrecognised text, not an error -> full report.
3. Empty arguments -> full cross-plugin report. Nothing here is chosen by asking.
4. AskUserQuestion fires at most ONCE per run, and only for Phase 1c's task-tools offer — the one outcome-changing choice this skill has. The filter is never asked about.
5. Prose that is not a plugin/skill name is still input: extract the name from it, never treat the first word as a positional filter.

Then print this block ONCE, right before the report (Phase 4) — the only possible mutation is the Phase 1c env key, and it comes after the report:

PLAN — brewcode:setup-status
INPUT:  <arguments verbatim, or "(empty)">
MODE:   report — <full cross-plugin | filtered: <plugin/skill>>
SCOPE:  <resolved plugin(s)/skill(s) in scope>
DO:     <2-5 imperative bullets: resolve plugin roots, probe artifacts, read stamps, classify;
         add "offer to enable the task-graph tools" when Phase 1c's verdict is `off`>
RESULT: <the report the user ends up holding; name the settings.json write when one is offered>

Labels are literal; values follow the conversation language.

Why it does not run the setups

Each setup skill is an interactive generator: it fans out subagents, analyses the repo and asks the user real questions. Running two of them back-to-back in one session degrades both — the context fills with the first one's analysis, and the second one's questions get answered against stale findings. So the correct flow is:

This skill reports. The user runs each setup by hand, ideally one per fresh session.

There is no --run, no --fix, no auto mode, and no plan to add one. If the user asks for one, say this paragraph and print the run-list instead.

One carve-out, and it is not a setup. Phase 1c's CLAUDE_CODE_ENABLE_TODO_TOOLS offer merges ONE key into ONE settings.json. It spawns no subagent, analyses nothing, generates nothing, and asks exactly one question — none of the properties that make batching setups harmful apply to it. The promise above is about the eleven setups and stays whole: this skill still runs none of them.

Outside that single env key, this skill creates, edits and deletes nothing.

Arguments: $ARGUMENTS — empty = full report. A plugin name (brewcode, brewtools, brewdoc) filters to that plugin's rows. A skill name (semble-setup, docsync, task board) filters to that one row and prints its detection rule in full. Unrecognised text = full report.

Two questions, two signals

Every setup artifact in a project carries a content_version — the release in which its own content last actually changed — alongside a version — the plugin release that produced this install. The field contract (version, content_version, generated_by, last_updated, doc_type, and which carrier each file type uses) lives in ONE place: references/artifact-metadata.md. This skill consumes it and never restates it.

version — which plugin release produced this install — stays readable on every row and every verdict; it answers a real question, just not this skill's headline one, since it bumps on every plugin release whether or not this artifact's own content changed, which is exactly what was producing false stale reports before content_version existed. Report content_version first, version beside it as provenance, the owner when it disagrees, the byte verdict last.

None answers another's question. A hand-edited installed hook still carries the X.Y.Z content_version stamp it was copied with, so the stamp cannot see body drift — cmp can. And cmp is meaningless for a generated artifact, which is AI-authored per project and never byte-equal to any asset — only the stamp reaches those. The owner is orthogonal to both: a file written by the WRONG setup can be at the current content_version and byte-perfect, and nothing but generated_by will say so.

Of the five fields in the contract, this skill reads three — content_version (headline), generated_by, and version (secondary, displayed but never decisive). Why last_updated and doc_type are deliberately unread is argued once, in Phase 2a; do not add a reader for them without an actionable verdict to attach.

Two stamping moments, and the difference matters when reading a row:

The Roster — SINGLE SOURCE OF TRUTH

Every fact this skill knows about a setup lives in this ONE table. Adding a future setup = adding ONE row. Nothing else in this file, and no script, encodes the roster.

$BC / $BT / $BD = the resolved plugin roots from Phase 0.

Rows 8 and 10 share one precedence rule: the setup's own generated JSON is the preferred carrier, and the byte-copied companion's brewcode-meta: line is the documented fallback for as long as that JSON goes unstamped. Read the JSON first; fall through silently; never report LEGACY on a row whose fallback carrier answered.

Row 2 — the .sembleignore carve-out. Like hard-sync.md it is shipped as mechanism a (STAMPED_FILES, kind marker) and copied verbatim by install_managed, so it LOOKS like a cmp partner. It is not one. install_ignore_apply (semble-guidance.sh:564-585, reached through the install_ignore dispatcher at :618-620) runs install_candidates after install_managed has copied the template, and that function appends a # --- brewcode:semble measured candidates --- block measured from THIS repo (:500-555) — every line commented out, proposals only. So a HEALTHY, freshly-installed .sembleignore differs from assets/sembleignore.template by construction, exactly like row 9. Fed to Phase 2b it prints DIFFERS beside a CURRENT stamp, which Phase 3 rule 9 turns into stale (bytes drifted) — and row 2's only two readings of that (metadata-only re-sync or prose hand-edit needing --force) are both wrong. --force there takes a backup and overwrites the user's own uncommented exclusions. Never cmp it, never prescribe --force for it, never name it in a remedy for byte drift.

Unlike row 9, its STAMP is still read. The installer's comparison strips both the # brewcode-meta: line and the whole candidates block from both sides (sg_strip_metaline, :401-411), so a template update still writes through on the metadata-only branch and the stamp genuinely moves. Phase 2a on .sembleignore is valid; Phase 2b on it is not. The two carve-outs differ exactly there: hard-sync.md loses BOTH signals, .sembleignore loses only cmp.

unchanged from the installer does NOT mean byte-equal to the template. install_ignore_apply snapshots the file around both halves and collapses a clean net-zero run — re-sync then a byte-identical re-append — back to ignore: up to date (:576-584; the dry-run path predicts the same verdict by simulating into a temp dir, install_ignore_dry:591-616). So a back-to-back re-run over an unchanged repo reports ignore: up to date — while the file on disk still differs from assets/sembleignore.template by the whole candidates block. Do not read the installer's unchanged as licence to cmp the pair; the two answer different questions.

A re-run over a repo whose FILE SET moved does report changed, because the scan re-measures and the block genuinely changes. That is real byte movement, still not a drift signal, and still not something cmp against the template can express.

Row 9 — why the dashboard parses instead of executing. bash "$BD/skills/memory-sync-setup/scripts/generate.sh" status prints a richer verdict (STAMP_FORMAT, META_*, DRIFTS, VERDICT) and is genuinely read-only — its status_report only reads and echoes, and resolve_root only cds. It is still the wrong default here: it re-scans the whole memory surface (real work, not a probe), it exit 1s when the cwd is not a repo root, and it returns a private verdict vocabulary that would have to be translated into this skill's states — which puts roster knowledge inside a foreign script and breaks "no script encodes the roster". So: read the frontmatter with the Phase 2a block like every other row, and put generate.sh status in the Command column as something the USER may run when row 9 is not green.

Row 9 — the hard-sync.md carve-out. It is shipped as mechanism a (STAMPED_FILES row, kind md) and cpd verbatim, so it LOOKS like a cmp partner. It is not one, and listing it as one made this dashboard report drift on every correctly-installed project. The emitted references/hard-sync.md carries two of the generator's twelve BLOCK placeholders — {PATHS_PRECISION_TABLE} and {OBVIOUS_VS_DOMAIN_TABLE} — which the generator's own Phase 3 fills with project-specific tables via Edit, and generate.sh validate FAILS while either is unfilled. So a HEALTHY install differs from the plugin source by construction: cmp DIFFERS is the success state, not drift, and no mode can ever clear it without destroying the user's tables. Its baked stamp is frozen at the release that emitted it for the same reason — refresh_refs refuses to re-copy a file whose content differs — so feeding it to Phase 2a would print a permanent BEHIND. Never cmp it, never stamp-read it, never name it in a remedy. The row's version signal is the anchor's frontmatter and nothing else.

The two references that DO pair up are cleared by upgrade, and only by it. generate.sh:514 refresh_refs() (reached from restamp, which is the mandatory last step of upgrade — memory-sync-setup/SKILL.md mode upgrade step 3) re-copies a reference only when that is provably lossless, and prints which case fired:

Line	Condition	Clears a cmp DIFFERS?
REF OK:	already byte-identical	n/a — the row was SAME
REF RESTORED:	the file was absent; nothing local to lose	yes
REF RECOPIED:	the ONLY difference is the brewcode-meta: release-stamp line	yes — this is the plugin-update case
REF DIFFERS:	real content differs (hand-edit, filled BLOCKs, prose moved in a newer release)	no — the file is left untouched, by design

A REF DIFFERS: on memory-guide.md or agent-audit.md after an upgrade therefore means a genuine local edit: report stale (bytes drifted), say upgrade will NOT overwrite it, and tell the user to diff against $BD/skills/memory-sync-setup/references/<name> and port by hand. Do not prescribe a mode that would silently discard their edit — there is none.

Every secondary must be EXCLUSIVE to its row. A shared artifact — .claude/agents/*.md, .claude/agents/intent-guard.md (superreview and teams both emit it), any hand-written agent — is not evidence that THIS setup ran, and listing one makes Phase 3 rule 3 report a partial install in every project that merely has an agent file. If a setup owns no exclusive secondary, leave the cell empty and let the anchor decide.

Row 3 baseline mapping (the only non-obvious cmp pairing):

<stack> is the one per-stack reference the install picked — go.md, java-kotlin.md, python.md or typescript-react.md. It is substituted and baseline-copied exactly like the other four; only its filename varies. Absent from an install that predates it: report the other four and say the per-stack ref is missing, never DIFFERS.

NOT setups — never appear in the report

Recurring tools, not one-time installs. They are correct to run repeatedly and have no installed state to report: brewcode:agents, skills, rules, convention, e2e; brewtools:text-optimize, text-human, secrets-scan, ssh, deploy, plugin-update, provider-switch; brewdoc:md-to-pdf, my-claude, publish.

Phase 0 — Resolve plugin roots

A plugin that is not installed makes every one of its rows n/a — never missing. Do not assume all four are present.

The plugin version is the number every stamp is compared against, so resolve it with the SAME precedence the brewcode SessionStart hook uses (brewcode/hooks/session-start.mjs, parseVersion): the cache directory basename first, .claude-plugin/plugin.json .version second. One precedence, two consumers — do not invent a third.

EXECUTE using Bash tool:

for p in brewcode brewdoc brewtools brewui; do
  r=$({ ls -d "$HOME/.claude/plugins/cache/claude-brewcode/$p"/*/ 2>/dev/null || true; } | sort -V | tail -1 | sed 's:/*$::')
  if [ -n "$r" ] && [ -d "$r" ]; then
    v=$(basename "$r")
    case "$v" in
      [0-9]*.[0-9]*.[0-9]*) : ;;
      *) v=$(grep -o '"version"[[:space:]]*:[[:space:]]*"[^"]*"' "$r/.claude-plugin/plugin.json" 2>/dev/null | head -1 | sed 's/.*:[[:space:]]*"//; s/"$//' || true) ;;
    esac
    echo "$p ROOT=$r VERSION=${v:-unknown}"
  else echo "$p ROOT=none VERSION=none"; fi
done
echo "PROJECT=$PWD"
test -d "$PWD/.claude" && echo "DOTCLAUDE=yes" || echo "DOTCLAUDE=no"
echo "OK"

STOP if FAILED — cannot resolve the cache; report it and stop rather than calling everything missing. All four roots none also means stop: nothing installed, nothing to report.

Bind $BC, $BT, $BD and their versions from the output. DOTCLAUDE=no is a legitimate answer — every row is missing, print the table anyway. VERSION=unknown on a plugin that IS installed means no comparison is possible for its rows: report installed (plugin version unresolved) and say why.

Phase 1 — Probe artifacts

One generic block, fed from the roster. Paste the anchor + secondary paths of the rows in scope (after the $ARGUMENTS filter) into the heredoc — relative to the project root, one per line, a trailing / for a directory, globs allowed.

EXECUTE using Bash tool:

cd "$PWD" || exit 1
while IFS= read -r rel; do
  [ -z "$rel" ] && continue
  case "$rel" in
    */)    [ -d "$rel" ] && echo "DIR  $rel" || echo "MISS $rel" ;;
    *"*"*) n=$({ find . -path "./$rel" 2>/dev/null || true; } | wc -l | tr -d ' '); n=${n:-0}; [ "$n" -gt 0 ] && echo "GLOB $rel ($n)" || echo "MISS $rel" ;;
    *)     if [ -f "$rel" ]; then echo "FILE $rel"
           elif [ -f "$rel.disabled" ]; then echo "PARK $rel.disabled"
           else echo "MISS $rel"; fi ;;
  esac
done <<'PATHS'
.claude/teams/*/team.md
.claude/teams/*/trace-ops.sh
.claude/rules/semble-first.md
PATHS
echo "OK"

PARK is present, not missing. Five setups disable by renaming their entry file to <name>.disabled (Phase 1b), and the body stays byte-identical — so a PARK line never feeds Phase 3's missing or partial rules, and the file it names is still a readable version stamp.

Then the `setting

…(truncated)