From 4151a70fe3cd4f4b6bd22b0f89961a59fe97c704 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Sat, 20 Jun 2026 05:53:20 +0200 Subject: [PATCH] docs(rollout): brief for STATE.md tracking + version-consistency rollout MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Marketplace-wide coordination brief in catalog/docs/. Two cross-cutting workstreams: (A) STATE.md tracked in every repo per the updated global continuity rule — verified status: 2 DONE (config-audit, ms-ai-architect), 3 avgitignore+track (voyage, linkedin-studio, claude-design), 6 avgitignore-only; per-repo steps + testable verification. (B) version-consistency via check-versions.mjs — 8 OK, 2 WARN (linkedin-studio, ms-ai-architect: plugin.json ahead of an untagged ref), each needing an operator release-intent decision. Plan only — execution is per repo with its own GO. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8 --- docs/state-version-rollout.md | 93 +++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/state-version-rollout.md diff --git a/docs/state-version-rollout.md b/docs/state-version-rollout.md new file mode 100644 index 0000000..be5748a --- /dev/null +++ b/docs/state-version-rollout.md @@ -0,0 +1,93 @@ +# 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 | no | yes | avgitignore + track | `:34` | +| linkedin-studio | yes | no | yes | avgitignore + track | `:62` | +| claude-design | yes | no | yes | avgitignore + track | `:3` | +| llm-security | no | no | yes | avgitignore (file made later) | `:19` | +| 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` | +| 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 check-ignore -v STATE.md` rather than trusting the number. + +### Per-repo steps (for each non-DONE repo) + +1. `git -C 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 check-ignore STATE.md` → exits non-zero (no longer ignored). +- If a file exists: `git -C ls-files STATE.md` → prints `STATE.md` (tracked). +- `grep -n STATE /.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: **8 OK, 2 WARN, 0 ERROR.** + +### 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).