project-resync

project-resync

Full bidirectional sync cycle for the template fleet. One run covers: provenance audit → GitHub sync → selective backport → root PR → upgrades → upgrade PRs. Safety first: nothing is pushed without a dated provenance verdict — stale sync-wave residue must never pollute a remote. Fleet membership SSOT (DEC-20261107-01): the project set is derived ONLY via bun scripts/fleet-list.ts --json — Projects/co-* directories minus the exclusions recorded in docs/fleet-membership.json. Never hardcode the fleet count; never fall back to a raw Projects/co-* glob, even when the helper fails (on helper/registry failure, STOP and file one urgent ticket).

Safety Rules (non-negotiable)

1. Audit before any commit/push (Step 0). No verdict → no action.
2. Never commit STALE-RESIDUE verdicts. Snapshot locally before discarding; snapshots are never pushed.
3. Never use --no-verify or bypass either the project's or the workspace's sync gates.
4. Remote bootstrap: remote-less repos get gh repo create 5throck/<name> --private + git remote add origin — private strictly, no collaborators/topics unless asked.
5. PR base = project default branch; verify before merging.
6. Backport gate: promote only template-grade, reusable content. Engagement output, domain stacks, and VARIANT-INJECT content stay in the project (ADR-0031). Never backport deprecated skills.
7. KEEP-uncertain defaults to COMMIT-side review, never silent deletion.

Step 0 — Provenance audit

bun scripts/resync-audit.ts --snapshot-dir /tmp/resync-snapshots

Review the per-project verdict tables:

Verdict	Meaning	Action
STALE-RESIDUE	equals a current L0/L1/L2 source, or an older revision corroborated by project mtime older + line-order agreement	snapshot → discard (tracked: git checkout --, untracked: delete)
PRESUME-STALE	subset of a source without mtime/order corroboration — possible deliberate reordering or legitimate deletion	human confirm before discard; routes to commit-side review like LOCAL-WORK
LOCAL-WORK	diverges from HEAD and every source; or non-template file	commit candidate (Step 1); feeds backport review (Step 2)
KEEP	unresolvable	human review; default to commit on a side branch if risky

Apply verdicts only after reading the MIXED-group per-file details.

Step 1 — Sync each project to GitHub

Per project (clean of STALE-RESIDUE now):

1. Commit the LOCAL-WORK set via the project's own dev-sync (mandatory pathway; creates pr/<ts>-<slug> + PR with audit gates): bun scripts/dev-sync.ts --body-file <body> "<english conventional message>".
2. Bootstrap remote-less repos first (gh repo create 5throck/<x> --private, git remote add origin, push current branch).
3. Merge each PR when checks are CLEAN; checkout default + pull; delete branches. Projects with no changes (or already-pushed commits only): just push / skip.

Step 2 — Selective backport review

Diff each project's landed delta for this cycle against its variant surface (templates/co-<x>/) using the 5-surface method (docs/designs/2026-08-28-project-template-backport-design.md). The delta source is the union of:

• (a) Step-1 LOCAL-WORK landings (as before); and
• (b) merged PRs in the review window that are non-mechanical — mechanical = the PR is a template-delivery/workspace-sync landing whose changed files are limited to template-version.txt, .claude/last-upgrade-*, docs/VERSION_MANIFEST.md, memory/, and generated registries (chore: upgrade template… / chore: workspace sync… shapes). Session work a project landed through its own dev-sync PRs (feature/fix/docs PRs) is NOT mechanical and MUST enter the judgment. For (b), run bun scripts/backport-diff.ts --project <p> --base <pre-window-rev> where pre-window-rev is the project revision before the window's first non-mechanical merge (fall back to the mechanical wave's merge if the exact rev is unclear; state the base used in the report).

Session-landed work previously bypassed this step entirely (only Step 2e saw it, requests-only) — since 1.7.0 every landed delta gets a promote / stays-project / discarded-stale verdict:

• Promote template-grade, reusable assets into templates/co-<x>/ (or L0 for cross-variant assets) — after measuring that the project copy is genuinely newer/richer, not just divergent.
• Stays-project: engagement output, domain content, VARIANT-INJECT blocks.
• 5-surface candidate table aid: bun scripts/backport-diff.ts --project <co-name> --base <rev> (v1.0.2, standard aid since T-20261009-003) plus surface-by-surface reads over the named range.
• Produce the per-variant judgment report (promoted / stays-project / discarded-stale, per source (a)/(b)) — it feeds Step 3's PR body and the root CHANGELOG.
• Validate: bun scripts/validate-templates.ts, bun test (root).

Step 2b — Evidence plane review

Run bun scripts/evidence-backport-scan.ts. Read-only: reports candidates, never writes into templates/ or into any Projects/co-* instance (design docs/designs/2026-09-19-actor-model-and-evidence-backport-design.md §4, ADR-0084 Decision 6).

