Asoba Asoba Open Source

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:

NEHANDA SDLC GOVERNANCE ENGINE — 11-PHASE STATE MACHINE Deterministic Phase Progression · Execution Provenance Gated · Zero Unapproved Code Mutations PHASE 00 idle Standby state · Free-form inquiry · Mutating Bash refused Safe Inquiries PROJECT CONTEXT SUPPLIED PHASE 01 explore Bounded repository survey · Read/Glob/Grep only · 20-req cap Read-Only Tools EXPLORATION CONVERGED / JEV PHASE 02 diagnose Evidenced root cause analysis · Observed vs expected behavior Diagnosis Text RECORDED DIAGNOSIS ARTIFACT PHASE 03 create_issue Bind issue identity · Create .issues/ artifact or cite GitHub #id Issue Metadata ISSUE RECORD REGISTERED PHASE 04 create_tests Author Given/When/Then test · Execute runner · PROVE RED Tests Only (RED) GENUINE RUNNER RED EVIDENCE PHASE 05 planning Plan Triad specification · Zero tools allowed · Human approval No Tools (Text) OPERATOR APPROVES PLAN [y/N] ✓ PHASE 06 implement Minimal production edits · Epistemic isolation · Code mutators All Tools (Code) CODE COMMITTED TO DISK PHASE 07 verify Execute unchanged original regression against code · PROVE GREEN Regression Run UNCHANGED TEST GREEN (PASS) ✓ PHASE 08 safety Run 3 safety checkers (JS/Shell/Py) + Branch coverage ≥ 70% Safety & Cov 3 CHECKERS 0-EXIT + ≥70% COV PHASE 09 confirm_fix Operator reviews full evidence · Explicit affirmative approval Human Sign-off OPERATOR CONFIRMS FIX ✓ PHASE 10 done Task completed · Authorized commit with #id · Update Project #4 Committed RESET ACKNOWLEDGED RETRY IMPL RETRY VERIFY lib/workflow.mjs · MANDATE_REJECT_REASONS · Schema v4 test_executions Provenance

The 11 Canonical Phases

0. idle

The resting state and post-completion reset state.

1. explore

Systematic, bounded repository survey.

2. diagnose

Root cause analysis and evidence documentation.

3. create_issue

Issue binding and artifact creation.

4. create_tests (TDD RED Phase)

Independent behavioral test authoring and failure verification.

5. planning

Concrete Plan Triad specification.

6. implement

Targeted production code implementation.

7. verify (TDD GREEN Phase)

Regression verification against current production code.

8. safety

Static analysis, safety checkers, and branch coverage validation.

9. confirm_fix

Final human review and operator sign-off.

10. done

Task completion, commit authorization, and reset.


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.