SDLC Workflow
Nehanda CLI enforces a deterministic, 11-phase software development lifecycle through a governed state machine (lib/workflow.mjs, lib/orchestrate.mjs). LLM prose, model claims, or arbitrary terminal commands cannot authorize phase transitions or bypass human approval gates.
Every phase specifies an explicit tool mask, evidence requirement, and human approval boundary. If the required execution evidence is missing or invalid, the engine rejects the transition and enforces the legal retry path.
State Machine Architecture
The runtime state machine operates across 11 canonical states, forming a closed, evidence-gated lifecycle:
The 11 Canonical Phases
0. idle
The resting state and post-completion reset state.
- Objective: Clean operational state. Inquiries about project architecture or general questions are handled here.
- Tool Constraints: Free-form read tools available. Mutating actions (
Bashrunning destructive commands,Write,Edit) are rejected by the idle safety guard. - Transition Forward: Advances to
explorewhen the user provides an objective and confirms SDLC initiation.
1. explore
Systematic, bounded repository survey.
- Objective: Discover existing modules, functions, and architecture contracts before planning any code changes.
- Tool Constraints: Strictly restricted to
Read,Glob, andGrep. Mutating tools (Write,Edit,Bash,NotebookEdit) are blocked. - Exploration Guardrails:
- Documentation-First Ordering: Scans
docs/MAP.md, root docs, and schema definitions before source files. - Jev-Mem Hot Path: If prior durable memory contains sufficient context, disk exploration is bypassed.
- Bounded Budget Ceiling: Allows up to 20 productive requests. The 21st request is blocked, forcing a handoff to
diagnose. - Stagnation Detection: Repeated identical reads or zero-hit queries trigger early exit to prevent loops.
- Documentation-First Ordering: Scans
2. diagnose
Root cause analysis and evidence documentation.
- Objective: Document the observed buggy or missing behavior, expected behavior, and evidenced cause before proposing any fix.
- Tool Constraints: Read-only analysis. No mutations permitted.
- Gate Requirement: The engine requires a substantive diagnosis record before advancing to issue creation.
3. create_issue
Issue binding and artifact creation.
- Objective: Associate the task with an explicit issue record (Project #4).
- Execution: Generates a structured Markdown artifact inside
.issues/(capturing issue ID, title, observed behavior, diagnosis, and acceptance criteria) or binds to an existing GitHub issue number. - Tool Constraints: Controlled issue creation. Production code cannot be touched.
4. create_tests (TDD RED Phase)
Independent behavioral test authoring and failure verification.
- Objective: Write a behavioral Given-When-Then regression test that fails against the current codebase, evidencing the bug or missing capability.
- Tool Constraints: Mutation is restricted strictly to test directories (
tests/**,test/**). Production source code modifications are blocked. - Execution Provenance (RED Gate):
- The test runner must be executed via
Bash. - The failure must be a genuine assertion failure (exit code $\ne 0$ from a recognized test runner like
node,pytest,bash). - Syntax errors, module import failures, runner crashes, timeouts, or simulated failures are rejected by the gate.
- The execution details (command, failure digest, input hashes, timing) are recorded in
test_executions(schema v4).
- The test runner must be executed via
5. planning
Concrete Plan Triad specification.
- Objective: Synthesize exploration and RED test evidence into a complete, file-by-file implementation plan.
- Tool Constraints: Zero tools available. The model must produce only structured text.
- Plan Triad Structure:
- Files & Functions: Exhaustive list of files to touch and existing functions to modify (no duplicates).
- Categorized Behaviors: Precise list of behaviors
CREATED,UPDATED, orREMOVED. - Verification Matrix: Given-When-Then mapping linking each behavioral change to test assertions.
- Human Gate: The plan is displayed to the operator:
"Approve this plan? [y/N]". Explicit affirmative operator confirmation is required. Missing input capability denies authorization.
6. implement
Targeted production code implementation.
- Objective: Apply the minimal approved edits to satisfy the failing test.
- Tool Constraints: All editing tools available (
Write,Edit,Bash, etc.). - Epistemic Filter: Implementation blocks in conversation history are filtered to prevent test-generation models from cheating during verification.
- Gate Requirement: Code edits must be committed to the working directory.
7. verify (TDD GREEN Phase)
Regression verification against current production code.
- Objective: Execute the original, unchanged regression test authored in Phase 04 against the freshly modified production code.
- Gate Requirement (GREEN Gate):
- Must execute against the current production snapshot (
sourceSnapshotSHA-256 validation). - If the test was altered during this phase, or if source files were changed after running the test, verification is invalidated.
- Test runner must return exit code 0 (clean PASS).
- Must execute against the current production snapshot (
8. safety
Static analysis, safety checkers, and branch coverage validation.
- Objective: Validate that no regressions, security violations, or untested branches were introduced.
- Gate Requirements:
- Three Mandatory Safety Checkers: All three must pass with exit code 0:
node lib/scripts/js-safety-checker.cjs .(JS/TS syntax and static integrity)bash lib/scripts/shell-safety-checker.sh .(Shell script quoting, safety, and POSIX compliance)python3 lib/scripts/python-safety-checker.py .(Python AST, type safety, and security checks)
- Production Branch Coverage: Changed production files must demonstrate measured branch coverage $\ge 70\%$. A zero exit code without qualifying branch coverage is rejected.
- Three Mandatory Safety Checkers: All three must pass with exit code 0:
9. confirm_fix
Final human review and operator sign-off.
- Objective: Present the completed verification results, test outputs, safety checker status, and coverage metrics to the human operator.
- Human Gate: Requires affirmative operator confirmation. Rejection returns execution to the legal retry state (
safetyorimplement).
10. done
Task completion, commit authorization, and reset.
- Objective: Commit the authorized changes with the bound issue reference in the commit message (e.g.
fix: align phase tool availability (#44)), report actual Git outcomes, and update issue tracking. - Reset Transition: The transition
done → idleacknowledges session reset, clears transient exploration caches (explore.mjs), and retains durable Jev-Mem observations in SQLite.
State Transition & Gating Matrix
Transitions are strictly validated by canTransition() and MANDATE_REJECT_REASONS (lib/workflow.mjs):
| Transition | Direction | Required Gate Evidence | Rejection Mandate |
|---|---|---|---|
idle → explore |
Forward | Project context & user task submission | AGENTS 1: Missing project context for exploration |
explore → diagnose |
Forward | Completed exploration or 20-req budget ceiling | AGENTS 1–2: Exploration incomplete or unbounded |
diagnose → create_issue |
Forward | Documented root cause & expected behavior | AGENTS 2–3: Diagnosis evidence missing |
create_issue → create_tests |
Forward | Registered issue artifact under .issues/ or GitHub #id |
AGENTS 3–4: Issue record required before tests |
create_tests → planning |
Forward | Executed behavioral RED runner failure recorded in DB | AGENTS 4–5: RED test evidence required before plan |
planning → implement |
Forward | Approved Plan Triad + Prior RED + Human [y/N] gate |
AGENTS 5–7: Approved Plan Triad + prior RED required |
implement → verify |
Forward | Implementation code applied to disk | AGENTS 7: Implementation not accepted / missing code |
verify → safety |
Forward | Original unchanged regression passes GREEN | AGENTS 8: GREEN verification evidence required |
safety → confirm_fix |
Forward | 3 safety checkers exit 0 + Branch coverage $\ge 70\%$ | AGENTS 8–9: All 3 safety checkers + ≥70% coverage |
confirm_fix → done |
Forward | Affirmative operator confirmation | AGENTS 9–10: Operator did not confirm fix |
done → idle |
Forward | Session reset acknowledgment | AGENTS 10: Session reset unacknowledged |
verify → implement |
Retry | Failing regression (GREEN failure) | Legal retry edge on broken fix |
safety → verify |
Retry | Checker failure or coverage $< 70\%$ | Legal retry edge on failed checker |
confirm_fix → safety |
Retry | Operator requests additional verification | Legal retry edge on operator revision |
planning → create_tests |
Retry | Flawed plan or missing test coverage | Legal retry edge on plan revision |
diagnose → explore |
Retry | Insufficient discovery evidence | Legal retry edge for further exploration |
Tool Availability by Phase
Tools are strictly masked at the orchestrator boundary (filterToolsByPhase in lib/orchestrate.mjs) and the execution boundary (lib/tools.mjs). A model attempt to call an unauthorized tool is intercepted and returned as an error result:
Tool Write is not available in explore phase. Use Read, Glob, or Grep to gather evidence and let the SDLC harness own phase transitions.
| Phase | Read, Glob, Grep | Write, Edit, NotebookEdit | Bash | WebFetch, WebSearch | Notes |
|---|---|---|---|---|---|
idle |
Allowed | Ask / Gated | Refused if mutating | Allowed | Free-form exploration mode |
explore |
Allowed | Denied | Denied | Allowed | Strictly read-only exploration |
diagnose |
Allowed | Denied | Denied | Allowed | Evidence synthesis |
create_issue |
Allowed | Issue files only | Denied | Allowed | Writes restricted to .issues/ |
create_tests |
Allowed | Test files only | Allowed (Test runner) | Allowed | Production source code edits denied |
planning |
Denied | Denied | Denied | Denied | Zero tools; structured text only |
implement |
Allowed | Allowed | Allowed | Allowed | Production implementation |
verify |
Allowed | Denied | Allowed (Test runner) | Allowed | No source or test changes allowed |
safety |
Allowed | Denied | Allowed (Checkers) | Allowed | Automated checker scripts only |
confirm_fix |
Allowed | Denied | Denied | Allowed | Human review |
done |
Allowed | Denied | Allowed (Git commit) | Allowed | Commit and push only |
Epistemic Filter
During test creation and verification, an epistemic filter (applyEpistemicFilter in lib/transcript.mjs) redacts implementation details (such as SEARCH/REPLACE blocks and diff payloads) from the context provided to the model:
[implementation details redacted for epistemic isolation]
This prevents the model from generating tests that merely mirror implementation quirks, ensuring test assertions evaluate genuine behavioral requirements rather than reverse-engineering the code.