{
  "$comment": "Framework migration manifest. The upgrade skill loads this, subtracts the project's migrations.json ledger, and replays outstanding steps by applyMode. Steps are idempotent / skipIfPresent so cold-start replay no-ops already-satisfied changes. See docs/storage-contract.md § Migrations.",
  "manifestVersion": 1,
  "releases": [
    {
      "version": "0.12.0",
      "summary": "Glossary becomes the core term spine (single canonical home for every domain term); ADR is the one optional doc type via docs.types.",
      "steps": [
        {
          "id": "0.12.0-docs-types-registry",
          "version": "0.12.0",
          "description": "Introduces docs.types — an optional array enabling the ADR doc type beyond the always-on core (PRD/Spec/Story/Glossary). Additive and opt-in for ADR: a project that doesn't set docs.types keeps core behavior with no loss. Records that the registry capability is available; enables nothing. To adopt ADR, set docs.types to [\"adr\"] in storage.json (re-run setup-agent-kit's optional-doc-types question, or edit directly) and the kit creates the adrs/ subdir on first use.",
          "type": "structural",
          "target": "config",
          "applyMode": "auto",
          "skipIfPresent": "always idempotent — records availability only, enables nothing"
        },
        {
          "id": "0.12.0-glossary-core-subdir",
          "version": "0.12.0",
          "description": "Glossary is now a core doc type — the single canonical home for every domain term. For filesystem doc providers, ensure the glossary/ subdir exists under docs.path. No-op for remote providers (the type is native) and for workspaces that already have a glossary dir.",
          "type": "structural",
          "target": "doc-store",
          "applyMode": "auto",
          "skipIfPresent": "glossary subdir (or remote glossary type) already present under docs.path"
        },
        {
          "id": "0.12.0-extract-terms-to-glossary",
          "version": "0.12.0",
          "description": "Migrate the distributed terms model to the glossary spine. For each domain term currently defined inline — in a Spec's Key concepts section or a PRD's inline product-term definitions — create a glossary note (glossary/<slug>.md) holding the canonical definition, then replace the inline definition with a [[term-slug]] citation. Spec Key concepts becomes an index of citations; the PRD cites. One owner per term: if the same term is defined in two places, reconcile to a single note and cite from both. This rewrites live doc-store content, so it is guided — per-term, human-in-the-loop, surfacing each proposed note and the citations that will replace the inline text before writing. Skip generic programming terms (they were never glossary material).",
          "type": "data",
          "target": "doc-store",
          "applyMode": "guided",
          "skipIfPresent": "no Spec Key concepts or PRD inline term definitions remain (all terms already live as glossary notes)"
        }
      ]
    },
    {
      "version": "0.11.0",
      "summary": "Story becomes a first-class requirement artifact; doc status ladder gains Proposed/Accepted/Implemented.",
      "steps": [
        {
          "id": "0.11.0-docs-status-ladder",
          "version": "0.11.0",
          "description": "Extend docs.statuses to the shared ladder draft|proposed|accepted|implemented|superseded|archived. Adds the role names if absent; preserves any project-custom display names already mapped.",
          "type": "structural",
          "target": "config",
          "applyMode": "auto",
          "skipIfPresent": "docs.statuses has accepted and implemented roles"
        },
        {
          "id": "0.11.0-requirements-storyhome",
          "version": "0.11.0",
          "description": "Add requirements.storyHome (default \"docs\") to storage.json. Selects the canonical home that owns story ID and status.",
          "type": "structural",
          "target": "config",
          "applyMode": "auto",
          "skipIfPresent": "requirements.storyHome is set"
        },
        {
          "id": "0.11.0-remap-active-docs",
          "version": "0.11.0",
          "description": "Remap existing docs at the old 'active' status to 'accepted' (the conservative floor — never falsely claim Implemented). Set 'implemented' only where a verifying-test trace confirms the behavior shipped. Touches every PRD/Spec/Story in the doc store.",
          "type": "data",
          "target": "doc-store",
          "applyMode": "guided",
          "skipIfPresent": "no docs remain at a legacy 'active' status"
        },
        {
          "id": "0.11.0-extract-inline-stories",
          "version": "0.11.0",
          "description": "For PRDs with inline user stories: extract each story to a Story artifact in the configured storyHome, and replace the PRD's inline bodies with a generated story index (link per story). Existing requirement IDs (e.g. MEM-US-1.2) remain valid citations — the story's home keeps them as its stable ID; only new stories use the home's native ID. Scenarios, edge cases, and acceptance criteria move to the Story.",
          "type": "data",
          "target": "doc-store",
          "applyMode": "guided",
          "skipIfPresent": "no PRD in the doc store contains inline story bodies"
        }
      ]
    }
  ]
}