Behavior Mapping & Recording
Relevant source files
The following files were used as context for generating this wiki page:
Behavior Mapping is the process of defining authoritative proof obligations for production code changes. It establishes a contract between intended behavior and verified implementation through a non-empty JSON array of behavior items. Each item represents a concrete, falsifiable attack on a public promise through a real production Seam.
Recording provides continuity for these obligations across the software development lifecycle. The repo-production-workflow skill manages the lifecycle of these mappings, ensuring that every behavior slice progresses from pending to red and finally green status. This formal tracking prevents premature completion and ensures that all contract and preservation obligations are satisfied before workflow completion.
Sources: skills/production-preflight/SKILL.md:144-150, skills/tdd/SKILL.md:46-50, skills/repo-production-workflow/SKILL.md:25-30
The Behavior Map Structure
The Behavior Map is initialized during the production-preflight phase. It consists of a JSON array where each object defines a specific behavior obligation.
Behavior Item Schema
Every item in the map requires eight specific fields to ensure technical accuracy and traceability.
| Field | Description |
|---|---|
id | Stable uppercase identifier (e.g., BM_ATOMICITY) used by evidence markers. |
kind | Categorizes the item as either contract (requested behavior) or preservation (existing behavior). |
basis | Prose description of the requirement source. |
behavior | Concise description of the expected behavior under a specific precondition. |
seam | The public Interface or observable boundary where the behavior is driven. |
expected | The observable outcome of a successful behavior check. |
redFailure | The specific error marker or diagnostic that signifies a valid RED state. |
status | The current lifecycle state: pending, red, green, already-satisfied, omitted, or withdrawn. |
Sources: skills/production-preflight/SKILL.md:223-239, skills/tdd/SKILL.md:38-42
Mapped Categories
A comprehensive map must account for the following outcomes:
- All contract-declared success, error, refusal, and exception paths.
- Meaningful state transitions, including nesting and re-entry.
- Wrapped or rerouted Seam guarantees (success, failure, atomicity).
- Interactions where behavior in one area mutates state affecting another.
- Values produced by one system and decided by another (Differential testing).
Sources: skills/tdd/SKILL.md:58-69
Lifecycle and Recording Workflow
The workflow enforces a strict order for behavior recording. A behavior changing map must contain at least one contract item, which is processed before preservation items.
The diagram shows the iterative cycle of behavior mapping from initial preflight recording to final workflow completion.
Sources: skills/repo-production-workflow/SKILL.md:104-162, skills/tdd/SKILL.md:73-82
Status Transitions
Items move through statuses based on recorded evidence:
pending: Initial state for all new items.red: Set when a runner-backed or non-runner attack fails with the declaredredFailure.green: Set when the same test surface passes following a production edit.already-satisfied: Used for preservation items where existing evidence proves the behavior holds.superseded: Used when a map update replaces an item with a new terminal replacement.
Sources: skills/tdd/SKILL.md:73-82, skills/tdd/SKILL.md:120-125
Seams and Attack Vectors
Recording behavior requires a defined Seam. A Seam is the public Interface or externally observable product boundary where behavior is driven and observed without substituting interior paths.
Validating RED State
A RED recording is valid only if the failure matches the redFailure declared in the map. This ensures the failure is specifically due to the absent behavior rather than a syntax error, missing fixture, or environment issue. The first RED of a new Seam must assert the existence of the Seam itself (e.g., assert hasattr(db, "x")).
Attack Types
- Runner-backed: Uses frameworks like
pytestorunittest. The recorder establishes reach from the runner's report. - Non-runner: Uses CLI scripts or end-to-end operations. The recorder marks reach as unresolved, requiring human review to confirm the failure matches the promise.
Sources: skills/tdd/SKILL.md:17-25, skills/tdd/SKILL.md:43-46
Workflow Continuity and Ledger
Recording is managed by the workflow.py script, which maintains a repository-scoped SQLite event ledger. This ledger remembers accepted transitions and logical evidence across process restarts.
# Example: Recording initial preflight and behavior map
python3 "$HOME/.claude/skills/repo-production-workflow/scripts/workflow.py" \
record-preflight --repo "$PWD" --slug "<task>" \
--workflow-id "<active-workflowId>" --input <preflight.json>
# Example: Updating the map with implementation consequences
python3 "$HOME/.claude/skills/repo-production-workflow/scripts/workflow.py" \
tdd-map --repo "$PWD" --slug <task> --workflow-id <active-workflowId> --input - <<'JSON'
{"sourceBehaviorId": "BM_...", "reassessment": "...", "items": [...]}
JSON
Sources: skills/repo-production-workflow/SKILL.md:124-131, skills/tdd/SKILL.md:115-120
Final Review and Completion Gates
The complete command refuses to proceed unless the Behavior Map is fully resolved. This verification checks the following:
- Every
contractitem isgreen,baseline, orwithdrawn. - Every
preservationitem isgreen,already-satisfied, oromittedwith evidence. - No proof gaps remain in the map.
- The final
codex-advisorintake contains no pending material findings. - The working tree matches the manifest recorded during the lead review.
Sources: skills/repo-production-workflow/SKILL.md:204-215, skills/tdd/SKILL.md:139-145
Behavior Mapping and Recording provide a structured framework for technical accountability. By explicitly defining attack vectors and tracking their resolution in a persistent ledger, the system ensures that every production change is backed by falsifiable evidence of its behavioral impact.