Workflow Contract (Agent Constitution) v1.0

This contract governs deterministic, phase-based development under DIDP.

1. Purpose & Authority

This contract defines:

  • how work is conducted
  • what artifacts override others
  • phase constraints and permitted actions
  • restart/compaction safety behavior

This contract supersedes conversational memory and agent intuition.

2. Source of Truth Hierarchy

Resolve conflicts using this order:

  1. iteration_state.yaml (authoritative)
  2. this contract (docs/workflow_contract.md)
  3. phase artifacts (spec, implementation plan, roadmap)
  4. git repository state (branches/tags/history)
  5. conversational context (lowest priority)

If conflict exists, higher authority always wins.

3. Mandatory Session Bootstrap

At session start, the agent MUST:

  1. Load and obey docs/workflow_contract.md
  2. Load iteration_state.yaml and treat it as ground truth
  3. Identify the current phase and constraints
  4. Load ONLY artifacts referenced by the current phase
  5. Resume from handoff_notes.next_recommended_action
  6. Update iteration_state.yaml as progress is made

If documents are missing, inconsistent, or ambiguous: STOP and report.

4. Phase Obedience

Global rules:

  • The agent MUST NOT perform out-of-phase work.
  • The agent MUST refuse requests that violate phase rules.
  • The agent MUST NOT advance phases unless exit criteria are satisfied.
  • The agent MUST update iteration_state.yaml when meaningful progress is made.
  • The agent MUST NOT silently reinterpret scope or goals.

5. Conversational Mode by Phase

PhaseConversation Style
planningOpen exploration and back-and-forth allowed
analysisClarifying questions allowed; scope changes forbidden
spec_lockStructured finalization; no re-opening planning without explicit replan trigger
implementationMinimal conversation; execution-focused clarifications only
testingMinimal; defect-focused only
archiveMechanical; no scope/code changes
mergeMechanical; no feature work
completeRetrospective only

6. Replan Protocol (Formal)

In analysis, if assumptions are invalidated, the agent MUST record:

analysis_outcome:
  replan_required: true
  reason: >
    Explicit explanation.

When replan_required: true:

  1. The conductor halts forward progression.
  2. Phase is reset to planning.
  3. The replan event is recorded in iteration_state.yaml and committed to git.

Silent replanning is forbidden.

7. Auto-Advance

If phase.auto_advance: true, phase may advance ONLY when:

  • all exit criteria are satisfied
  • the transition is legal
  • iteration_state.yaml is updated and committed

Partial satisfaction is insufficient.

8. Ambiguity, Errors, and Refusal

The agent MUST:

  • ask for clarification when artifacts conflict
  • refuse out-of-phase work
  • surface uncertainty explicitly
  • prefer stopping over guessing

9. Compaction & Restart Safety

Sessions are disposable. After compaction/reset:

  • rely on artifacts, not chat memory
  • resume from iteration_state.yaml
  • if state is missing or inconsistent, STOP

10. Completion & Handoff

At phase completion, the agent MUST:

  • update iteration_state.yaml
  • commit changes
  • write handoff_notes including risks/decisions/next action