mcs-sync

MCS Sync — Detect, Understand, Decide

Single manifest-driven pipeline for every external dependency. Replaces the deleted /mcs-refresh + tools/refresh-everything.js auto-apply path. The key invariants:

1. Two decisions only — TAKE or REJECT. No middle ground.
2. Never auto-applies — taking a change prints the impacted artifacts and writes an action plan markdown for the user; the orchestrator never edits a downstream file itself.
3. Manual cadence — there is no auto-cron, no session-start auto-fetch. The user runs sync weekly (or on demand). The session-start hook only warns about staleness; it does not invoke sync.

Invocation

# Default: detect + understand on all 8 sources, write triage bundle
node tools/sync-orchestrator.js
npm run sync

# Single source
node tools/sync-orchestrator.js run --source knowledge-cache
node tools/sync-orchestrator.js run --source upstream-repos
node tools/sync-orchestrator.js run --source elevate
node tools/sync-orchestrator.js run --source eval-guide
node tools/sync-orchestrator.js run --source mcp-servers
node tools/sync-orchestrator.js run --source om-cli
node tools/sync-orchestrator.js run --source docs-manifest
node tools/sync-orchestrator.js run --source plugins

# Fast detect-only (fingerprints, no classification)
node tools/sync-orchestrator.js detect

# Re-open the last triage (no re-detection)
node tools/sync-orchestrator.js review

# Record a decision
node tools/sync-orchestrator.js decide <changeId> reject --reason "..."
node tools/sync-orchestrator.js decide <changeId> take   --reason "..." --confirm

# Inspect loaded manifest (lists all 8 sources)
node tools/sync-orchestrator.js manifest

# Machine-readable output
node tools/sync-orchestrator.js --json

Decisions

Decision	Meaning
TAKE	Accept the upstream change. The orchestrator prints the impact graph (downstream artifacts the change touches) and writes an action plan to knowledge/sync/views/<runId>-actions.md. The user works through the plan manually. Requires --confirm so the impact list is not silently bypassed.
REJECT	Decline the change. Permanent for this changeId. If upstream moves again, the next sync run produces a fresh card with a different changeId and re-presents it.

There are no ADOPT/MERGE/LEVERAGE/SKIP/IGNORE classes anymore. Legacy adapter outputs in those forms are remapped automatically by tools/sync-orchestrator.js (normalizeRecommendation).

Sources (8)

All sources registered in knowledge/sync-manifest.json. Each has a dedicated adapter under tools/sync-adapters/.

Source	Adapter	Detection Signal	Default
knowledge-cache	knowledge-cache.js	Normalized markdown content hash per cache file	TAKE
upstream-repos	upstream-repos.js	Commit SHA + watchPaths hash via upstream-check.js	REJECT
elevate	elevate.js	Commit SHA + tracked path tree hash via elevate-sync.js	REJECT
eval-guide	eval-guide.js	Installed plugin SHA + gh api HEAD comparison	TAKE
mcp-servers	mcp-servers.js	Static config hash from .claude/settings.json mcpServers	REJECT
om-cli	om-cli.js	Binary hash + stamped source SHA	REJECT
docs-manifest	docs-manifest.js	Per-URL content hash for tracked MS Learn pages	TAKE
plugins	plugins.js	Installed Claude plugin SHA set (excluding eval-guide)	REJECT

Storage Layout

knowledge/sync/
├── snapshots/          (gitignored — last observed fingerprint per source)
├── runs/               (gitignored — per-run change records, working memory)
├── decisions/<id>/     (committed — hash-chained JSONL, canonical machine truth)
└── views/              (committed — generated markdown projection for humans)
    ├── <runId>.md         (triage board)
    └── <runId>-actions.md (action plan; appended on every TAKE)

• Snapshots and runs are gitignored because they churn on every run.
• Decisions (JSONL, partitioned by source id) are the authoritative audit trail.
• Views are regenerated on every decision; never hand-edit. The pre-commit hook (tools/git-hooks/pre-commit) runs sync-orchestrator.js verify-views and rejects edits that break the integrity marker.

Three-Phase Pipeline

Phase 1: DETECT

Each adapter reports a fingerprint: {primary, secondary, version, timestamp}. The orchestrator compares against the stored snapshot. If fingerprints match, the source is unchanged and skipped.

