Skip to content

intent-commit-flow.md

Latest commit

 

History

History
144 lines (113 loc) · 4.35 KB

intent-commit-flow.md

File metadata and controls

144 lines (113 loc) · 4.35 KB

Intent commit flow

Intent mode groups related captures before replay writes a commit. Capture durability stays the same: every edit is still stored first, then planning decides which pending seqs can publish together.

Use event mode when you want one capture per commit. Use intent when local history should read like review-ready changes.

Setup

Sparse repo:

export ACD_COMMIT_STRATEGY=intent
export ACD_AI_PROVIDER=openai-compat
export ACD_AI_API_KEY=...
export ACD_AI_DIFF_EGRESS=1
export ACD_INTENT_WINDOW=5
export ACD_INTENT_MIN_PENDING=3
export ACD_INTENT_MAX_PENDING_AGE=60s
export ACD_INTENT_DEFER_LIMIT=1

Busy repo:

export ACD_COMMIT_STRATEGY=intent
export ACD_AI_PROVIDER=openai-compat
export ACD_AI_API_KEY=...
export ACD_AI_DIFF_EGRESS=1
export ACD_INTENT_WINDOW=10
export ACD_INTENT_MIN_PENDING=8
export ACD_INTENT_MAX_PENDING_AGE=5m
export ACD_INTENT_DEFER_LIMIT=1
export ACD_INTENT_RETRY_ON_INVALID=1

Prompt-end flush from a registered harness session:

acd flush --repo . --session-id "$ACD_SESSION_ID" --logical

Logical flush bypasses only the batch wait. It does not bypass validation, terminal barriers, or replay safety checks.

Flow

flowchart TB
  A["Capture rows<br/>state=pending"] --> B{"Batch ready?"}
  B -->|no| C["Wait for count,<br/>age, or logical flush"]
  C --> B
  B -->|yes| D["Build planner window"]
  D --> E["AI planner"]
  E --> F{"Plan valid?"}
  F -->|no| G["Deterministic<br/>one-capture fallback"]
  F -->|yes| H{"Message OK?"}
  H -->|needs rewrite| I["Locked message rewrite"]
  I --> J{"Rewrite valid?"}
  J -->|no| G
  H -->|yes| K["Replay selected seqs"]
  J -->|yes| K
  G --> K
  K --> L[("decision ledger")]

  classDef queue fill:#243447,stroke:#7aa2f7,color:#e6edf3
  classDef decision fill:#3d2f1f,stroke:#f6c177,color:#fff4d6
  classDef provider fill:#203a31,stroke:#9ece6a,color:#eaffdf
  classDef fallback fill:#402b2b,stroke:#f7768e,color:#ffe8ee
  class A,L queue
  class B,F,H,J decision
  class E,I provider
  class G fallback
Loading

Planner input

Field Meaning
offered_captures Candidate seqs with path, op, timestamp, defer count, fidelity, and optional captured diff.
recent_commits Compact branch context.
path_commit_context Recent commits for paths touched by the offered captures.
forced_aging True when a repeatedly deferred capture is forced into a one-capture window.
path_recent_commits Optional hint that an offered path recently changed at HEAD. It is not an amend feature.

The planner must put every offered seq in either selected_seqs or deferred_seqs. It may select one seq or a larger related subset. Deferred seqs need reasons.

Message rules

Small single-file commits can use only a subject:

Refine prompt validation

Multi-file, larger, mixed code/test/docs/config, CLI, migration, recovery, template, workflow, installer, and public contract changes need body bullets:

Surface rewrite diagnostics

- Show recent rewrite counts in status output
- Preserve fallback reasons for diagnose and events inspection

Rejected examples:

Subject Why it is rejected
Update file Generic.
Update parsed Token-only.
Update effort.ts Filename-only.

When only the message is weak, ACD sends a locked rewrite request. The provider may change subject and body, but not selected seqs, deferred seqs, or grouping rationale.

Deferrals

Deferral is normal. It means the planner decided a capture did not belong in the current commit.

When a capture reaches ACD_INTENT_DEFER_LIMIT, ACD forces it through a one-capture planning window unless an earlier related-path capture must land first. If the provider fails there, deterministic fallback publishes the capture safely.

Observability

Question Command
What strategy and batch gate are active? acd status --json
Why is intent waiting? acd diagnose --json or acd doctor
Which seqs were grouped or deferred? acd events --json
What did the provider see? ACD_AI_PROMPT_TRACE=1 then acd prompt --seq <seq>
Where are rejected planner responses? <gitDir>/acd/planner-rejects.jsonl

intent_strategy reports window settings, batch wait state, deferred counts, forced-aging readiness, planner error rate, singleton commit rate, and message-quality rewrite or fallback counts.