Skip to content

MIGRATION.md

Latest commit

 

History

History
51 lines (43 loc) · 3.21 KB

MIGRATION.md

File metadata and controls

51 lines (43 loc) · 3.21 KB
Raw

Migrating from v1

Use START_HERE.md for new work. Existing v1 projects do not need to rename their six-file project pack or three-file initiative pack.

  1. Preserve current status, decisions, evidence and unfinished gates. Identify which v1 records remain active; historical completion claims stay historical.
  2. Add a versioned adoption note to existing guidance when persistent adoption is authorized. Record the source revision and local adaptations.
  3. Use v2's authority boundary: host and applicable policy first; status is a claim checked against evidence. Do not elevate old document ordering over actual rules.
  4. Select relevant modules from the task and risk. Map new obligations into existing records instead of creating a parallel control system.
  5. Collapse redundant future recordkeeping where useful. Existing documents can remain; v2 removes mandatory document counts, not valuable history.
  6. Check adapters and prompts for conflicting defaults. Thin native pointers can coexist. Never overwrite unrelated target instructions while upgrading.
  7. Revalidate changed behavior and resume unresolved work. Migration itself does not turn pending or deferred gates into passes.

The preserved v1 guide, legacy manuals, template packs and examples are labeled reference material. Old saved prompts must explicitly select v1 to use its workflow; otherwise follow v2 and retain only relevant task intent.

Between v2 previews

Pin the helper used to validate historical records. Machine records declare an exact framework version; a preview.1 record is not silently accepted by preview.2. For ongoing work, review the new controls, create an updated record with the current version, reroute its facts/policies and revalidate the evidence. Keep the original record and evidence intact. Preview.2 makes policy-file ordering irrelevant without weakening content hashes or allowing recorded policies to be omitted.

Preview.3 keeps schema 1 and existing record fields, adding optional gate requires lists and optional current-snapshot checking. New snapshots and pending-record generation require no target adoption files. Existing helpers cannot interpret the new gate field, so keep historical records/helpers pinned. For ongoing work, review required evidence kinds and current input coverage before collecting fresh evidence. The new nonfunctional routing signals add controls without changing existing facts.

Preview.4 retains schema 1, the snapshot format and CLI commands. Snapshot capture now rejects observed changes during a file read. A previously accepted unstable capture may return exit 2; isolate the inputs and capture again. Preserve earlier records with their original helper/version rather than relabeling old evidence.

Preview.5 retains schema 1 and the existing CLI/snapshot formats. Repository validation additionally rejects stale README and newest changelog version metadata. Use main for current instructions or the v2.0.0-preview.5 tag for a fixed source; the older v2 branch preserves an earlier preview. For active machine records, review the updated guidance, regenerate with the current version and recheck current evidence. Keep earlier records and their helpers unchanged.