Files

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

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>

2026-04-30 00:33:05 +03:00

4.6 KiB

Raw Blame History

using-projects-meta-freshness-gate

Goal

Add an explicit Step 0 "Freshness gate" to using-projects-meta so the agent does not hit a stale MCP cache or a sha-based optimistic-lock conflict in cross-machine workflows. Pre-flight: always meta_status; if cache_age > 10 min or errors_count > 0, run node ~/.local/projects-meta-mcp/dist/sync.js for reads; for shared-wiki writes (knowledge_ingest, knowledge_promote) additionally git -C ~/projects/projects-wiki pull --ff-only. 401/403 from sync → token expired → send user to ~/.config/projects-mcp/auth.toml. Tasks-mutations need only the sync (no local clone of target tasks repo). Bump skill 1.0.0 → 1.1.0 (additive, non-breaking).

Key files

skills/using-projects-meta/SKILL.md — add Step 0 — Freshness gate section before "Read (no confirmation needed)" and before "Mutate (always two-step)"; tweak Workflow ordering
skills/using-projects-meta/README.md — mirror the rule in a new "Freshness gate" subsection of "Two operation classes"
.wiki/concepts/projects-meta-skills.md — append a "Freshness gate (v1.1.0)" subsection
.wiki/log.md — one entry

Decisions log

2026-04-30: Threshold = 10 min cache age. Reason: balance between catching cross-machine pushes and not hitting Gitea on every casual tasks_aggregate. User-supplied number, codified.
2026-04-30: For shared-wiki writes, pull is unconditional (not gated by cache age). Reason: sha-based optimistic lock in knowledge_ingest will reject the commit otherwise with a 422, and the failure mode is opaque ("why did it fail?"). The pull is cheap (fast-forward is a no-op when already current).
2026-04-30: For tasks-mutations, sync via dist/sync.js is enough. Reason: there's no local clone of the target tasks repo — mutations go straight through Gitea API. The sync only refreshes the local view of all repos' STATUS.md so the agent reasons from current state when writing.
2026-04-30: 401/403 from sync → send user to rotate gitea_token in ~/.config/projects-mcp/auth.toml. Reason: silently failing or pretending sync succeeded leaves the agent reasoning on stale data. Loud failure is the whole point of the check.
2026-04-30: Version bump 1.0.0 → 1.1.0 (additive behavior change — adds a pre-flight step, doesn't break existing usage). using-context7 precedent: version in frontmatter, semver discipline.

Open questions

Should Step 0 apply to meta_status itself? Decision: no — that would be circular. meta_status is the freshness probe, not a read that depends on freshness.

Completed steps

Open task in STATUS.md as 🔴 active
Add Step 0 — Freshness gate section to using-projects-meta/SKILL.md (between Workflow header and Read sub-section); add Step 0 reference to Read and Mutate sub-flows; extend Common mistakes (3 new rows: stale aggregate, skipped pull, sync 401/403); extend Red flags (2 new bullets)
Mirror rule in using-projects-meta/README.md as new "Step 0 — Freshness gate (v1.1.0, mandatory pre-flight)" section
Bump version: 1.0.0 → 1.1.0 in SKILL.md frontmatter
First rebuild + reinstall — caused regression: full Step 0 inlined into description took it to ~1450 chars, exceeded harness limit, description silently dropped → listing showed using-projects-meta: Using the projects-meta MCP server (H1 fallback); fixed by trimming description to 924 chars with one-sentence pointer "v1.1.0 mandates a Step 0 freshness gate ... see SKILL body"
Saved feedback memory skill_description_length_limit.md so future me checks length after frontmatter edits
Wiki: appended "Freshness gate (v1.1.0)" subsection to concepts/projects-meta-skills.md; one entry in log.md
Closed in STATUS.md (🟢 done); next: commit + push + MCP round-trip close

Notes

User-supplied draft text for the skill (verbatim): "Step 0 — Freshness gate. Always call mcp__projects-meta__meta_status first. If cache_age_minutes > 10 or errors.length > 0, run node ~/.local/projects-meta-mcp/dist/sync.js before any read. For shared-wiki writes (knowledge_ingest, knowledge_promote), additionally run git -C ~/projects/projects-wiki pull --ff-only — sha-based optimistic lock will reject your commit otherwise."
Trigger reason from user: "projects-meta — это шина между машинами. Юзер на ноуте может не знать, что на десктопе уже был коммит в shared wiki 5 минут назад. Без этого шага write-флоу ломается случайным образом, и баг трудно воспроизвести."

4.6 KiB Raw Blame History Unescape Escape