devflow-engine 1.0.0__py3-none-any.whl

devin/nodes/iterate/_archived_design_stages/iterator_agent_design/04-harness-and-playground.md

@@ -0,0 +1,12 @@
+# Iterator harness and playground
+
+The harness should be able to inspect:
+- readiness decisions
+- respawn decisions
+- terminal verdict selection
+- consistency between verdict, artifacts, and observed verification state
+
+Key fixtures:
+- near miss then repair success
+- missing truth blocks coding
+- unauthorized scope growth forces promotion

devin/nodes/iterate/_archived_design_stages/observer_agent_design/01-objectives-requirements.md

@@ -0,0 +1,20 @@
+# Observer, objectives and requirements
+
+## Objective
+
+Convert the framed task into observable truth that can safely govern coding and completion judgment.
+
+## Requirements
+
+- inspect logs, traces, state, or repro surfaces relevant to the framed task
+- confirm an error when evidence exists
+- report `not_confirmed` or `inconclusive` honestly when it does not
+- define a bounded failing seam for targeted improvements when direct repro is not the right frame
+- document the expected green condition
+- recommend whether the task is ready for Coder
+
+## Derived non-goals
+
+- do not implement fixes
+- do not invent evidence
+- do not claim completion

devin/nodes/iterate/_archived_design_stages/observer_agent_design/02-evals.md

@@ -0,0 +1,8 @@
+# Observer evals
+
+- confirms a reported failure when logs or repro evidence support it
+- reports `not_confirmed` honestly when the issue cannot be reproduced
+- creates a bounded red seam for a targeted improvement
+- provides repro steps another role can execute
+- records the expected green condition clearly
+- returns `needs_more_context` when truth is genuinely insufficient

devin/nodes/iterate/_archived_design_stages/observer_agent_design/03-tools-and-boundaries.md

@@ -0,0 +1,14 @@
+# Observer tools and boundaries
+
+## Needed capabilities
+
+- inspect logs and traces
+- run bounded repro checks
+- inspect relevant repo or runtime surfaces needed to define a failing seam
+- write the observation artifact
+
+## Boundary rules
+
+- should not silently patch code while observing
+- should not blur evidence with assumptions
+- should not escalate weak signals into false certainty

devin/nodes/iterate/_archived_design_stages/observer_agent_design/04-harness-and-playground.md

@@ -0,0 +1,13 @@
+# Observer harness and playground
+
+The harness should inspect:
+- evidence summaries
+- repro steps
+- repeatability status
+- green-condition definition
+- readiness verdict
+
+Key fixtures:
+- error confirmed by logs
+- user-reported error not confirmed
+- targeted improvement with a red seam

devin/nodes/iterate/agent-roles.md

@@ -0,0 +1,89 @@
+# Iterate agent roles and boundaries
+
+## System shape
+
+The iterate lane has four named agents, but not four equal peers.
+
+- `Iterator` is the accountable lane owner
+- `Framer` and `Observer` are specialist advisors
+- `Coder` is a supervised implementation worker
+
+That role split should stay visible in every stage of the design pipeline.
+
+## Iterator
+
+Primary owner of the task.
+
+Owns:
+- iterate-lane accountability
+- scope discipline
+- advisor coordination
+- readiness judgment before coding
+- spawning and supervising Coder
+- final validation and completion judgment
+- promotion or blockage decisions
+
+Must not:
+- act as the primary code writer
+- redefine Framer or Observer truth casually
+- claim success without verification evidence
+
+## Framer
+
+Turns raw user text and relevant history into a bounded task artifact.
+
+Owns:
+- task typing
+- locating the likely surface
+- separating facts from assumptions
+- writing explicit success criteria
+- identifying blocking versus nonblocking unknowns
+- recommending stay iterate, investigate first, or promote to idea
+
+Must not:
+- do observation work that belongs to Observer
+- implement code
+- broaden scope beyond the ask
+
+## Observer
+
+Converts the framed task into observable truth.
+
+Owns:
+- log inspection
+- minimal repro attempts for errors
+- bounded failing seams for improvements
+- repeatability judgment
+- explicit green-condition definition
+- recommendation on coding readiness
+
+Must not:
+- silently fix the issue
+- invent evidence
+- claim completion
+
+## Coder
+
+Supervised implementation worker.
+
+Owns:
+- implementing the scoped delta
+- using task and observation artifacts as the contract
+- running the narrowest valid verification seam
+- reporting what changed, what passed, what failed, and what remains blocked
+
+Must not:
+- rewrite the task contract
+- broaden scope because cleanup seems appealing
+- self-certify completion without Iterator validation
+
+## Ownership rule
+
+Iterator owns truth and completion judgment.
+Coder owns implementation attempts.
+Framer and Observer are specialized advisors whose artifacts constrain the coding loop.
+
+## Where the detailed design now lives
+
+- cross-agent stage docs: `pipeline/`
+- per-agent stage docs: `agents/`

