Skip to content

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

Open
jmjava wants to merge 23 commits into
mainfrom
cursor/architecture-review-milestones-8088
Open

jmjava wants to merge 23 commits into
mainfrom
cursor/architecture-review-milestones-8088

Conversation

@jmjava

@jmjava jmjava commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Summary

Architectural review (SPIKE-005) opened Milestones 3–5, then executed the P0 direction the review surfaced: there is exactly one engine (Python sdlc_engine) and one persistence model (storage v3 under sdlc-spdd/). No competing versions remain in code, tests, or docs.

Net: 249 files, +7,101 / −13,001.

Code (REF-002 / REF-003 / REF-005)

  • scripts/sdlc.sh is a thin dispatcher to python -m sdlc_engine; SDLC_ENGINE / SDLC_GATE_ENGINE and every shell fallback are gone.
  • Bash workflow twins deleted (sdlc-workflow.sh, sdlc-pointer.sh, sdlc-team-registry.sh, accept-lessons.sh, registry hook example).
  • New sdlc_engine.session bridge: start-agent-session.sh and capture-session-memory.sh call the engine for touch / brief / record-capture / Jira status / recommend.
  • cli_commands.py split into commands/{state,team,context,integrations,storage}.py; capture / complete pass unknown options through.
  • Storage v3 only: Project.home is SDLC_HOME or <root>/sdlc-spdd; legacy TSV registry, agent-context/ markers, storage migrate, agent_context_upgrade, legacy context parsers and framework-install consolidation helpers removed. upgrade-project.sh refuses pre-v3 trees instead of migrating them.
  • archive deletes Complete/Cancelled artifacts (git history retains them); no spdd/*/archive/ folders.
  • BUG-001 (NameError in db export --format sql) fixed; ensure_runtime_dirs no longer pre-creates committed spdd/memory/entries/.

Tests

  • Python: 406 unit+integration, 87 research — all green, fixtures routed through the sdlc-spdd home.
  • Bash: 29 harnesses share tests/lib/harness.sh and drive the engine via the dispatcher; twin-based harnesses replaced by test-upgrade-layout.sh. Full sweep green.
  • CI: test-workflow-harnesses.yml consolidates pointer/workflow/archive/gate harnesses; test-upgrade-layout.yml replaces test-upgrade-consolidate.yml; shellcheck.yml added; ruff widened to F,E9; PR-diff complexity gate added (CHORE-004).

Docs

  • README, TESTING, CONTRIBUTING, docs/*, engine/README, templates, command specs, research protocol and diagrams 02/03/06 describe only the single engine and v3 layout.
  • Dogfood adapter packs (.cursor, .claude, .github/prompts) and sdlc-spdd/docs/ regenerated from templates; validate-command-adapters.sh and generate-command-adapters.sh --check pass.

Planning artifacts

  • sdlc-spdd/requirements/milestones/milestone-{3,4,5}/ plus Obsidian-ready task lists in sdlc-spdd/spdd/tasks/.
  • Milestone 2 closed; ROADMAP.md updated.

Verification

406 passed (unit+integration)   87 passed (research)   ruff: All checks passed
29/29 bash harnesses PASS       render-diagrams --check: 14 ok
validate-command-adapters: PASS  generate-command-adapters --check: PASS
Open in Web Open in Cursor 

cursoragent and others added 23 commits September 13, 2026 23:26
One engine (Python sdlc-engine), one persistence model (storage v3), aligned
code/tests/docs. Adds the measured-baseline analysis, Milestone 3 (one flow),
Milestone 4 (docs truth), Milestone 5 (make-it-fast outline), 24 requirement
stubs, task lists including the Obsidian monthly goals, ROADMAP pointers, and
marks Milestone 2 complete. Registry: claim SPIKE-005.

Co-authored-by: John Menke <jmjava@gmail.com>
…inked_to_section.

db_query.py referenced _utc_now and NODE_*/REL_* constants without importing
them, so sdlc-engine db export --format sql crashed. Import utc_now, delete the
uncalled context_linked_to_section (the only user of the graph constants), and
add a round-trip regression test for export_sql and the CLI path.

Co-authored-by: John Menke <jmjava@gmail.com>
…eal gates.