For each project, record the detected form (F1 prose ledger / F2 registry-backed / F3 schema-typed / F0 unrecognized / MIXED / none), the M1-M6 maturity results, and the verdict:

Verdict	Meaning	Action
PROMOTABLE	form real + all of M1-M6 pass	promote (see below)
SCHEMA-ONLY	M6a passes (a procedure exists) but M6b fails (not repeatedly used)	human-triage row; do not promote
NOT_YET	some other maturity test failed	human-triage row; do not promote
NEEDS_TRIAGE	F0, MIXED, or no evidence-shaped content at all	human-triage row; do not promote

Promote only PROMOTABLE candidates, and only by authoring the pair — under templates/co-<x>/:

• the F3 schema (evidence-models/<record-type>.schema.json, regardless of the source form),
• its companion evidence-collection-<name> skill (a generalization of the source collection procedure — never a copy of engagement-specific content),
• a provenance README.md recording the source project, source form, the skill path that satisfied M6, the commit range the maturity bar was measured over, and the M1-M6 results.

A schema promoted without its companion procedure is an incomplete backport and MUST be rejected at review. Route F0, MIXED, SCHEMA-ONLY, and any NOT_YET verdict to the cycle report as human-triage rows. Never auto-write into templates/. Safety Rule 6 (backport gate) governs this step unchanged.

Step 2c — Fleet echo check

For each backport-worthy LOCAL-WORK candidate from Step 2, check whether the same change (fix, improvement, or gap) echoes across the rest of the fleet:

1. Derive a fixed query per candidate: its distinctive identifiers or strings (symbol names, error messages, config keys — stable tokens that only match the changed code).
2. Run the query across ALL fleet repos (the membership SSOT — bun scripts/fleet-list.ts --json), scoped to the surface the candidate came from (e.g. grep -rn "<identifier>" Projects/*/skills/ Projects/*/scripts/).
3. Record a per-project verdict in the Step 2 judgment report:

Verdict	Meaning	Action
same-defect-present	the sibling carries the same pre-fix content	row in the cycle report — the fix lands in that project's own next resync
absent	the sibling has no matching content (different lineage, or already resolved)	no action
divergent-implementation	the sibling solves the same problem differently	human-triage row — possible cross-project learning, never merged mechanically

Report-only: this step never edits sibling projects. ADR-0031 Principle 5 (docs/adr/0031-l1-l2-fork-model.md) forbids automated sibling sync — drift REPORTING is the sanctioned direction. Each project adopts its echo fixes through its own reviewed resync cycle.

Step 2d — Upstream request ledger (design 2026-10-07-daily-fleet-learning-extraction)

Read-only upward-carrier reporting; added by user direction 2026-10-07:

1. Read every open upstream-request ticket (kind: manual, U- ids) in the workspace store and every LOCAL-PATCH(upstream-request: <id>) marker in the fleet.
2. Report each in the cycle report as the upstream request ledger: requesting project, subject, disposition stage (received / designed / fixed / re-delivered), and — when re-delivered — the template version that carried the fix to the requesting project.
3. Loop-closing duty: when this cycle's upgrade wave delivered a fix a project requested, state the pairing explicitly ("co-develop's U-20261006-001 reached the fleet via v0.13.1"). Report only — no edits.

Step 2e — Learning extraction (design 2026-10-07-daily-fleet-learning-extraction)

For each project with merged landings in the window (PRs merged, or commits landed by its own session), dispatch one scoped review pass over the delta (daily cadence, user directive 2026-10-07 — nightly batches are 1–3 landings, small and fresh):

1. Identify reusable assets: template enhancement, new/reusable skill, L0 tooling improvement, cross-pollination candidate.
2. File one ticket per asset — kind: manual, title prefix learning: — citing evidence refs (files, PRs). Requests only.
3. No silence rule: a landing with no reusable assets gets a one-line "reviewed, nothing to extract" entry. Every landing produces either a request or an explicit negative.
4. Never write into templates/, sibling projects, or promotion surfaces from this step. Promotion remains human-judged (user directive 2026-10-07); this step adds reporting and requests, moving no promotion authority (ADR-0031 unchanged).
5. Budget: review up to 3 landings per night; overflow is listed and carried to the next night first-in-first-reviewed. Pollination (Step 2c) is redefined to seed from these extracted assets, not only from backport diffs. The Friday FULL sweep reviews the cumulative week as the safety net for anything a nightly pass missed or degraded.
6. Skill-graph learning cross-reference (since 1.7.0): after Phase-I's skill-graph-fleet-report.ts snapshot exists, diff per-project skill sets and node counts against the prior snapshot. Project-side new skills this window join the extraction pass as candidates; a new/similar skill converging across ≥3 projects, or a fleet-report delivery gap (root skill missing from projects), files a skill-graph:-prefixed ticket row. Report-only — this never edits skills/, templates/, or projects.

Step 2f — Per-project review (cadence; since 1.7.0)

