workspace_closeout

You are tasked to close out abandoned work in a domain workspace so a new planning cycle can begin over clean ground. This is a FRESH context window — you have no memory of the cycle whose remains you are about to archive. Everything you need is on disk. </role>

This procedure is the remediation for a BLOCKED planning readiness verdict. forgectl refuses to begin a planning cycle over a domain whose workspace still holds a previous cycle's plan.json, evals, and implementation logs — starting fresh over that material silently mixes stale work into new planning and overwrites artifacts nobody reconciled. The scaffold detects the condition and stops. It never writes the archive and never deletes a workspace. You do both.

The archive answers, for a reader six months from now: what was this cycle trying to build, how far did it get, what landed in the codebase, and what was abandoned unfinished? </task>

<step_0> Confirm the verdict and scope the work

Never start from an assumption that a workspace is dirty. Get the list from forgectl:

forgectl preflight --from <plan-queue.json>
# or, inside a session with a generated queue:
forgectl preflight

A BLOCKED verdict names every dirty domain and its workspace path:

Planning readiness: BLOCKED
The following domain workspaces contain prior-cycle artifacts:
  - protocols   protocols/.forge_workspace/
  - launcher    launcher/.forge_workspace/

That list is your entire scope. Close out those domains and no others. A dirty workspace belonging to a domain outside the incoming plan queue is not your concern — the gate ignores it deliberately, and so do you.

If the verdict is READY, there is nothing to close out. Stop and say so.

Resolve the workspace directory name from .forgectl/config (paths.workspace_dir, default .forge_workspace) rather than assuming it — projects configure it, and .forgectl_workspace is also in use. The blocked verdict prints the resolved path for each domain; prefer that.

Process one domain completely (steps 1–5) before starting the next. </step_0>

<step_1> Inventory the workspace — read everything before writing anything

List every file in the domain's workspace, at any depth:

find <domain>/<workspace_dir> -type f

Read all of them. A workspace left by a full cycle typically holds:

Do not skim. The archive replaces these files permanently, and anything you fail to read is lost when you delete them. If a file is unreadable or malformed, record that fact in the archive rather than dropping it.

Then establish what actually landed in the codebase. The plan tells you what was intended; git tells you what shipped:

git log --oneline -30 -- <domain>/
git log --diff-filter=A --oneline -- <domain>/<workspace_dir>

Cross-reference the plan's completed items against real commits. An item marked PASS whose files never appear in a commit is exactly the kind of discrepancy the archive exists to record. </step_1>

<step_2> Write the ExecPlan archive

Write to docs/execplans/<domain>/<YYYY-MM-DD>-<slug>.md, relative to the project root — outside every workspace directory, so the archive survives step 4. The date is the close-out date; the slug names the abandoned initiative (ledger-reconciliation, not cycle-2).

Create the directory if it does not exist. If a file with that name already exists, append -2, -3 rather than overwriting — a prior archive is itself durable work.

Structure:

# ExecPlan Archive — <Domain>: <Initiative>

## Provenance
- **Domain:** <domain>
- **Workspace archived:** <domain>/<workspace_dir>/
- **Archived on:** <YYYY-MM-DD>
- **Session:** <session_id from the state file, or "unrecoverable">
- **Last workspace activity:** <mtime of the newest file>

## What This Cycle Was Building
<Two to four paragraphs. The intent behind the plan, drawn from plan.json's
name and the planning notes. Written for someone with no context.>

## Plan Inventory
<Every layer, batch, and item from plan.json, with its terminal status.
One row per item. Include items never started — the gap is the point.>

| Layer | Item | Status | Rounds | Files |
|-------|------|--------|--------|-------|

## What Landed in the Codebase
<Commits attributable to this cycle, with hashes and what each contains.
Explicitly flag any item marked complete in the plan with no commit behind it.>

## Evaluation History
<Verdicts by round, per item or batch. Recurring FAIL reasons matter most —
they are the ones a future cycle will hit again.>

## Abandoned Unfinished
<Items not terminal, work in progress, known-broken states left in the tree.
Be specific enough to act on.>

## Notes and Reasoning Worth Keeping
<Salvage from the planning notes: decisions made, alternatives rejected and
why, constraints discovered. Discard restatements of the plan.>

## Resuming This Work
<What a future cycle should know before re-planning this domain. Where to
start, what to distrust, what has since changed underneath it.>

Every section is required. Where a source is absent — no notes file, no evals — write "None present in the workspace" rather than omitting the heading. A reader must be able to distinguish "this cycle produced nothing here" from "the archivist skipped it."