Phase 2: UNDERSTAND

For each changed source, the adapter's understand() classifies the diff: kind (content/structure/behavior/dependency), breakingRisk, novelty. The impact graph in the manifest expands direct impacts into transitive review items (e.g., eval-guide change → flag eval-generation + eval-pipeline for review).

Phase 3: DECIDE

The orchestrator renders triage cards sorted by priority (impact 40 + breakingRisk 25 + confidence 15 + staleness 10 + opportunity 10). Top 10 shown in console, full bundle in knowledge/sync/views/<runId>.md. User issues decide per card. On TAKE, the orchestrator:

1. Resolves the change's source through manifest.impactGraph.edges.
2. Prints "Taking this change touches N downstream artifact(s)" with the list.
3. Refuses to record without --confirm.
4. Once confirmed, appends a hash-chained JSONL entry with impactedArtifacts: [...].
5. Appends a ## <changeId> section to knowledge/sync/views/<runId>-actions.md containing the action plan steps and a checklist of impacted artifacts.

The action plan is a manual checklist. The orchestrator never edits any of those files.

Priority Score

priority = 40*impact + 25*breakingRisk + 15*confidence + 10*staleness + 10*opportunity

Cards under priority 20 are noise-level; they appear but below the fold.

When to Use This Skill

• User says "sync", "refresh everything", "check what's new upstream?", "weekly sync" → run npm run sync
• User says "check the knowledge cache" → run --source knowledge-cache
• User says "has eval-guide changed?" → run --source eval-guide
• User says "is om-cli current?" → run --source om-cli
• Before a major build → detect (fast) then full run if anything moved
• Weekly cadence: full run, review the triage, decide TAKE or REJECT for everything priority > 40

When NOT to Use This Skill

• For per-task lookups inside another skill (e.g., /mcs-research calling microsoft_docs_search for a specific topic) — that is local research, not a dependency sync.
• For applying a TAKE decision automatically — the orchestrator never edits framework files. The user works through the action plan manually and commits.
• For amending a decision — decisions are append-only and hash-chained. To re-evaluate, wait for the next run to produce a fresh changeId.

Extending: Add a New Source

1. Add entry to knowledge/sync-manifest.json under sources[] with id, adapter, defaultRecommendation (TAKE or REJECT), and impacts: [...].
2. Write adapter at tools/sync-adapters/<source-id>.js exporting detect({source, prevSnapshot, root}) and understand({source, before, after, root}).
3. Declare any new impact graph edges in manifest.impactGraph.edges.
4. Run node tools/sync-orchestrator.js run --source <id> to baseline.

Adapter Contract

// tools/sync-adapters/<source-id>.js
module.exports = {
  async detect({ source, prevSnapshot, root }) {
    return {
      fingerprint: { primary, secondary, version, timestamp },
      meta: { /* optional free-form */ },
    };
  },
  async understand({ source, before, after, root }) {
    return {
      severity: 'none' | 'low' | 'medium' | 'high',
      confidence: 0..1,
      classification: { kind, subkind?, breakingRisk, novelty? },
      recommendation: 'TAKE' | 'REJECT',
      actionPlan: 'Step 1\nStep 2\n...',          // newline-delimited; rendered as a checklist
      evidence: [{ type, path?, ref?, excerpt? }],
      headline: 'Short one-line summary',
      why: ['Bullet 1', 'Bullet 2'],
    };
  },
};

Return { error: '...' } from detect for recoverable issues; orchestrator logs it as a REJECT card without crashing other sources.

Notes on side effects

• The orchestrator never modifies a tracked source file under the user's control. It only writes:
  • knowledge/sync/snapshots/*.json (gitignored)
  • knowledge/sync/runs/<runId>/* (gitignored)
  • knowledge/sync/decisions/<source>/<runId>.jsonl (committed audit trail)
  • knowledge/sync/views/<runId>.md and <runId>-actions.md (committed)
  • knowledge/docs-cache/<slug>.txt (gitignored, raw fetched content for diff)
• tools/elevate-sync.js --digest and tools/upstream-check.js --update advance their own tracking state when the user runs them manually as part of an action plan. Sync never invokes those --update/--digest modes itself.