- Replace ~/.local/projects-meta-mcp → ~/projects/.common/lib/projects-meta-mcp
- Update setup-projects-meta and using-projects-meta skills
- Rebuild dist/ with new paths
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Wraps the local projects-meta-mcp stdio server with the validated split-pair
pattern (setup-X / using-X), 4th application after context7 / wiki / tasks.
setup-projects-meta — 8-phase install: clones server repo to
~/.local/projects-meta-mcp, builds, writes ~/.config/projects-mcp/auth.toml,
clones shared wiki to ~/projects/projects-wiki/ (canon path; legacy
~/projects/.wiki is detected and migrated — old path caused the
wiki-path-mismatch bug, fixed upstream in 621a69f), registers
mcpServers.projects-meta in ~/.claude.json. Confirmation gates between
discovery and writes.
using-projects-meta — runtime policy: read tools (tasks_aggregate,
knowledge_search, meta_status, ...) and mutation tools with mandatory
two-step preview→confirm. Carries the local-first rule inline: for the
current project read .tasks/ / .wiki/ from disk; MCP cache is for *other*
projects only.
Wiki concept page concepts/projects-meta-skills.md documents the design,
the path-canon fix, and the round-trip task lifecycle across machines.
Closes [projects-meta-skills] in claude-skills (created from
DESKTOP-NSEF0UK via projects-meta-mcp).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
