# Brief — STATE.md tracking + version-consistency rollout (marketplace-wide)

> Coordination brief for two cross-cutting changes across all marketplace plugins.
> Lives in catalog (the marketplace coordinator). **This is the plan — execution happens
> per repo, each needing its own operator GO** (cross-repo edits). Status verified 2026-06-20.

## Goal

1. **STATE.md tracked** in every repo — the updated global continuity rule
   (`~/.claude/CLAUDE.md`): STATE.md is tracked and committed, never gitignored; pushed to
   private Forgejo, never GitHub/public.
2. **Version-consistency green** — every plugin passes `catalog/scripts/check-versions.mjs`
   (no ERROR; ideally no WARN).

These two workstreams are independent and can be done in any order.

---

## Workstream A — STATE.md tracking

### Status (verified 2026-06-20)

| Repo | har STATE.md | tracked | gitignored | Action | `.gitignore` line* |
|------|--------------|---------|------------|--------|--------------------|
| config-audit | yes | **yes** | no | ✅ DONE | — |
| ms-ai-architect | yes | **yes** | no | ✅ DONE | — |
| voyage | yes | **yes** | no | ✅ DONE | — |
| llm-security | yes | **yes** | no | ✅ DONE (2026-06-20) | — |
| linkedin-studio | yes | no | yes | avgitignore + track | `:62` |
| claude-design | yes | no | yes | avgitignore + track | `:3` |
| graceful-handoff | no | no | yes | avgitignore (file made later) | `:3` |
| ai-psychosis | no | no | yes | avgitignore (file made later) | `:21` |
| okr | no | no | yes | avgitignore (file made later) | `:28` |
| human-friendly-style | no | no | yes | avgitignore (file made later) | `:3` |
| playground-design-system | no | no | yes | avgitignore (file made later) | `:3` |
| catalog | no | no | yes | avgitignore (file made later) | `:5` |

\* Line numbers as of 2026-06-20 — they drift. At execution time, resolve the exact source with
`git -C <repo> check-ignore -v STATE.md` rather than trusting the number.

### Per-repo steps (for each non-DONE repo)

1. `git -C <repo> check-ignore -v STATE.md` → confirm the exact `.gitignore` line.
2. Remove the `STATE.md` entry from `.gitignore`. Replace the section comment with a tracked-state
   note, mirroring config-audit / ms-ai-architect (e.g. *"session/local state — STATE.md is TRACKED
   continuity (per ~/.claude; overrides the polyrepo convention); the rest stays local"*).
3. If a `STATE.md` file already exists (voyage / linkedin-studio / claude-design): `git add STATE.md`.
   If not (the 6 "file made later"): de-gitignoring is enough — the file is tracked the first time a
   session writes it at session-end. Optionally seed a minimal stub now; not required.
4. Commit `chore: track STATE.md per global continuity rule` (+ standard footer). `chore:`/`docs:`
   pass any docs-gate freely.
5. Push within the window (weekday 20:00–23:00, weekend anytime).

### Verification (testable)

- `git -C <repo> check-ignore STATE.md` → exits non-zero (no longer ignored).
- If a file exists: `git -C <repo> ls-files STATE.md` → prints `STATE.md` (tracked).
- `grep -n STATE <repo>/.gitignore` → no bare `STATE.md` ignore line remains.

---

## Workstream B — Version-consistency

Run from catalog: `node scripts/check-versions.mjs` (add `--strict` to fail on WARN too).
Current run (2026-06-20): **8 OK, 2 WARN, 0 ERROR.** llm-security was resolved this day —
v7.8.0 released + tagged `v7.8.0` (commit `6d3c4b5`), catalog `ref` + README version/stats
bumped 7.7.2 → 7.8.0; gate → OK. The 2 WARN below are unchanged.

### The 2 WARN — require an operator decision

| Plugin | plugin.json | catalog ref | tag for plugin.json version? |
|--------|-------------|-------------|------------------------------|
| linkedin-studio | 0.5.0 | v0.4.0 | no (`v0.5.0` does not exist) |
| ms-ai-architect | 1.16.0 | v1.15.0 | no (`v1.16.0` does not exist) |

For each, pick one:

- **Bump is unreleased** → no action. The gate WARNs correctly; catalog rightly points at the last
  released tag. (Leave as-is.)
- **Bump is meant to be released** → in the plugin repo: tag `vX.Y.Z` on the release commit + push;
  in catalog: bump the `ref` + the README version/stat line; re-run the gate (expect that plugin → OK).

> Only the operator knows which case applies — the gate cannot infer release intent.

### Verification (testable)

- `node scripts/check-versions.mjs` → `0 ERROR` (hard requirement).
- After resolving both WARNs: `node scripts/check-versions.mjs --strict` → exit 0.

---

## Scope fence

- Each repo edit is a separate cross-repo change → **its own operator GO**.
- This brief is the plan; nothing in the 9 non-catalog repos is touched until GO per piece.
- Push window applies to every push (weekday 20:00–23:00, weekend anytime).