Ruff select is F,E9 in pyproject/CI/test (was F401,F811, which let 9 undefined
names ship). test-sdlc-engine runs check-complexity.py against the PR base on
pull requests. New shellcheck workflow (bash -n + -S error) over scripts,
installed runtime templates, tests, and install.sh. Fixes the current
shellcheck errors: quoted glob in resolve-agent-context skill patterns never
expanded (SC2066), array-style expansion in setup-engine-venv (SC1087),
restore_victim redefinitions in test-command-specs (SC2218), [[ -f glob ]] in
the shim harness (SC2144). Drops four F541 f-strings. TESTING.md documents the
gates and fixes the stale 158-test count.

Co-authored-by: John Menke <jmjava@gmail.com>
…lders.

Python ArchiveService moved canvases/analysis/reviews/sync into spdd/*/archive/
and swept legacy agent-context/sessions, while the documented storage v3
contract (docs/storage-v3.md, TESTING.md, ROADMAP) and the shell path delete.
One contract now: remove canvas, analysis, review, sync, matching hot session
briefs, and the workflow .state; append the archived registry event; leave
requirements and lessons.jsonl untouched. Unit and CLI tests assert the same
behavior the bash harness already asserted; legacy feature-mirror seeding is
gone from the tests.

Co-authored-by: John Menke <jmjava@gmail.com>
…pter.

.cursor/commands, .claude/commands, and .github/prompts lagged the templates
(Kasana I1 Files: allowlist, DIF steps, whereami jira ask, next validation) in
13 files. Regenerated through framework_rewrite_adapter_paths, the same rewrite
the installer applies. test-command-specs.sh now diffs every slug in all three
packs against the rewritten template instead of two Cursor files; the workflow
triggers on Claude/Copilot dogfood paths too.

Co-authored-by: John Menke <jmjava@gmail.com>
init-project.sh writes sdlc-spdd/docs/, but the install guide, hub, upgrade
guide, cheat sheet, demo narration, and CONTRIBUTING said docs/sdlc-spdd/.
first-day expected results now match init output (single sdlc-spdd/ home,
no agent-context/). CONTRIBUTING's registry checklist names
spdd/memory/registry.jsonl, not work-registry.tsv. README states storage v3 is
the only supported layout instead of promising legacy consolidation. Shipped
copies under sdlc-spdd/docs re-synced for the five changed guides.

Co-authored-by: John Menke <jmjava@gmail.com>
Orchestrator docs pointed at agent-context/README.md, requirements/, and
ROADMAP.md at the repo root; they live under templates/ and sdlc-spdd/. Shipped
copies keep target-relative links (../requirements/) and drop the link to the
non-shipped agent-context README. Remaining 70 are install-boundary links from
shipped docs to orchestrator-only docs; CHORE-007 proper fixes the verifier.

Co-authored-by: John Menke <jmjava@gmail.com>
- Project.home is SDLC_HOME or <root>/sdlc-spdd; drop root/agent-context fallbacks
- TeamRegistry reads registry.jsonl only; remove work-registry.tsv path
- Delete storage_migrate and agent_context_upgrade (no legacy migration)
- Remove legacy markdown parsers from context_model
- installer.detect reports pre-v3 layouts as unsupported (reinit)
- integration_config drops issue-tracker-config.json fallback

Co-authored-by: John Menke <jmjava@gmail.com>
- Add sdlc_engine.session (brief, touch, record-capture, recommend, jira status/ask)
- New top-level verbs: quiet-status, start, capture, complete, accept, session
- Drop storage/agent-context CLI verbs
- Split cli_commands.py into commands/{state,team,context,integrations,storage}
- cli.py exports main/build_parser only; delete issue_tracker re-export shim

Co-authored-by: John Menke <jmjava@gmail.com>
- sdlc.sh execs python -m sdlc_engine; SDLC_ENGINE/SDLC_GATE_ENGINE removed
- Delete bash twins: sdlc-workflow.sh, sdlc-team-registry.sh, sdlc-pointer.sh,
  accept-lessons.sh, notify-team-registry hook
- start-agent-session/capture-session-memory call the engine via sdlc_engine_run
- upgrade-project refuses pre-v3 layouts (exit 3) and prunes retired twins;
  drop consolidate/archive helpers from framework-install.sh and skills.sh
- init/verify no longer install or check twins; verify asserts twins absent
- Replace consolidate harnesses with tests/test-upgrade-layout.sh
- live-consumer uses sdlc.sh pointer get/reset

Co-authored-by: John Menke <jmjava@gmail.com>
- adf_work, sync_local, local_sessions, installer (guide/viewer runtime,
  playground, guide_ops) use Project.home/spdd_dir/requirements_dir/sdlc_dir
- detect_target reports any pre-v3 path as unsupported (matches upgrade refusal)
- sync-roadmap default path is <home>/ROADMAP.md; shell wrapper delegates to engine
- scripts/lib/paths.sh sdlc_home drops the root fallback
- adapter installers always rewrite to sdlc-spdd/ paths; session brief hints v3-only

Co-authored-by: John Menke <jmjava@gmail.com>
- Route fixture paths through <root>/sdlc-spdd
- Drop storage_migrate/agent_context_upgrade tests and legacy seeds
- detect tests: v3 markers upgrade, pre-v3 layout unsupported
- public import test targets sdlc_engine.commands

Co-authored-by: John Menke <jmjava@gmail.com>
…ions through

- test_ref001_sut: sdlc.sh dispatcher rejects weak canvas; removed switches refused
- cli.main uses parse_known_args so 'sdlc.sh capture --summary ...' reaches the script
- engine-sut.md names the single Python engine
- cretrieve fixtures use the sdlc-spdd home

Co-authored-by: John Menke <jmjava@gmail.com>
…workflow

- tests/lib/harness.sh: installed v3 target fixture + sdlc.sh dispatcher helpers
- live-consumer: home is always sdlc-spdd/; export orchestrator engine for the target
- Merge test-archive-work / test-sdlc-pointer / test-sdlc-workflow workflows into
  test-workflow-harnesses.yml (Python 3.12 + pip install -e ./engine)
- test-upgrade-layout.yml installs the engine

Co-authored-by: John Menke <jmjava@gmail.com>
- All 29 harnesses use tests/lib/harness.sh and target the sdlc-spdd home;
  twin-script references removed
- session.py: capture/complete refusals go to stderr
- upgrade-project.sh: keep the orchestrator's dogfood adapter workflow
  instead of overwriting it with the target template

Co-authored-by: John Menke <jmjava@gmail.com>
…yout

- Remove SDLC_ENGINE/SDLC_GATE_ENGINE, bash twin, storage migrate,
  work-registry.tsv and consolidation references from README, TESTING,
  CONTRIBUTING, docs/, engine/README, templates, specs and research protocol
- TESTING.md: describe test-upgrade-layout and test-workflow-harnesses CI,
  v3-only upgrade contract, engine-backed pointer/workflow harnesses
- Diagrams 02/03/06 regenerated without storage_migrate / accept-lessons.sh
- Regenerate dogfood adapter packs and sdlc-spdd/docs copies

Co-authored-by: John Menke <jmjava@gmail.com>
The progress ledger writer creates its own parent; runtime setup must not
leave committed-tree side effects on every engine call (capture stages a
JSONL record only).

Co-authored-by: John Menke <jmjava@gmail.com>
…eview-milestones-8088

# Conflicts:
#	engine/src/sdlc_engine/cli_commands.py
#	engine/tests_unit/test_cli.py
#	engine/tests_unit/test_registry_archive.py
#	tests/test-sdlc-engine-shim.sh

Co-authored-by: John Menke <jmjava@gmail.com>
…dd home

- test-sdlc-engine.yml smoke step exported SDLC_ENGINE=python, which the
  dispatcher now rejects by design (exit 2)
- engine/tests_e2e wrote requirements/, spdd/ and .sdlc/ at the target root;
  the engine reads them under <root>/sdlc-spdd, so issue-sync tests failed
  with FileNotFoundError before any gh call

Co-authored-by: John Menke <jmjava@gmail.com>
check-complexity.py now recognises functions moved between changed/deleted
files (judged against their old CCN instead of as NEW) and silences git
noise for files absent from the base. The seven genuine findings are
refactored: cli.main, detect_target, cmd_accept, cmd_session, cmd_shell,
SessionService.brief_markdown and SessionService.capture split helpers out
so every function is at or below CCN 10.

Co-authored-by: John Menke <jmjava@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants