OpeItcLoc03/claude-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(using-projects-meta): v1.1.0 — mandatory Step 0 freshness gate

Browse Source 
Cross-machine workflows broke silently when the agent reasoned on a stale
MCP cache, or hit sha-based optimistic-lock 422s on shared-wiki writes
because another host had pushed minutes earlier. Codify the missing
pre-flight as Step 0:

  1. Always probe mcp__projects-meta__meta_status first.
  2. If cache_age_minutes > 10 OR errors_count > 0 → run
     `node ~/.local/projects-meta-mcp/dist/sync.js` before any read.
  3. For shared-wiki WRITES (knowledge_ingest, knowledge_promote) →
     unconditional `git -C ~/projects/projects-wiki pull --ff-only`
     (sha-lock will reject the commit otherwise; failure is opaque).
  4. Tasks-mutations: sync via dist/sync.js is enough (no local clone
     of target tasks repo).
  5. Sync 401/403 → STOP, send user to ~/.config/projects-mcp/auth.toml
     to rotate gitea_token. No silent retry.

10-minute cache window chosen as the read threshold — balances
multi-machine drift detection against unnecessary Gitea round-trips.

Common mistakes + Red flags expanded to call out the new failure modes.
README mirrors the rule for human readers. Wiki concept page
projects-meta-skills.md gets a "Freshness gate (v1.1.0)" subsection.

Closes [using-projects-meta-freshness-gate].

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
vitya
2026-04-30 00:33:05 +03:00
parent e744dad46b
commit 6c83a35d6d
7 changed files with 133 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
.wiki/concepts/projects-meta-skills.md
View File

@@ -67,6 +67,20 @@ Both `setup-projects-meta` and `using-projects-meta` now write the canon path. `
This is a meta-lesson: **always pull shared/multi-machine resources before relying on cached anchors**. Saved as a feedback memory.
## Freshness gate (v1.1.0)
`using-projects-meta` v1.1.0 adds a mandatory pre-flight **Step 0** before any `tasks_*` / `knowledge_*` call:
1. Probe `mcp__projects-meta__meta_status` (cache age + errors).
2. If `cache_age_minutes > 10` or `errors_count > 0` → `node ~/.local/projects-meta-mcp/dist/sync.js`.
3. For shared-wiki writes (`knowledge_ingest`, `knowledge_promote`) → **unconditional** `git -C ~/projects/projects-wiki pull --ff-only` (sha-based optimistic lock will reject otherwise with 422).
4. For tasks-mutations (`tasks_create/update/close`) → sync via `dist/sync.js` is enough; no local clone of target tasks repo.
5. 401/403 from sync → token dead → send user to `~/.config/projects-mcp/auth.toml`. Loud failure mandatory.
Why: `projects-meta` is a bus between machines. Another host can push minutes ago without the agent knowing. Without Step 0, reads return stale data and writes hit opaque 422s — exactly the failure mode we hit during this very session (skipped initial pull → wiki anchors stale → had to rewrite three places after retroactive `git pull`). Codified the lesson into the skill so future sessions don't repeat it.
10-minute threshold is the chosen balance: catches multi-machine drift, doesn't burn Gitea round-trips for casual back-to-back questions.
## Round-trip note
The task `[projects-meta-skills]` was created on a different machine (`OpeItcLoc03@DESKTOP-NSEF0UK`) via `mcp__projects-meta__tasks_create target_project=claude-skills`. Closing it on this machine via `mcp__projects-meta__tasks_close target_project=claude-skills slug=projects-meta-skills` round-trips back to the same Gitea board — both sides see the 🟢 done state. First end-to-end multi-machine task lifecycle in the fleet.