One Python engine, one v3 persistence model: code, tests, docs aligned (Milestones 3–5)

.claude/commands/sdlc-spdd-commit-message.md

@@ -10,7 +10,7 @@ Your job is to draft a commit message from the current local changes. Collect th
 
 1. Parse optional arguments: a short user hint and an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, omit Work ID from the message unless the user hint includes one.
-3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message` even when `SDLC_ENGINE=shell`.
+3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known.
 4. Use the engine report as the source of truth for which files/diff to message (source is staged, else unstaged, else commits/diff since merge base). If the engine exits non-zero or reports nothing to commit, report that failure and stop. Do not invent a message.
 5. Draft a paste-ready commit message: a concise subject line (imperative mood, ~72 chars); an optional body with why/what when the change needs more than the subject; incorporate the user hint when provided; include the Work ID in the subject or body when known (for example `FEAT-008: …` or a `Work-ID:` trailer).
 6. Prefer one focused commit message for the current change set. Do not rewrite unrelated history.

.claude/commands/sdlc-spdd-sunset.md

@@ -15,7 +15,7 @@ Your job is to close out a Work ID by collecting GitHub PR, GitHub issue, commit
 
 1. Parse an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, stop and ask for a Work ID.
-3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset` even when `SDLC_ENGINE=shell`.
+3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`.
 4. Use the engine report as the source of truth for Jira key/status, GitHub issue and PR number/title/state/URL, and matching commits. If the engine exits non-zero, report that failure and stop. Do not invent issue, PR, commit, or Jira facts.
 5. Treat missing remotes as warnings, not a hard stop, when the engine still produced a snapshot (for example `gh` is not installed, or Jira credentials are unset). Report every warning from the engine.
 6. After a successful `--apply`, the engine has staged a `session` record (`source=sunset`) in `sdlc-spdd/.sdlc/staged/lessons.jsonl`. Recommend `/sdlc-spdd-accept` to promote it into `sdlc-spdd/spdd/memory/lessons.jsonl`. Do not edit the ledger by hand.

.cursor/commands/sdlc-spdd-commit-message.md

@@ -10,7 +10,7 @@ Your job is to draft a commit message from the current local changes. Collect th
 
 1. Parse optional arguments: a short user hint and an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, omit Work ID from the message unless the user hint includes one.
-3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message` even when `SDLC_ENGINE=shell`.
+3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known.
 4. Use the engine report as the source of truth for which files/diff to message (source is staged, else unstaged, else commits/diff since merge base). If the engine exits non-zero or reports nothing to commit, report that failure and stop. Do not invent a message.
 5. Draft a paste-ready commit message: a concise subject line (imperative mood, ~72 chars); an optional body with why/what when the change needs more than the subject; incorporate the user hint when provided; include the Work ID in the subject or body when known (for example `FEAT-008: …` or a `Work-ID:` trailer).
 6. Prefer one focused commit message for the current change set. Do not rewrite unrelated history.

.cursor/commands/sdlc-spdd-sunset.md

@@ -10,7 +10,7 @@ Your job is to close out a Work ID by collecting GitHub PR, GitHub issue, commit
 
 1. Parse an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, stop and ask for a Work ID.
-3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset` even when `SDLC_ENGINE=shell`.
+3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`.
 4. Use the engine report as the source of truth for Jira key/status, GitHub issue and PR number/title/state/URL, and matching commits. If the engine exits non-zero, report that failure and stop. Do not invent issue, PR, commit, or Jira facts.
 5. Treat missing remotes as warnings, not a hard stop, when the engine still produced a snapshot (for example `gh` is not installed, or Jira credentials are unset). Report every warning from the engine.
 6. After a successful `--apply`, the engine has staged a `session` record (`source=sunset`) in `sdlc-spdd/.sdlc/staged/lessons.jsonl`. Recommend `/sdlc-spdd-accept` to promote it into `sdlc-spdd/spdd/memory/lessons.jsonl`. Do not edit the ledger by hand.

.github/prompts/sdlc-spdd-commit-message.prompt.md

@@ -15,7 +15,7 @@ Draft a commit message from the current local changes. Collect the diff through
 
 1. Parse optional arguments: a short user hint and an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, omit Work ID from the message unless the user hint includes one.