Summarize; do not transcribe. A 400-line plan.json becomes an inventory table, not an appendix. But never summarize away a failure, a discrepancy, or an unfinished item. </step_2>

<step_3> Verify the archive against the inventory, then commit it

Walk the file list from step 1 and confirm every file is represented in the archive. Then:

git add docs/execplans/<domain>/<YYYY-MM-DD>-<slug>.md
git commit -m "docs: archive abandoned <domain> workspace before planning close-out"

Commit the archive before deleting anything. This ordering is the whole safety property of the procedure: until the archive is committed, the workspace is the only copy of the work. Do not batch this commit with the deletion, and do not defer it to the end of a multi-domain close-out.

forgectl performs no git operations here regardless of general.enable_commits — close-out runs outside any phase. You commit. </step_3>

<step_4> Clear the workspace

Only after step 3's commit exists:

rm -rf <domain>/<workspace_dir>
git add -A <domain>/
git commit -m "chore: clear <domain> workspace after close-out"

Removing the directory entirely is correct — the gate treats an absent directory as clean, and the phase recreates it when it needs it. Leaving empty subdirectories behind also passes, but serves no purpose.

Delete only the workspace directory of the domain you are closing out. Nothing above it, nothing in a sibling domain. </step_4>

<step_5> Confirm, then resume the blocked operation

After the last domain:

forgectl preflight --from <plan-queue.json>

Expect Planning readiness: READY. If it still reports BLOCKED, a domain was missed or a file was recreated — return to step 0 with the new list; do not proceed.

A .gitkeep or other placeholder counts as content and will keep a domain blocked. The rule is strict on purpose: any regular file at any depth is dirty. Remove it.

Then re-run whatever the gate refused — forgectl init --phase planning --from <plan-queue.json>, or forgectl advance at the blocked phase shift. It now proceeds into planning ORIENT. </step_5>

<contextual_information>

Where this sits

preflight: BLOCKED  →  workspace_closeout (THIS skill)  →  preflight: READY  →  planning ORIENT
   (gate refuses)        (archive, then clear)              (gate passes)

The gate is defined in forgectl/specs/planning-readiness-gate.md. Two properties of it shape this procedure:

• It is stateless. The verdict is "does this domain's workspace contain a regular file," nothing more. It has no record of what was planned before and cannot tell your archive from the work it archived. Emptiness is the only signal it reads.
• It runs once per cycle, at cold start. It inspects every domain in the incoming plan queue when planning begins, and does not re-inspect at domain boundaries — a finished domain's full workspace is the expected result of the cycle, not stale cruft. So close-out is a precondition of starting a cycle, not something you run between domains.

What the gate does not guarantee

The gate verifies the workspace is empty. It cannot verify an archive was ever written. A hand-cleared workspace passes exactly like a properly closed-out one. The archival discipline lives entirely in this procedure — which is precisely why the archive is committed before the deletion, and why rm -rf never comes first.

Interruption

Every step is re-runnable, and the ordering makes interruption safe at any point:

There is no interruption point at which committed work is lost, because nothing is deleted until its archive is in git.

</contextual_information>

Archive before delete, always

The commit in step 3 must exist before the rm in step 4. No exceptions, no batching, no "I'll commit both at the end."

Scope is the blocked list

Close out the domains forgectl named. Do not clean up a dirty workspace you happened to notice elsewhere.

Read every file before deleting it

Deletion is permanent. An unread file is an unarchived file.

The archive lives outside every workspace

docs/execplans/ at the project root. An archive written inside a workspace is deleted by step 4.

Never edit the plan or the codebase

Close-out archives and clears. It does not fix failing items, finish abandoned work, or amend plan.json. That is the next cycle's job, informed by what you wrote.

Record discrepancies, don't resolve them

An item marked PASS with no commit behind it goes in the archive as a discrepancy. Do not investigate it into a conclusion the evidence does not support.

<IMPORTANT_INFO>

999 Commit the archive BEFORE deleting the workspace. Until that commit lands, the workspace is the only copy of the work.

999 forgectl never writes an archive and never deletes a workspace. Both are yours. The scaffold only reports readiness and refuses to proceed without it.

9999 The gate cannot tell a closed-out workspace from one someone emptied by hand. Passing preflight is not evidence the work was archived — this procedure is the only thing that makes that true.

9999 One domain at a time, steps 1 through 4 complete, before starting the next.

</IMPORTANT_INFO>