Skip to content

README.md

Latest commit

 

History

History
116 lines (89 loc) · 4.74 KB

README.md

File metadata and controls

116 lines (89 loc) · 4.74 KB
Raw

SDLC Engine (v2)

Python orchestration engine for the SDLC-SPDD operating model.

Shell scripts remain the v1 compatibility surface. This package is the v2 reusable core: pointer, workflow phases/gates, team registry, archive, and a stable CLI/API that assistants and tools can call without bash.

Status

Alpha (2.0.0a6). Core workflow commands are implemented in Python and covered by pytest. Install/upgrade/adapter generation still use the existing shell scripts; the engine can shell out to them via sdlc-engine shell … when needed.

Quick start

Requires Python 3.12 (engine/pyproject.toml, same as CI). From the orchestrator repo:

sudo apt install python3.12 python3.12-venv   # once
./scripts/setup-engine-venv.sh --e2e
source .venv/bin/activate

# CLI entry
sdlc-engine next
sdlc-engine claim FEAT-001-demo
sdlc-engine archive --all --dry-run

Or without activating the venv:

.venv/bin/python -m sdlc_engine next --root .

Or through the sdlc.sh dispatcher, which always runs this engine:

./scripts/sdlc.sh next

./scripts/sdlc.sh local start --name scratch --intent "explore without a FEAT"
./scripts/sdlc.sh local promote --type feature --name "Documented title"
./scripts/sdlc.sh db rebuild
./scripts/sdlc.sh db query --search "orchestration"
./scripts/sdlc.sh db lookup --work-id FEAT-001-example --markdown
./scripts/sdlc.sh commit-message --hint "summarize current changes"
./scripts/sdlc.sh sunset --work-id FEAT-001-example --apply

Package layout

Module Responsibility
timeutil / io_util / placeholders Shared UTC stamps, JSON/path helpers, TBD sentinels
project Resolve project root and artifact paths
phases Phase order, gates, recommended assistant commands
pointer .sdlc/pointer get/set/reset + guarded run
workflow Resume/advance/skip/shelf/sync/next/status
registry spdd/memory/registry.jsonl claim/release/team/list-work (legacy TSV fallback)
archive Remove Complete/Cancelled work artifacts (git history retains them)
canvas Final Status + next-operation inference
links / sync_local Milestone↔canvas↔registry drift check/repair + ROADMAP sync
issues Draft/push/pull Jira (JIRA_*) or GitHub (gh) from milestone sections
jira_format Markdown ↔ ADF; optional ADF→wiki shim (adf_to_wiki) for Server/DC — raw ADF is default on Cloud v3
issues CLI draft / push / pull / upload-adf / download-adf — explicit only; --description-format adf|wiki
local_sessions LOCAL-* offline sessions + promote into documented Work IDs
db / db_schema / db_rebuild / db_query Regenerable local SQLite index (.sdlc/index.sqlite) before GUIDE
commit_message Staged/unstaged/ahead-of-base diff report for commit-message drafts
sunset Close-out snapshot: GitHub PR + issue + commits + Jira → lesson ledger
viewer ADF WYSIWYG editor for checked-in adf/*.json (optional [viewer] / Flask)
installer / console / dashboard EXPERIMENTAL ops console: install/upgrade, SQLite, rollback, Guide+Neo4j, ADF viewer lifecycle (optional [viewer] / Flask)
cli / cli_parser / commands/ sdlc-engine / python -m sdlc_engine (CommandResult per verb)

Two local GUIs + Guide map: docs/ops-console.md (Guide pin for console dogfood: jmjava/orch-guide tag sdlc-spdd-projection-v2).
ADF editor runbook: docs/adf-viewer.md.

python3 -m pip install -e './engine[dev,viewer]'
./scripts/sdlc.sh console --target /path/to/app --port 5051   # ops UI
./scripts/sdlc.sh viewer --root /path/to/app --port 5050      # ADF editor

Compatibility

  • File formats stay identical (.sdlc/, spdd/memory/registry.jsonl, canvas paths).
  • Shell sdlc.sh is a thin dispatcher into this engine; it requires Python 3.12 and an importable sdlc_engine and has no bash fallback (REF-003).
  • SDLC_ENGINE=python is accepted as a no-op; SDLC_ENGINE=shell and SDLC_GATE_ENGINE=shell are rejected.

Tests

python3 -m pip install -e './engine[dev,viewer]'
pytest -q engine/tests_unit

Or without install (viewer tests need Flask):

PYTHONPATH=engine/src python3 -m pytest -q engine/tests_unit

Three suites — see TESTING.md:

./scripts/run-test-suites.sh unit          # engine/tests_unit
./scripts/run-test-suites.sh integration # engine/tests_integration (+ installer cov)
./scripts/run-test-suites.sh e2e         # engine/tests_e2e (Playwright, gh, optional --guide)

Design notes

See docs/engine-v2.md and spdd/canvas/FEAT-006-python-orchestration-engine.md.