The fleet's project reviews previously happened only in ad-hoc sessions — the nightly cycle now carries a per-project review leg (design 2026-10-27-project-resync-coverage-design):

1. Battery ALWAYS (no agents): run each project's own bun scripts/audit.ts and record PASS/FAIL per project in the cycle report. Any FAIL → same-day ticket with the mandatory Class column.
2. SCOPED review for every project with a non-mechanical window landing (same set as Step 2 source (b)): one window-scoped read-only reviewer per project — Critical / High / Moderate / Strengths with file:line evidence, Class column (one-time / systemic / script-gap), in the cycle report's per-project section. Script-gap findings become validator-hardening tickets like any project-review run.
3. ROTATION safety net: when the scoped set is empty (or the night is heavy), review exactly one project per night by deterministic rotation — day-of-year mod N over the sorted fleet SSOT list (bun scripts/fleet-list.ts) — so every project is reviewed at least once per N nights even when quiet. State the rotated project in the report.
4. Budget binding: Step 2f reviewers share the nightly ≤4-agent cap with Phase 1b variant reviews and Step 2e extraction passes; on cap exhaustion, remaining projects degrade to battery-only with an explicit note and carry FIFO to the next night. Degraded cycle (Phase I ≥3 ERRORs) → battery-only, no reviewers.

Step 3 — Root PR

Standard /sync with the Step-2 report; merge before Step 4 (sequential branch rule — upgrades must see merged templates).

Step 4 — Upgrade projects

Per project: bun scripts/upgrade-project.ts Projects/<p> --dry-run --prune-removed → review category plan → run with the same flags → verify .claude/template-version.txt and project bun scripts/audit.ts.

--prune-removed is mandatory in this cycle: the upgrade engine is L0-only and the delivered tree carries no engine copy (ADR-0073 Amendments 1, 3 and 4 — the delivered scripts are validate-templates.ts plus the lib/ leaf modules upgrade-policy.ts, skills-registry.ts and platform-skeleton-merge.ts that project dev-sync.ts/validate-templates.ts import), so any project still holding a stray engine copy (scripts/upgrade-project.ts) gets it retired by this flag and drops the pruned script's registry row itself. A registered project-local script (SCRIPTS.md source cell = the variant name) is never pruned; if one still disappears, that is a pruner defect — file a ticket, do not hand-restore silently.

The delivered scripts' SCRIPTS.md registry rows reconcile automatically (common-registry fallback, layer rewrite, duplicate-row removal). Still proof-check the upgrade: bun scripts/verify-scripts.ts --verify per project must exit clean — an unregistered script there means the reconcile missed a case (report it, do not hand-patch silently). Upgrades must run on a clean tree: the pre-upgrade git stash push snapshot reverts uncommitted tracked changes. Note the upgrader is workspace-side only (L0, ADR-0073 Amendment 1) — invoke bun scripts/upgrade-project.ts … from the workspace root; from inside a project use bun ../../scripts/upgrade-project.ts ..

Step 5 — Upgrade PRs + final verification

Per project: dev-sync chore: upgrade template to <version>, merge CLEAN, default + pull + delete branches. Final gate: all projects have clean trees, 0 unpushed, 0 open PRs, passing audits; root audit + validate-templates pass.

Step 6 — Fleet branch cleanup + root final sync

After Step 5's merges:

1. Remote PR branches: for every project, delete merged pr/* branches — git -C <project> branch -r --merged origin | grep 'origin/pr/' → git -C <project> push origin --delete <branch>; then git fetch --prune. (Repos with auto-delete-on-merge need only the prune.)
2. Local PR branches: git -C <project> branch --list 'pr/*' → -D after verifying each is merged. Return every repo to its default branch + pull.
3. Root final sync: root must be on main, pulled, clean (git status).
4. Emit the final state table — per project: dirty / unpushed / open PRs / template version — all zeros before declaring the cycle complete.

Output Format

• Step 0: audit tables (script output) + applied-verdict summary per project.
• Steps 1/5: per-project PR URLs + merge states.
• Step 2: per-variant judgment report.
• Step 2b: evidence-backport-scan verdict table per project + human-triage rows.
• Step 2c: fleet echo-check verdict table per backport candidate.
• Step 2d: upstream request ledger (read-only upward-carrier report).
• Step 2e: learning-extraction outputs (including skill-graph cross-reference rows).
• Step 2f: per-project review section — battery table (all projects) + scoped/rotation findings.
• Cycle summary: one table — project → synced? / promoted? / reviewed? / upgraded? / final state.

Related Skills

• sync: single-repo commit→PR pipeline (used inside projects and at root).
• upgrade-project: L2→L3 delivery (Step 4).
• project-to-variant: standalone-project promotion (different concern — not part of this cycle).
• project-review: loop: project-review (diagnose) → project-resync (fleet sync/backport) → upgrade-project (deliver) → project-review baseline-only (verify).