Workflow Contract (Agent Constitution) v3.1

Related Documentation

• DIDP v1 Specification — The normative protocol spec
• Phase Model — Phase state machine and transitions
• Artifact Inventory — Complete catalog of DIDP artifacts
• Canonical Prompts — Bootstrap and recovery prompts

---

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. .jellylabs.ai/didp/iteration_state.yaml (authoritative)
2. this contract (.jellylabs.ai/didp/workflow_contract.md)
3. deviations.log (learned violations - append-only)
4. phase artifacts (spec, implementation plan, roadmap)
5. git repository state (branches/tags/history)
6. 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 .jellylabs.ai/didp/workflow_contract.md
2. Load .jellylabs.ai/didp/iteration_state.yaml and treat it as ground truth
3. Read deviations.log and learn from past violations
4. Identify the current phase and constraints
5. Load ONLY artifacts referenced by the current phase
6. Resume from handoff_notes.next_recommended_action
7. Update .jellylabs.ai/didp/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 .jellylabs.ai/didp/iteration_state.yaml when meaningful progress is made.
• The agent MUST NOT silently reinterpret scope or goals.

5. Conversational Mode by Phase

• planning: open exploration and back-and-forth are allowed.
• analysis: clarifying questions allowed; scope changes forbidden.
• spec_lock: structured finalization; no re-opening planning without explicit replan trigger.
• implementation: minimal conversation; execution-focused clarifications only.
• testing: minimal; defect-focused only.
• archive: mechanical; no scope/code changes.
• merge: mechanical; no feature work.
• complete: retrospective 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 .jellylabs.ai/didp/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
• .jellylabs.ai/didp/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 .jellylabs.ai/didp/iteration_state.yaml
• if state is missing or inconsistent, STOP

10. Completion & Handoff

At phase completion, the agent MUST:

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

11. Versioning Policy (v2)

11.1 SemVer Requirement

Semantic Versioning (SemVer) is mandatory for protocol specifications:

• Major: Breaking changes to protocols or public interfaces
• Minor: New features, backwards compatible
• Patch: Bug fixes, documentation corrections

11.2 Bump Intent Declaration

All iterations SHOULD declare version bump intent at spec_lock phase:

versioning:
  scheme: semver
  planned_bump: minor  # major|minor|patch

If versioning.enforcement: required, this becomes MUST.

11.3 Version Source

Each project MUST have exactly one canonical version source:

• VERSION file, or
• package.json / pyproject.toml / equivalent, or
• Git tag

The version source MUST be updated during the archive phase.

11.4 Changelog Requirements

When versioning.changelog_required: true:

• Changelog entry MUST be created during implementation
• Entry MUST describe changes in user-facing terms
• Entry MUST be committed before phase advancement to testing

11.5 Enforcement Levels

Level	Behavior
required	Phase transitions blocked if versioning rules violated
recommended	Warnings emitted but transitions allowed

Default enforcement level is recommended.

12. Testing Policy (v3)

12.1 Testing Strategy Declaration

All iterations SHOULD declare testing strategy at spec_lock phase:

testing_strategy:
  methodology: tdd | test-after | hybrid
  coverage_target: 80
  required_test_levels:
    - unit
    - integration
  evidence_required: true
  enforcement: required | recommended

If testing_strategy.enforcement: required, methodology declaration becomes MUST.

12.2 Methodology Semantics

Methodology	Requirement
tdd	Tests MUST be written before implementation code
test-after	Tests MUST be written before testing phase exit
hybrid	Critical paths use TDD, non-critical may use test-after

12.3 Phase-Level Testing Rules

Phase	Testing Requirement
planning	Define acceptance criteria and test scenarios
analysis	Validate requirements are testable
spec_lock	Declare testing_strategy.methodology
implementation	Follow declared methodology
testing	Execute validation, defect-only fixes
archive	Preserve evidence if evidence_required: true

12.4 TDD vs Testing Phase

TDD belongs inside the implementation phase, not instead of the testing phase:

• TDD: Build correctly (implementation phase)
• Testing phase: Prove correctness (testing phase)

Both are complementary, not substitutes.

12.5 Enforcement Levels

Level	Behavior
required	Phase transitions blocked if testing rules violated
recommended	Warnings emitted but transitions allowed

Default enforcement level is recommended.

13. Foundation Task Ledger (FTL) Integration

13.1 Purpose

The Foundation Task Ledger (FTL) is the canonical intake system for all foundation work:

• Ideas, proposals, tasks, and decisions
• Reference: Foundation Task Ledger

13.2 Entry Workflow

1. Capture — Add entry with status: Idea
2. Evaluate — Human reviews, updates to Proposed or Rejected
3. Review — Discussion/analysis, status: Under Review
4. Decide — Human decides: Accepted, Rejected, or Deferred
5. Implement — If Accepted, create iteration and work
6. Close — Update status to Complete with artifact link

13.3 Authority Constraint

