REF-003: retire bash workflow dual path

.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. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message`.
 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`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset`.
 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. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message`.
 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`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset`.
 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. In the orchestrator repo this always routes to `python -m sdlc_engine commit-message`.
 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`. In the orchestrator repo this always routes to `python -m sdlc_engine sunset`.
 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-workflow.yml

@@ -3,9 +3,8 @@ name: Test SDLC Workflow
 on:
   pull_request:
     paths:
-      - 'templates/agent-context/sdlc-workflow.sh'
-      - 'templates/agent-context/sdlc-pointer.sh'
-      - 'templates/agent-context/sdlc-team-registry.sh'
+      - 'engine/src/sdlc_engine/**'
+      - 'engine/tests_unit/**'
       - 'templates/agent-context/README.md'
       - 'scripts/start-agent-session.sh'
       - 'scripts/capture-session-memory.sh'
@@ -22,9 +21,7 @@ on:
       - 'templates/cursor/rules/sdlc-spdd.mdc'
       - 'templates/copilot/copilot-instructions.md'
       - 'templates/claude/CLAUDE.md'
-      - 'tests/test-sdlc-workflow.sh'
-      - 'tests/test-sdlc-pointer.sh'
-      - 'tests/test-archive-work.sh'
+      - 'tests/test-sdlc-engine-shim.sh'
       - 'tests/test-verify-receipt.sh'
       - 'tests/test-gate-review-validation.sh'
       - 'tests/test-gate-advisory-visible.sh'
@@ -37,9 +34,8 @@ on:
   push:
     branches: [main]
     paths:
-      - 'templates/agent-context/sdlc-workflow.sh'
-      - 'templates/agent-context/sdlc-pointer.sh'
-      - 'templates/agent-context/sdlc-team-registry.sh'
+      - 'engine/src/sdlc_engine/**'
+      - 'engine/tests_unit/**'
       - 'templates/agent-context/README.md'
       - 'scripts/start-agent-session.sh'
       - 'scripts/capture-session-memory.sh'
@@ -56,9 +52,7 @@ on:
       - 'templates/cursor/rules/sdlc-spdd.mdc'
       - 'templates/copilot/copilot-instructions.md'
       - 'templates/claude/CLAUDE.md'
-      - 'tests/test-sdlc-workflow.sh'
-      - 'tests/test-sdlc-pointer.sh'
-      - 'tests/test-archive-work.sh'
+      - 'tests/test-sdlc-engine-shim.sh'
       - 'tests/test-verify-receipt.sh'
       - 'tests/test-gate-review-validation.sh'
       - 'tests/test-gate-advisory-visible.sh'
@@ -74,13 +68,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install Python engine
+        run: python3 -m pip install -e './engine[dev]'
 
       - name: Check shell syntax
         run: |
-          bash -n templates/agent-context/sdlc-pointer.sh
-          bash -n templates/agent-context/sdlc-workflow.sh
           bash -n scripts/sdlc.sh
-          bash -n tests/test-sdlc-workflow.sh
+          bash -n tests/test-sdlc-engine-shim.sh
           bash -n tests/test-verify-receipt.sh
           bash -n tests/test-gate-review-validation.sh
           bash -n tests/test-gate-advisory-visible.sh
@@ -92,11 +89,15 @@ jobs:
           bash -n scripts/lib/paths.sh
           bash -n scripts/validate-command-adapters.sh
 
-      - name: Run SDLC pointer regression tests
-        run: ./tests/test-sdlc-pointer.sh
-
-      - name: Run SDLC workflow regression tests
-        run: ./tests/test-sdlc-workflow.sh
+      - name: Run Python workflow, pointer, archive, and CLI regressions
+        run: >
+          PYTHONPATH=engine/src pytest -q
+          engine/tests_unit/test_workflow.py
+          engine/tests_unit/test_workflow_gates.py
+          engine/tests_unit/test_pointer.py
+          engine/tests_unit/test_registry_archive.py
+          engine/tests_unit/test_cli.py
+          engine/tests_unit/test_cli_shell.py
 
       - name: Run I1 verify-receipt proving tests
         run: ./tests/test-verify-receipt.sh
@@ -113,5 +114,5 @@ jobs:
       - name: Run leftover #16 constraint-honesty proving tests
         run: ./tests/test-quality-gates-constraint-honest.sh
 
-      - name: Run archive-work regression tests
-        run: ./tests/test-archive-work.sh
+      - name: Run Python dispatcher regression tests
+        run: ./tests/test-sdlc-engine-shim.sh

CHANGELOG.md

@@ -37,12 +37,28 @@ All notable changes to this project will be documented in this file.
 
 ### Removed
 
+- REF-003: the bash workflow twin — `sdlc-workflow.sh`, `sdlc-team-registry.sh`,
+  and `sdlc-pointer.sh` — from `templates/agent-context/` and
+  `sdlc-spdd/scripts/` (3,100 shipped LOC). Init and upgrade no longer install
+  them, upgrade deletes the exact retired paths, and install verification
+  asserts their absence. Their shell harnesses
+  (`test-sdlc-workflow.sh`, `test-sdlc-pointer.sh`, `test-archive-work.sh`)
+  are replaced by `engine/tests_unit/` coverage (#321).
 - REF-002: pre-v3 consolidation, layout migration, TSV registry fallback,
   migration-only parsers and CLI verbs, duplicate-canvas synchronization, and
   executable root-layout fallbacks. Storage v3 is the only runtime layout.
 
 ### Changed
 
+- REF-003: `scripts/sdlc.sh` is a thin dispatcher that requires Python 3.12 and
+  an importable `sdlc_engine`, with no bash fallback. `SDLC_ENGINE=shell` and
+  `SDLC_GATE_ENGINE=shell` now exit non-zero instead of selecting a second
+  implementation; `SDLC_ENGINE=python` stays accepted as a no-op. The retained
+  `start-agent-session.sh`, `capture-session-memory.sh`, and
+  `accept-lessons.sh` utilities call the engine, and `sdlc-engine shell`
+  resolves helpers in both orchestrator `scripts/` and installed
+  `sdlc-spdd/scripts/` layouts. Operator, testing, engine, and research docs
+  describe one mandatory engine (#321).
 - Milestone 3 (one flow on storage v3) opened from SPIKE-005: Python
   `sdlc-engine` is the only engine, storage v3 the only persistence model;
   pre-v3 compatibility and the bash workflow twin are removed, not

README.md

@@ -225,7 +225,7 @@ Python engine (same surface, importable):
 
 ```bash
 python3 -m pip install -e './engine[dev,viewer]'
-SDLC_ENGINE=python ./scripts/sdlc.sh next
+./scripts/sdlc.sh next
 sdlc-engine context retrieve --work-id FEAT-001-order-status
 sdlc-engine context backends
 ```

STARTER-SPEC.md

@@ -268,10 +268,7 @@ Create the repo with this structure:
     │   ├── sync/
     │   └── memory/               # lessons.jsonl + registry.jsonl
     ├── .sdlc/                    # gitignored runtime (sessions, staged, sqlite)
-    ├── agent-context/            # workflow scripts in dogfood repo only
-    │   ├── sdlc-pointer.sh
-    │   ├── sdlc-workflow.sh
-    │   └── sdlc-team-registry.sh
+    ├── agent-context/            # dogfood repo only
     │   └── harness/              # dogfood mirror of harness/
     │       ├── validation-rules.md
     │       └── quality-gates.md