[feature] Machine-wide Prawduct sync sweep — one-click update across all projects

[Jason-Vaughan]

What

Add a single TangleClaw entry point that runs Prawduct framework sync across every TC-managed project on the machine in one operation, with per-project pass/skip/fail reporting and a clear surface for projects that need operator attention (local edits, broken state).

Concretely:

• New API endpoint: POST /api/admin/prawduct-sync-all
• New landing-page action: "Sync all projects to framework v" button next to the framework version badge
• Per-project result rows in the response: { project, status: 'updated'|'skipped'|'no-prawduct'|'error', changedFiles, skippedFiles, reason }
• Edit-preserving by default; no --force flag exposed in the UI (skipped files get surfaced as "needs operator review" rather than silently overwritten)

Why

Hit today (2026-05-29) during the v1.6.0 framework upgrade. The Prawduct framework checkout at ~/Documents/Projects/prawduct-test/prawduct was three minor versions behind (1.3.10 checked-out branch, 1.5.2 on main) when v1.6.0 landed upstream. The framework source was updated cleanly with git pull, but propagating that to all TC-managed projects required one of:

1. Lazy: open each project in TC one-at-a-time, let session-start sync handle it. Works, but takes hours of click-around for an operator with 15-20 projects, and silently leaves un-opened projects on the old framework.
2. Manual: shell-script a walk over ~/Documents/Projects/*/.prawduct/ and run prawduct-setup.py sync in each. Works, but requires shell and Prawduct-internals knowledge an operator shouldn't need.

Neither is the right shape. This problem recurs every time Prawduct ships a minor version. And on this machine specifically: the previous session's Critic finding (preserved in .prawduct/.session-handoff.md) already documented that the per-project session-start sync was actively downgrading tools/product-hook from 4182 → 2183 lines because a stale framework checkout was the sync source. A one-click eager sweep across all projects is the operational primitive that makes framework version upgrades safe and visible.

This is also a portfolio-credibility issue — TC's whole pitch is "central control plane for AI dev sessions." Not having a "sync all" for the methodology framework is a visible gap.

How (rough)

Backend (lib/api/admin.js or similar — add a new route):

• Read the TC projects list from data/projects.json (or wherever the canonical list lives).
• For each project, check whether .prawduct/sync-manifest.json exists. If not → status no-prawduct.
• Read framework_source from each project's manifest; default to the TC-wide configured framework dir if absent.
• Shell out to python3 <framework_source>/tools/prawduct-setup.py sync <project_dir> --json --no-pull for each project. (--no-pull because the framework should already be at the desired version; the operator updates the framework first, then sweeps. The sweep itself doesn't git pull per-project.)
• Aggregate JSON results into the response.

Frontend (public/landing.js):

• Add a "Sync all projects to framework v" button near the framework version badge. Disabled state if framework dir not configured or unreachable.
• On click: confirmation modal listing how many projects will be touched. Operator confirms → POST the endpoint.
• Render a modal/table with per-project results: name, status (color-coded), changed file count, skipped file count, link to "Open project" for any with error or non-zero skippedFiles.

Engine-profile-ish config:

• data/framework-config.json (new) with prawduct: { sourceDir, lastSweepAt, lastSweptVersion } — lets the UI show "Last machine-wide sweep: 2 days ago at v1.5.2" so operators know when they're drifting.

Where

• lib/api/admin.js (new route handler) or extend existing admin endpoints
• lib/prawduct-sync.js (new helper) — wraps the per-project shell-out, handles timeouts, collects results
• public/landing.js — button + result modal
• data/framework-config.json — new persisted state
• test/prawduct-sync.test.js — unit tests for the wrapper, integration test against a fixture project tree

Acceptance

• One-click sweep on the landing page successfully syncs every Prawduct-using project on the machine in one operation.
• Result table shows pass/skip/no-prawduct/error per project, with reason text for skipped/errored entries.
• Edit-preserving by default — projects with local template edits are reported as skipped with the filenames, NOT silently overwritten.
• Sweep is idempotent (running twice in a row when nothing's changed is a no-op).
• Framework version mismatch surfaces clearly — if the framework checkout is at v1.5.2 but landing-page badge says v1.6.0 is available, the badge shows a "framework needs update" indicator before the sweep button activates.
• Operator can dismiss/resolve "skipped due to local edits" entries from the UI (link to project + diff view).

Related

• TC [feature] Codex pre-flight model validation at session launch #260 (Codex pre-flight model validation) — same operational shape: surface framework-side state to the operator before it bites
• TC [feature] Surface engine API errors in session UI (Codex 400s, etc.) #261 (engine error surfacing) — same family: make hidden state visible
• The recurring problem will hit again on Prawduct v1.7, v1.8, etc. — this is preventative infrastructure.
• Spec reference for the v1.6.0 advisory infrastructure (which makes per-project advisories visible in the same way this issue makes framework currency visible): documentation/post-sync-advisory-spec.md in the Prawduct framework repo.

Notes

The minimum viable version is just the API endpoint + a CLI wrapper script. The landing-page button is the operator-friendly version. Even shipping V0 as "scriptable endpoint + curl example in CLAUDE.md" would be a real improvement over the current state.