Only human authority can transition entries past Idea status.

The agent MAY:

• Add entries with status Idea
• Propose status changes
• Draft entry content

The agent MUST NOT:

• Unilaterally advance entry status
• Self-approve proposals
• Skip FTL for substantive work

13.4 FTL vs Iteration

Work Type	Intake	Execution
Ideas/Proposals	FTL entry (status: Idea)	None until approved
Accepted tasks	FTL entry (status: Accepted)	Iteration required
Trivial work	FTL-014 exemption (if approved)	maintenance.log

13.5 Trivial Work Exemption (FTL-014)

When FTL-014 is accepted, trivial work MAY bypass iteration ceremony IF:

1. Human explicitly approves BEFORE work begins
2. No new content pages (specs, docs)
3. No spec changes
4. Configuration/tooling only
5. < 5 files modified

Tracking: Log to maintenance.log with format:

[DATE] APPROVED-TRIVIAL | description | human approval note

Status: FTL-014 accepted 2025-12-26. This section is ACTIVE.

14. Documentation Enforcement

14.1 Purpose

Documentation MUST remain synchronized with implementation. Stale or missing documentation creates:

• Agent misinformation (AI reads outdated docs)
• Adopter confusion
• Audit findings

14.2 Documentation Requirements by Phase

Phase	Documentation Requirement
planning	Define documentation scope in iteration goals
spec_lock	Identify which docs will be affected
implementation	Update docs as features are built
testing	Verify docs match implementation
archive	Confirm all doc updates committed

14.3 Mandatory Exit Criteria

Implementation phase MUST NOT complete unless:

• Public-facing changes have corresponding methodology.md updates
• FTL entry exists and reflects current status (Accepted → In Progress → Complete)
• CLAUDE.md (local) reflects new capabilities/commands
• Changelog updated if versioning.changelog_required: true

Testing phase MUST NOT complete unless:

• Documentation has been reviewed for accuracy
• Cross-references validated (links work, versions match)

14.4 Documentation Scope Matrix

Change Type	Required Documentation
New DIDP script	methodology.md, CLAUDE.md (local)
New command	Command .md file, methodology.md if public
Spec change	Spec file, changelog, potentially PSP proposal
Phase model change	phase-model.md, workflow-contract.md
New FTL entry	task-ledger.md

14.5 Enforcement

The agent MUST:

• Prompt for documentation updates before phase advancement
• Refuse to mark implementation complete if docs are stale
• Include documentation status in handoff notes

The agent SHOULD:

• Run doctor.ts to verify CLAUDE.md compliance
• Check that FTL status reflects work state

14.6 Verification

Documentation enforcement can be verified via:

• doctor.ts --docs (FTL-052 complete)
• Manual review during testing phase
• Cross-reference validation during archive phase

15. Agent Transparency

15.1 Purpose

The user MUST always know what the agent is doing. Automated actions, hooks, and background processes MUST be announced before and after execution.

15.2 Feedback Pattern

For ANY automated action, the agent MUST:

1. Announce intent before starting:

   • “Running knowledge base update…”
   • “Checking documentation compliance…”
   • “Idea triggered, please hold while I record this…”

2. Report outcome after completion:

   • “Knowledge base updated. 3 files changed.”
   • “Documentation verified. No issues found.”
   • “That’s a good idea, saved it for later as FTL-XXX.”

15.3 Applies To

This rule applies to ALL automated actions including:

• DIDP hooks (hash-site, index-specs, doctor)
• FTL idea capture
• Session startup checks
• Background agents/tasks
• File operations triggered by rules
• Any action not explicitly requested by user

15.4 Format

Feedback SHOULD be concise and use consistent patterns:

• Starting: “[Action], please hold…” or “Running [action]…”
• Complete: “[Result]. [Brief detail].” or “Done. [Summary].“

15.5 Rationale

• Builds trust through transparency
• Helps user understand system behavior
• Enables user to interrupt if needed
• Creates audit trail in conversation

16. Deferred Decision Capture

16.1 Purpose

Decisions discussed but not immediately acted on MUST be captured as FTL Ideas to prevent loss during context compaction.

16.2 Trigger

The agent MUST create an FTL Idea when:

• User says “we should do X later”
• Discussion produces actionable insight not in current scope
• User expresses interest in a direction but defers action
• A decision is made but implementation is out of scope

16.3 Capture Process

1. Announce: “Idea triggered, please hold while I record this…”
2. Create FTL entry with:
   • Status: Idea
   • Context: What was discussed
   • User quote (if relevant)
   • Recommended action
3. Confirm: “That’s a good idea, saved it for later as FTL-XXX: [title]“

16.4 Session Startup

At session start, the agent SHOULD:

1. Check for recent FTL Ideas from previous sessions
2. Surface relevant ones: “Last session you mentioned [X] (FTL-XXX) - want to pursue this?“

16.5 Staleness

FTL Ideas not addressed after 5+ sessions MAY be flagged for review or archival.