devin/nodes/iterate/agents/README.md

@@ -0,0 +1,10 @@
+# Per-agent design docs
+
+Each agent has its own folder with the same ordered design stages:
+
+1. objectives and requirements
+2. evals
+3. tools and boundaries
+4. harness and playground
+
+This keeps review aligned with Marcus's pipeline while still making each role inspectable on its own.

devin/nodes/iterate/artifacts.md

@@ -0,0 +1,504 @@
+# Iterate artifact contracts
+
+## Why artifacts matter in this lane
+
+The iterate lane is not a loose conversation between four peers. It is an advisor-primary loop with one accountable owner.
+
+Artifacts are what keep that structure real:
+- `Framer` converts the ask into a bounded task contract
+- `Observer` converts the task into observable truth
+- `Coder` records supervised implementation attempts
+- `Iterator` decides readiness, respawns, blockage, promotion, and final disposition
+
+If those judgments are not expressed in shared artifacts, the lane will drift into hidden state and role collapse.
+
+## Pipeline position
+
+These artifact contracts support Marcus's pipeline order:
+1. objectives and requirements define what truth the lane needs
+2. evals define how weak or dishonest artifacts would fail
+3. tools and boundaries define who can create and modify which artifact
+4. harness and playground later test the artifact flow
+
+This file therefore describes the shared contract surface that the four-agent model depends on.
+
+## Canonical task primitive
+
+`IterateTask` is smaller than a story. It is a targeted change packet for work that still fits iterate.
+
+Suggested base shape:
+
+```yaml
+IterateTask:
+  task_id: string
+  project_id: string
+  source_message: string
+  turn_history: []
+  task_type: error_fix | quick_change | targeted_improvement
+  where:
+    surface: string | null
+    route_hint: string | null
+    component_hint: string | null
+    file_hint: string | null
+    function_hint: string | null
+  current_behavior: string
+  desired_behavior: string
+  success_criteria: string[]
+  constraints: string[]
+  assumptions: string[]
+  blocking_unknowns: string[]
+  nonblocking_unknowns: string[]
+  promotion_recommendation: stay_iterate | investigate_first | promote_to_idea
+  expected_user_outcome: string | null
+  what_happened: string | null
+  log_hint: string | null
+  repro_hint: string | null
+  task_details:
+    error_fix?:
+      suspected_failure_mode: string | null
+      user_reported_error_text: string | null
+    quick_change?:
+      requested_delta_summary: string
+      acceptance_examples: string[]
+    targeted_improvement?:
+      target_metric_or_quality: string | null
+      bounded_red_seam_hint: string | null
+```
+
+The payload above is the business body of the task. Durable artifact files should wrap that body in a small revision envelope rather than inventing a different schema per write.
+## Persisted location decision
+
+Iterate artifacts should live under a lane-owned root:
+
+```text
+.devflow/iterate/<task_id>/task_artifact.json
+.devflow/iterate/<task_id>/observation_artifact.json
+.devflow/iterate/<task_id>/iterator_run.json
+.devflow/iterate/<task_id>/promotion_handoff.json
+.devflow/iterate/<task_id>/attempts/<attempt_id>/verification_summary.json
+.devflow/iterate/<task_id>/attempts/<attempt_id>/verifier_output.json
+```
+
+Where `attempt_id` uses the exact format `attempt-<NNN...>`:
+- prefix is always the literal `attempt-`
+- suffix is a zero-padded decimal ordinal starting at `001`
+- the numeric portion is at least 3 digits and may widen past 3 digits only after `999`
+- ids are assigned monotonically within one `task_id` and are never reused
+
+Examples:
+- first attempt: `attempt-001`
+- second attempt: `attempt-002`
+- one thousandth attempt: `attempt-1000`
+
+This is now the preferred contract, not just a placeholder suggestion.
+
+Why this root is the right default:
+- it matches the existing repo convention of lane-specific durable artifacts under `.devflow/<lane>/...`
+- the iterate lane owns a task-scale execution record, not an arbitrary conversation transcript
+- `task_id` can carry or reference session lineage without making artifact lookup conversation-scoped
+- promotion out of iterate should preserve the iterate record as the historical source of the attempted task, rather than relocating it mid-run
+
+If cross-lane lineage matters, artifacts should point to upstream or downstream ids in metadata. The storage root should stay stable.
+
+## Shared artifact chain
+
+The four-agent lane should share this progression:
+1. `Framer` writes or amends `task_artifact`
+2. `Observer` writes `observation_artifact` against that task contract
+3. `Iterator` records a readiness decision in `iterator_run`
+4. `Coder` appends attempt records under `iterator_run`
+5. per-attempt verifier details are stored under `attempts/<attempt_id>/`
+6. `Iterator` records respawn reasons, blockage, promotion, or verified completion
+7. if the lane exits to `idea` or `insight`, `Iterator` also writes `promotion_handoff.json`
+
+This progression is the operating contract. It keeps advisors constraining the worker and keeps Iterator accountable for the final truth claim.
+
+## Shared revision policy
+
+Artifact revisioning should use explicit monotonic revision numbers, not content hashes and not opaque version strings.
+
+Recommended envelope for durable top-level iterate artifacts:
+
+```yaml
+artifact_envelope:
+  artifact_kind: task_artifact | observation_artifact | iterator_run | promotion_handoff
+  artifact_id: string
+  task_id: string
+  revision: integer
+  supersedes_revision: integer | null
+  updated_at: string
+  updated_by: Framer | Observer | Iterator | Coder
+  payload: {...}
+```
+
+Policy decisions:
+- `revision` starts at `1` and increments by `1` each time the same top-level artifact file is rewritten
+- `supersedes_revision` is `null` on first write and otherwise points to the immediately prior revision number
+- readers should treat `(artifact_kind, task_id, revision)` as the stable version identity for iterate artifacts
+- `task_artifact.json`, `observation_artifact.json`, `iterator_run.json`, and `promotion_handoff.json` are revised in place using this envelope
+- attempt-scoped files under `attempts/<attempt_id>/` are immutable per attempt by default and should not grow their own revision ladder unless a later design proves that necessary
+
+Why this is the right default:
+- monotonic integers are easy for agents, harnesses, and reviewers to compare
+- revision numbers make readiness and promotion decisions auditable without introducing content-addressing complexity
+- immutable attempt artifacts avoid accidental rewrites of verifier evidence
+- the policy matches the lane's need for clear supervision history more than sophisticated storage deduplication
+
+## Task artifact
+
+### Purpose
+The `task_artifact` defines the bounded ask before coding begins.
+
+It should let any reviewer answer:
+- what existing surface is being changed
+- what is happening now
+- what should happen instead
+- how success will be judged
+- what uncertainty still exists
+- whether the task still belongs in iterate
+
+### Required base fields
+Inside the `payload` body, the required task fields are:
+- `task_id`
+- `task_type`
+- `project_id`
+- `source_message`
+- `where`
+- `current_behavior`
+- `desired_behavior`
+- `success_criteria`
+- `constraints`
+- `assumptions`
+- `blocking_unknowns`
+- `nonblocking_unknowns`
+- `promotion_recommendation`
+- `task_details`
+
+At the envelope level, `task_artifact.json` also requires:
+- `artifact_kind=task_artifact`
+- `artifact_id`
+- `revision`
+- `supersedes_revision`
+- `updated_at`
+- `updated_by=Framer`
+
+### Schema strategy decision
+The task contract should use one shared base schema with a discriminated `task_type` plus a nested `task_details` section for type-specific requirements.
+
+Why this is the right shape:
+- all iterate tasks still need the same cross-agent spine for framing, observation, supervision, and completion
+- `Framer`, `Observer`, and `Iterator` need one stable place to read core fields regardless of subtype
+- the lane currently has a small, known subtype set, so a discriminator is simpler than maintaining separate top-level schemas
+- subtype-specific strictness can still grow without fragmenting the shared contract
+
+The design should therefore avoid separate `error_fix_task_artifact`, `quick_change_task_artifact`, and `targeted_improvement_task_artifact` roots unless the lane later proves the shared spine is breaking down.
+
+### Quality bar
+A valid `task_artifact` is:
+- specific enough that Coder does not need to reinterpret the request
+- narrow enough to stay task-scale
+- explicit about facts versus assumptions
+- honest about missing information
+- written so Observer can derive a real verification seam
+
+## Observation artifact
+
+### Purpose
+The `observation_artifact` turns the framed task into observable truth.
+
+It should let any reviewer answer:
+- what evidence exists
+- whether the failure or gap was confirmed
+- how repeatable the issue is
+- what exact condition must turn green for Iterator to approve completion
+
+### Required fields
+Inside the `payload` body, the required observation fields are:
+- `task_id`
+- `mode`
+- `evidence_summary`
+- `log_sources`
+- `log_evidence`
+- `repro_steps`
+- `repro_artifacts`
+- `red_test_paths`
+- `repeatability_status`
+- `current_failure`
+- `expected_green_condition`
+- `confidence`
+- `observer_verdict`
+
+At the envelope level, `observation_artifact.json` also requires:
+- `artifact_kind=observation_artifact`
+- `artifact_id`
+- `revision`
+- `supersedes_revision`
+- `updated_at`
+- `updated_by=Observer`
+
+### Quality bar
+A valid `observation_artifact` is:
+- evidence-based rather than interpretive only
+- explicit when repro is confirmed, not confirmed, or partially confirmed
+- concrete enough that Iterator can later compare final state against the same seam
+- honest when truth is insufficient for safe completion claims
+
+## Iterator run record
+
+### Purpose
+`iterator_run` preserves supervision truth across attempts.
+
+It should let any reviewer answer:
+- when Iterator judged the task ready
+- what each coder attempt changed
+- why respawns happened
+- whether the terminal outcome was completion, blocked, or promoted
+
+### Required fields
+Inside the `payload` body, `iterator_run` requires:
+- `task_id`
+- `run_state`
+- `readiness`
+- `attempts`
+- `latest_attempt`
+- `respawn_count`
+- `promotion`
+- `final_verdict`
+
+At the envelope level, `iterator_run.json` also requires:
+- `artifact_kind=iterator_run`
+- `artifact_id`
+- `revision`
+- `supersedes_revision`
+- `updated_at`
+- `updated_by`, usually `Iterator` and sometimes `Coder` for attempt append operations under Iterator supervision
+
+### Readiness state decision
+Iterator readiness should be a first-class top-level structure, not just an event hidden inside attempt history.
+
+Recommended shape:
+
+```yaml
+iterator_run:
+  task_id: string
+  run_state: framing | observing | blocked_pre_coding | ready_for_coder | coding_in_progress | awaiting_iterator_review | needs_respawn | completed | blocked | promoted
+  readiness:
+    status: not_ready | ready_for_coder | blocked | promoted
+    decided_at: string
+    decided_by: Iterator
+    based_on:
+      task_artifact_revision: integer
+      observation_artifact_revision: integer
+    reason: string
+  attempts: []
+  latest_attempt: string | null
+  respawn_count: integer
+  promotion:
+    status: none | to_idea | to_insight
+    decided_at: string | null
+    decided_by: Iterator | null
+    reason: string | null
+    based_on:
+      task_artifact_revision: integer
+      observation_artifact_revision: integer | null
+      iterator_run_revision: integer
+    handoff_ref: string | null
+    downstream:
+      lane: idea | insight | null
+      downstream_id: string | null
+      downstream_artifact_ref: string | null
+  final_verdict: null | completed | blocked | promoted
+```
+
+Why this should be explicit:
+- readiness is an Iterator-owned gate, not merely another attempt note
+- the harness needs to inspect whether coding started too early
+- blocked or promoted outcomes can happen before any coder attempt exists
+- top-level state makes pre-coding and post-attempt transitions auditable
+
+Attempt history should still record when readiness changed, but the canonical current state belongs at top level.
+
+### Promotion linkage decision
+When iterate exits to `idea` or `insight`, the durable linkage contract should be split into two parts:
+1. `iterator_run.payload.promotion`, which records the lane decision inline in the supervisory spine
+2. `promotion_handoff.json`, which stores the actual handoff payload that the downstream lane can consume
+
+Recommended `promotion_handoff` payload shape:
+
+```yaml
+promotion_handoff:
+  task_id: string
+  target_lane: idea | insight
+  decided_at: string
+  decided_by: Iterator
+  reason: string
+  handoff_summary: string
+  based_on:
+    task_artifact_revision: integer
+    observation_artifact_revision: integer | null
+    iterator_run_revision: integer
+  source_refs:
+    task_artifact_ref: string
+    observation_artifact_ref: string | null
+    iterator_run_ref: string
+  downstream:
+    downstream_id: string | null
+    downstream_artifact_ref: string | null
+```
+
+At the envelope level, `promotion_handoff.json` should also use:
+- `artifact_kind=promotion_handoff`
+- `artifact_id`
+- `revision`, normally `1` unless the handoff record itself is amended
+- `supersedes_revision`
+- `updated_at`
+- `updated_by=Iterator`
+
+Mandatory linkage fields for every promotion or reroute:
+- in `iterator_run.payload.promotion`: `status`, `reason`, `based_on`, `handoff_ref`, and `downstream.lane`
+- in `promotion_handoff.json`: `target_lane`, `handoff_summary`, `based_on`, and `source_refs`
+
+Decision on downstream refs:
+- `handoff_ref` to the iterate-owned `promotion_handoff.json` is mandatory
+- direct downstream refs such as `downstream_id` or `downstream_artifact_ref` are optional at promotion time and may remain `null` if the downstream lane has not yet allocated durable state
+- if the downstream lane does allocate an artifact or session synchronously, that ref should be filled in, but iterate should not block truthful promotion on that allocation
+
+Why this is the right default:
+- iterate can close truthfully without depending on downstream side effects
+- the handoff remains durable and inspectable even if downstream work starts later
+- the linkage gives `idea` and `insight` enough upstream provenance without forcing a cross-lane transaction
+
+### Attempt record expectations
+Each attempt entry should summarize supervised coding work without swallowing raw verifier detail.
+
+`attempt_id` should be a human-readable, sortable sequence id, not a timestamp and not an opaque UUID.
+
+Exact policy:
+- format is `attempt-<NNN...>`
+- numbering starts at `attempt-001`
+- numbering advances by `1` for each new coder spawn under the same `task_id`
+- ids remain stable even if a later attempt is blocked, superseded, or leads to promotion
+- `latest_attempt` in `iterator_run` should point to the highest assigned ordinal, not the most recently successful attempt
+
+Why this is the right default:
+- iterate runs are linear supervisory loops, so ordinal identity matches the mental model better than random ids
+- lexical sort and chronological sort stay aligned
+- reviewers can discuss respawns unambiguously as "attempt-002 failed verification" without decoding timestamps
+- harness fixtures can assert attempt order deterministically
+
+Suggested attempt shape:
+
+```yaml
+attempt:
+  attempt_id: attempt-001
+  spawned_at: string
+  coder_summary: string
+  changed_surfaces: string[]
+  verification_summary_ref: string
+  verifier_output_ref: string | null
+  iterator_review:
+    disposition: success | respawn | blocked
+    reason: string
+```
+
+### Verifier output placement decision
+`iterator_run.json` should contain durable summaries and file references, while verbose verifier evidence should live in attempt-scoped files.
+
+Normalization decision:
+- all verifier types must emit the same top-level JSON envelope in both `verification_summary.json` and `verifier_output.json`
+- verifier-specific structure is allowed only inside a dedicated nested payload field
+- consumers should be able to inspect verdict, seam alignment, and artifact refs without knowing which verifier produced the record
+
+Why this split is the right default:
+- `iterator_run` is the audit spine and should stay readable across multiple retries
+- raw verifier evidence can be large and verifier-specific
+- a shared envelope gives Iterator, harnesses, and downstream reviewers one stable parsing contract
+- nested verifier-specific payloads preserve useful detail without forcing false uniformity across test runners, screenshots, logs, or manual checks
+
+The run record should therefore keep:
+- concise attempt-level verification summaries
+- stable refs to attempt-scoped verifier files
+- Iterator's disposition against that evidence
+
+It should not try to inline full test logs, stack traces, or tool-native output blobs by default.
+
+Recommended normalized `verification_summary.json` shape:
+
+```yaml
+verification_summary:
+  artifact_kind: verification_summary
+  task_id: string
+  attempt_id: attempt-001
+  verifier_kind: test_run | browser_check | screenshot_diff | log_check | manual_probe | mixed
+  generated_at: string
+  produced_by: Coder
+  overall_result: pass | fail | inconclusive | not_run
+  green_condition_alignment:
+    status: satisfied | not_satisfied | unknown
+    against: string
+    notes: string
+  checks:
+    - check_id: string
+      label: string
+      result: pass | fail | inconclusive | not_run
+      summary: string
+      artifact_refs: string[]
+  summary: string
+  blocker_notes: string[]
+  output_ref: string | null
+```
+
+Recommended normalized `verifier_output.json` shape:
+
+```yaml
+verifier_output:
+  artifact_kind: verifier_output
+  task_id: string
+  attempt_id: attempt-001
+  verifier_kind: test_run | browser_check | screenshot_diff | log_check | manual_probe | mixed
+  generated_at: string
+  produced_by: Coder
+  overall_result: pass | fail | inconclusive | not_run
+  green_condition_alignment:
+    status: satisfied | not_satisfied | unknown
+    against: string
+    notes: string
+  evidence_refs: string[]
+  native_payload:
+    # verifier-specific structure lives only here
+```
+
+Normalization rules that should stay stable:
+- `overall_result` uses the shared enum above for every verifier type
+- `green_condition_alignment` is mandatory even when the verifier cannot decide, in which case `status=unknown`
+- `checks` belongs in `verification_summary.json` because Iterator often needs a readable rollup rather than only a raw blob
+- `native_payload` in `verifier_output.json` may contain tool-specific objects, arrays, text blocks, or structured traces
+- additional attempt-scoped files such as screenshots, traces, or junit XML may exist, but they should be referenced from the normalized JSON rather than replacing it
+
+### Quality bar
+A valid `iterator_run`:
+- captures attempt history rather than only the final state
+- records Iterator-owned judgments distinctly from Coder-authored notes
+- explains terminal disposition in a way that can be audited later
+- keeps the canonical state readable even when several attempts accumulate
+
+## Agent-to-artifact mapping
+
+- `Framer` authors and amends `task_artifact`
+- `Observer` authors `observation_artifact`
+- `Coder` contributes attempt records and verification summaries under `iterator_run`, with raw verifier detail stored in attempt-scoped files
+- `Iterator` owns `run_state`, `readiness`, respawn reasons, promotion linkage, and the final disposition in `iterator_run`
+- `Iterator` authors `promotion_handoff.json` whenever work exits iterate for `idea` or `insight`
+
+This mapping should remain stable even if runtime execution details change.
+
+## Remaining open seams
+
+At this stage, the two previously open seams are now closed for the pre-prompt design pass:
+- `attempt_id` format is fixed to monotonic ordinal ids of the form `attempt-001`
+- attempt-scoped verifier artifacts use a shared top-level JSON envelope, with verifier-specific structure nested under `native_payload`
+
+Still intentionally open for a later design pass:
+1. whether `checks[].check_id` should follow a repo-wide naming convention shared with other lanes
+2. whether `verifier_kind=mixed` should stay a single artifact or fan out into multiple verifier records when one attempt runs several distinct verification modes
+3. whether any attempt-scoped artifacts beyond the normalized JSON pair should become mandatory for certain verifier kinds, such as screenshots for UI checks or junit XML for test suites