-3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message` even when `SDLC_ENGINE=shell`.
+3. Collect the change set by running the Python engine (required — do not improvise with raw git when the engine is available): `./sdlc-spdd/scripts/sdlc.sh commit-message` with `--hint` / `--work-id` when known.
 4. Use the engine report as the source of truth for which files/diff to message (source is staged, else unstaged, else commits/diff since merge base). If the engine exits non-zero or reports nothing to commit, report that failure and stop. Do not invent a message.
 5. Draft a paste-ready commit message: a concise subject line (imperative mood, ~72 chars); an optional body with why/what when the change needs more than the subject; incorporate the user hint when provided; include the Work ID in the subject or body when known (for example `FEAT-008: …` or a `Work-ID:` trailer).
 6. Prefer one focused commit message for the current change set. Do not rewrite unrelated history.

.github/prompts/sdlc-spdd-sunset.prompt.md

@@ -15,7 +15,7 @@ Close out a Work ID by collecting GitHub PR, GitHub issue, commit, and Jira stat
 
 1. Parse an optional Work ID. Do not invent Work IDs.
 2. If Work ID is omitted, try the active pointer via `./sdlc-spdd/scripts/sdlc.sh next` (or `./sdlc-spdd/scripts/sdlc.sh next` in the orchestrator repo) or `sdlc-spdd/.sdlc/sessions/current-session.md`. If still unknown, stop and ask for a Work ID.
-3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset` even when `SDLC_ENGINE=shell`.
+3. Collect tracker and git close-out state by running the Python engine (required — do not improvise with raw `gh`, Jira HTTP, or `git log` when the engine is available): `./sdlc-spdd/scripts/sdlc.sh sunset --work-id <WORK-ID> --apply`.
 4. Use the engine report as the source of truth for Jira key/status, GitHub issue and PR number/title/state/URL, and matching commits. If the engine exits non-zero, report that failure and stop. Do not invent issue, PR, commit, or Jira facts.
 5. Treat missing remotes as warnings, not a hard stop, when the engine still produced a snapshot (for example `gh` is not installed, or Jira credentials are unset). Report every warning from the engine.
 6. After a successful `--apply`, the engine has staged a `session` record (`source=sunset`) in `sdlc-spdd/.sdlc/staged/lessons.jsonl`. Recommend `/sdlc-spdd-accept` to promote it into `sdlc-spdd/spdd/memory/lessons.jsonl`. Do not edit the ledger by hand.

.github/workflows/test-sdlc-engine.yml

@@ -76,9 +76,9 @@ jobs:
           --cov-fail-under=90
       - name: CLI smoke via sdlc.sh
         run: |
-          SDLC_ENGINE=python ./scripts/sdlc.sh version
-          SDLC_ENGINE=python ./scripts/sdlc.sh next
-          SDLC_ENGINE=python ./scripts/sdlc.sh viewer --help
+          ./scripts/sdlc.sh version
+          ./scripts/sdlc.sh next
+          ./scripts/sdlc.sh viewer --help
       - name: Shim regression harness
         run: ./tests/test-sdlc-engine-shim.sh
 

.github/workflows/test-upgrade-consolidate.yml → .github/workflows/test-upgrade-layout.yml

@@ -1,4 +1,4 @@
-name: Test Upgrade Consolidate
+name: Test Upgrade Layout
 
 on:
   pull_request:
@@ -10,9 +10,8 @@ on:
       - 'scripts/lib/framework-install.sh'
       - 'scripts/lib/skills.sh'
       - 'templates/**'
-      - 'tests/test-upgrade-consolidate.sh'
-      - 'tests/test-framework-install-consolidate.sh'
-      - '.github/workflows/test-upgrade-consolidate.yml'
+      - 'tests/test-upgrade-layout.sh'
+      - '.github/workflows/test-upgrade-layout.yml'
   push:
     branches: [main]
     paths:
@@ -23,26 +22,28 @@ on:
       - 'scripts/lib/framework-install.sh'
       - 'scripts/lib/skills.sh'
       - 'templates/**'
-      - 'tests/test-upgrade-consolidate.sh'
-      - 'tests/test-framework-install-consolidate.sh'
-      - '.github/workflows/test-upgrade-consolidate.yml'
+      - 'tests/test-upgrade-layout.sh'
+      - '.github/workflows/test-upgrade-layout.yml'
 
 jobs:
-  test-upgrade-consolidate:
+  test-upgrade-layout:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install engine
+        run: python -m pip install -q -e ./engine
+
       - name: Check shell syntax
         run: |
           bash -n scripts/upgrade-project.sh
           bash -n scripts/verify-project-install.sh
           bash -n scripts/lib/framework-install.sh
-          bash -n tests/test-upgrade-consolidate.sh
-          bash -n tests/test-framework-install-consolidate.sh
-
-      - name: Unit — framework-install consolidate helpers
-        run: ./tests/test-framework-install-consolidate.sh
+          bash -n tests/test-upgrade-layout.sh
 
-      - name: Integration — upgrade layout consolidation
-        run: ./tests/test-upgrade-consolidate.sh
+      - name: Integration — upgrade layout contract (v3 only)
+        run: ./tests/test-upgrade-layout.sh