Preserve workflow progress across metadata refreshes

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "name": "dk-workflows",
       "source": "./",
       "description": "dk-workflows",
-      "version": "1.3.0"
+      "version": "1.4.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dk-workflows",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Portable repository workflows, configurable reviewers, and guarded drafting.",
   "author": {
     "name": "Dmitry Kropachev"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dk-workflows",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Portable repository workflows, configurable reviewers, and guarded drafting.",
   "author": {
     "name": "Dmitry Kropachev"

PROVENANCE.json

@@ -72,6 +72,11 @@
       "source": "dk-code-factory/dk-workflows",
       "version": "1.2.0",
       "description": "Incremental preparation, conclusion graph, immutable evidence lineage, refresh validation and regression coverage."
+    },
+    {
+      "source": "dk-code-factory/dk-workflows",
+      "version": "1.4.0",
+      "description": "Fresh workflow metadata contracts: consistent plugin versions, revision-checked Decisions and publication ownership, engineering compatibility identity, durable captures and isolated checkouts, host guidance and regression coverage."
     }
   ]
 }

README.md

@@ -1,6 +1,6 @@
 # dk-workflows
 
-Independent MIT plugin for Claude Code and Codex. Version 1.3.0.
+Independent MIT plugin for Claude Code and Codex. Version 1.4.0.
 
 ## Install
 
@@ -237,7 +237,7 @@ when the host removes the original installation during lookup. Entry failures
 without a usable runtime receipt stop work; offline release checks still return
 a retained runtime and token and remain nonblocking.
 
-Preparation v2 retains stable conclusion dependencies and immutable evidence snapshots.
+Preparation v3 retains stable conclusion dependencies and immutable evidence snapshots.
 `prepare --previous-preparation FILE` compares complete Git entries and governing
 sources, reuses proven unchanged conclusions, and batches affected conclusions into
 one reassessment. Identical and supported operational refreshes use zero model calls;
@@ -248,10 +248,41 @@ Decisions synchronization and iteration budgets retain their existing gates. See
 
 Decisions can persist across independent runs by setting `DK_PR_DECISIONS_HOME` to
 an absolute private directory shared by those runs. It is the complete cache root:
-`<root>/<host>/<base-owner>/<base-repo>/pr-<number>.json`, including fork PRs.
+`<root>/v3/<host>/<base-owner>/<base-repo>/pr-<number>.json`, including fork PRs.
 When unset, the default remains `${XDG_DATA_HOME:-~/.local/share}/dk-pr-decisions`.
 Explicit stores are exclusive; invalid or repository-local paths fail without
 fallback. Hosts provide persistent storage and access. See the
 [Decisions storage contract](runtime/dk-pr-decisions/references/storage.md) for
 seeding, migration, locking and interruption recovery. Recovered choices require
 live context refresh and engineering preparation before dependent work.
+
+
+Fresh workflows allocate durable private directories under
+`${XDG_STATE_HOME:-~/.local/state}/dk-code-factory/workflows/`. Generated contexts,
+isolated checkouts, manifests, evidence captures and conflict proposals belong there;
+use the returned paths in handoffs. No automatic deletion policy applies. Preparation
+gates read owned captures; arbitrary external evidence defaults to live checks, so
+missing required rules or instructions still block. Live head/body, configuration
+and local-choice checks remain mandatory.
+
+`preparation_id` fingerprints the entire immutable artifact. Runtime-computed
+`engineering_id` fingerprints its normalized governing evidence, tree/base, scope,
+Decisions, ordered reviewer descriptors, analysis, readiness and policy. Supported
+operational counters/status/receipts, storage paths, refresh reports and verified
+lineage do not invalidate engineering compatibility; unknown fields still govern.
+Session v2 checkpoints, review-result v3 coverage, scope assessments and completion
+verification v2 can survive an operational refresh with the same engineering ID.
+Interrupted resume also requires the same head. Tree-equivalent cleanup retains its
+separate guarded reconciliation path. Provenance keeps exact preparation references.
+
+New Decisions storage uses `dk-pr-decisions/v3/` under the private data home. Each
+write checks a monotonic revision under the private-state lock; network/model work
+runs outside it. A stale write returns API v2 `status: error` with
+`error.code: metadata_conflict`, a retained proposal path and an explicit recovery
+action. The stable CLI reports a workflow block. Publication intent is committed
+before GitHub mutation; pending intent blocks other writers until its owner finishes
+or `publish --reconcile` verifies the outcome without replaying the edit. A validated
+legacy snapshot can be imported without changing its original file, including any
+pending intent. Legacy active iteration runs require their retained runtime; a fresh
+request after a terminal legacy run preserves history under the existing start rules.
+There is no bulk migration of old runs, results or checkpoints.

