state-hub/workplans/STATE-WP-0083-forge-derived-projection-reset.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related
STATE-WP-0083	workplan	Forge-derived projection reset, per repository	infotech	state-hub	active	codex	infotech	2026-08-25	2026-08-25	CUST-ADR-012 CUST-WP-0068

Forge-derived projection reset, per repository

Goal

Implement ADR-012 decision 7: discard a repository's projection and rebuild it from what Forgejo holds. Per repository, routine, idempotent, and verifiable.

This is the only sanctioned way to remove a hub record. The hub has no hard-delete for work records — DELETE /tasks/{id} is cancel_task, DELETE /workstreams/{id} is 410 Gone, and no session.delete exists for either. Re-derivation is not one option among several; it is the mechanism.

Why here and not in Repo Manager

ADR-012 decision 1 says central derives from the forge, and the pod can reach it: git ls-remote https://forgejo.coulomb.social/... succeeds anonymously from inside the cluster, and git is already in the image.

Driving the reset from Repo Manager would mean computing a projection on a workstation and pushing it into central — precisely the injection of derived state ADR-010 decision 5 forbids. Central must do its own reading. The cost is that workplan parsing exists in two places; scripts/consistency_check.py already parses frontmatter and task blocks here, so the capability is present and should be extracted rather than rewritten.

What it must not do

• Not restore preliminary overlay records. They exist because the forge does not hold them; a rebuild from the forge cannot reproduce them and must not pretend to.
• Not destroy hub-native records. Progress events, decisions and inbox messages originate in the hub (ADR-010 decision 4). They are not forge-derived and must survive a rebuild of forge-derived state.
• Not proceed silently when records would be lost. Stop, name them, and require an explicit acknowledgement.

Derive a repository's projection from the forge

id: STATE-WP-0083-T01
status: todo
priority: high

Given a repository slug, clone or fetch its default branch from Forgejo into a temporary location, parse the workplan files, and compute the projection that state would produce: workplans, tasks, their identifiers, statuses and backing paths.

Read-only and side-effect free. Record the commit the derivation came from — ADR-012 decision 2 requires provenance, and the existing git_fingerprint is worthless precisely because nothing ever wrote it correctly.

Acceptance: deriving the-custodian twice from the same commit yields identical output, and the commit is reported.

Report the difference before changing anything

id: STATE-WP-0083-T02
status: todo
priority: high

Compare the derived projection against what the hub currently holds for that repository, and report: records the forge has that the hub lacks, records the hub has that the forge does not, and records whose fields differ.

This is the half that is immediately useful without any destructive capability, and it is what makes decision 7's "verifiable" real. It also answers the question CUST-WP-0068-T09 is waiting on — which stale rows would actually clear — before anyone commits to clearing them.

Acceptance: a dry-run diff for a repository with known drift matches what manual inspection shows.

Apply the reset transactionally

id: STATE-WP-0083-T03
status: todo
priority: high

Replace the repository's forge-derived records with the derived projection in one transaction: create what is missing, update what differs, remove what no longer derives. Hub-native records are untouched.

Refuse by default when removal would destroy a record with no counterpart in the forge; report what would be lost and require an explicit acknowledgement to proceed. That refusal is evaluated per repository, so one unresolved repository never blocks the rest.

Acceptance: reset twice produces the same projection; a repository holding records the forge lacks is refused with those records named; hub-native record counts are unchanged across a reset.

Fleet form as a loop over the repository form

id: STATE-WP-0083-T04
status: todo
priority: medium

The fleet-wide reset iterates the per-repository reset and shares its implementation, so the rarely-used dangerous path is exercised by the frequently used safe one. Repositories that refuse are skipped and reported, never aborting the pass.

Acceptance: a fleet dry-run reports per-repository outcomes including refusals, and completes despite them.

Retire what the reset replaces

id: STATE-WP-0083-T05
status: wait
priority: medium

Once reset is trusted, CUST-WP-0068-T09 can clear its stale rows — 4 workplan rows from the prefix migration and 305 task rows across 44 workplans.

ADR-003 decision 2's mtime-based fingerprints should also be replaced by the source commit at this point; ADR-012 invalidated that composition and the replacement belongs with the provenance work in T01.

Acceptance: CUST-WP-0068-T09 closes; no fingerprint input depends on a local filesystem.