claude/skills/dk-pr-decisions/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the shared procedure](../../../runtime/dk-pr-decisions/procedure.md) and perform the requested workflow. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

claude/skills/dk-pr-iter/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the coordinator entry](../../../runtime/dk-pr-iter/procedure.md), then read each linked stage contract before acting in that stage. Give child agents only their assigned role contracts and pinned evidence paths. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

claude/skills/dk-pr-review/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the shared procedure](../../../runtime/dk-pr-review/procedure.md) and perform the requested workflow. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

codex/skills/dk-pr-decisions/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the shared procedure](../../../runtime/dk-pr-decisions/procedure.md) and perform the requested workflow. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

codex/skills/dk-pr-iter/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the coordinator entry](../../../runtime/dk-pr-iter/procedure.md), then read each linked stage contract before acting in that stage. Give child agents only their assigned role contracts and pinned evidence paths. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

codex/skills/dk-pr-review/SKILL.md

@@ -10,3 +10,5 @@ Before work, read [the lifecycle procedure](../../../common/lifecycle.md), then
 Read [the shared procedure](../../../runtime/dk-pr-review/procedure.md) and perform the requested workflow. Resolve paths beginning with `PLUGIN_ROOT/` against this plugin's root. Preserve the shared procedure's validation and publication guards.
 
 On preparation refresh, select the active artifact with `prepare --previous-preparation FILE`; follow [the incremental preparation contract](../../../runtime/dk-pr-decisions/references/preparation.md). Preserve review budgets and exact session/coverage gates.
+
+Fresh workflows use preparation v3, session v2, review-result v3 and completion-verification v2. Preserve both preparation and engineering IDs. Use returned private workflow paths for all generated evidence and child handoffs. Operational refresh may preserve engineering identity; validate current evidence and retained reviewer bindings before reuse. Resume legacy active runs only through their retained runtime. A Decisions `metadata_conflict` blocks dependent work: read its retained proposal and explicitly reconcile; never merge or replay publication automatically.

conftest.py

@@ -13,3 +13,8 @@ def run(argv, *args, **kwargs):
             raise AssertionError('Fixture attempted an unmocked model execution')
         return original(argv, *args, **kwargs)
     monkeypatch.setattr(subprocess, 'run', run)
+
+
+@pytest.fixture(autouse=True)
+def private_workflow_state(tmp_path_factory, monkeypatch):
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path_factory.mktemp("workflow-state")))

runtime/dk-pr-decisions/references/api.md

@@ -55,8 +55,8 @@ All former top-level command results now live under `data`; publication results
 
 `prepare --input-manifest FILE --output-dir PRIVATE_DIR [--previous-preparation FILE] [--full-analysis]` delegates to
 `scripts/preparation.py` without a discussion scan or any publication. It preserves
-this API v2 envelope; `data` contains `artifact`, `preparation_id`, `readiness` and a `refresh` report.
-The artifact has its own `preparation_version: 2`; read
+this API v2 envelope; `data` contains `artifact`, `preparation_id`, `engineering_id`, `readiness` and a `refresh` report.
+The artifact has its own `preparation_version: 3`; read
 [the preparation contract](preparation.md) for complete evidence, semantic analysis,
 question retention, placement, proportionate tests, and downstream gates.
 `verified: true` retains its original provenance/freshness meaning.
@@ -74,3 +74,24 @@ results retain `status: pending` with `publication.reason`, even if the pending
 array is empty. Dependent iteration stays `sync_pending` until live publication,
 context and preparation agree. Existing scan/list/context/add/replace/suggest
 commands and unified decision records retain their contracts.
+
+
+## Revision conflicts and pending publication
+
+The API envelope remains v2. Fresh records use private `dk-pr-decisions/v3/` storage
+and a monotonically increasing `revision`. Every commit compares the loaded revision
+under the existing file lock. Network and model calls run outside the lock. A stale
+writer receives `status: error`, `error.code: metadata_conflict`,
+`error.proposal_path` and `error.next_action`. The proposal retains the attempted
+update, expected/current revisions, record path and diagnostics. The stable CLI
+classifies it as a workflow block. Read the proposal and current state, reconcile
+any pending intent, and explicitly reapply the intended change against the current
+revision. Never merge, retry or replay publication automatically.
+
+Publication commits its owning operation's intent before GitHub mutation. A pending
+intent rejects competing writers, including refresh, additions and suggestions.
+Its owner can finish; after interruption use `publish --reconcile` to verify applied
+or unapplied state without replaying the mutation. Pending legacy intents remain
+blockers after import. Import validates the selected legacy snapshot and leaves its
+original file untouched. Existing interrupted workflows use their retained runtime;
+there is no bulk migration of active runs or immutable evidence.

runtime/dk-pr-decisions/references/preparation-contract.md

@@ -113,7 +113,7 @@ remain significant. Exact supported exceptions:
 
 ## Stored artifact and verification
 
-Immutable `preparation_version:2` artifacts retain `analysis`, graph/retired IDs,
+Immutable `preparation_version:3` artifacts retain `analysis`, graph/retired IDs,
 input fingerprints, reviewer descriptors, readiness, PR/base/head/body/Decisions
 identity, parent path/ID/hash and migration provenance. Snapshots are fingerprinted
 and read-only outside the repo. Historical validation checks retained integrity and
@@ -126,10 +126,27 @@ binding/identity changes, affected/reused conclusions, explanations and actual
 remain outside binding analysis. Tree-equivalent review reuse preserves original
 provenance only when existing scope/rules/Decisions/instruction/base checks pass.
 
-Completion verification has `verification_version:1`, current `preparation_id`,
+Completion verification has `verification_version:2`, originating `preparation_id`,
+runtime-computed `engineering_id`,
 `pr_url`, `head_sha`, and `checks` for `behavior`, `placement`, `test_sufficiency`,
 `compatibility`, `complexity`. Each check contains boolean `satisfied`, `rationale`,
 and nonempty `evidence`: `{"path":"ABSOLUTE_PATH","sha256":"FILE_HASH"}`.
 Inspection reports, code and test results qualify; missing, false or stale evidence
 blocks completion. Both stages use the same current preparation, verification and
 mutable run record; an immutable history snapshot cannot replace live choices.
+
+
+The complete artifact fingerprint is `preparation_id`; its runtime-computed
+`engineering_id` is the compatibility key. Store both. The latter excludes supported
+operational metadata, storage paths, reports and verified lineage, retaining unknown
+fields as governing. Reviewer order is explicit in `reviewer_order`. Sources retain
+`path`, `sha256`, immutable `snapshot`, and `mode` (`capture` or `live`). See the
+preparation procedure for capture defaults and manifest `source_modes` overrides.
+Never accept a supplied engineering ID without recomputation and current evidence
+and binding validation. Completion verification v2 remains reusable across an
+operational refresh with identical engineering identity and head; its preparation
+reference remains unchanged. Use workflow-owned evidence captures for verification
+reports intended to survive original export removal. Legacy verification v1 belongs
+to the retained legacy runtime. Fresh artifacts never rewrite historical checkpoints.
+
+`recovery_manifest` and `recovery_context` retain verified path/hash references to runnable private recovery inputs. Captured sources record `origin_identity`; recovery manifests carry `source_origins` to preserve identity while relocating captures. These declared storage fields do not govern engineering compatibility.