#Concepts

Work flows through four entities, each backed by a validated state machine:

Requirement -> Suggestion -> Story (+ acceptance criteria) -> Workstream -> micro-commits -> merged commit

• A suggestion is a candidate piece of work that discovery proposes from your requirements (REQS.md).
• Claiming a suggestion creates a story: a feature or bug with a problem statement and acceptance criteria, the source of truth for what the change should do.
• Running an accepted story creates a workstream: one git branch in one isolated worktree, holding a plan of micro-commits, the smallest planned units of work.

State only changes through a validated transition that is saved atomically and recorded as an event, so every interface always knows what stage a piece of work is in and what can happen next.

#The governed loop

Inside a workstream, every micro-commit runs the same loop, and every arrow is a gate:

implement -> test -> review -> human gate -> commit

• Test. Your configured tests must pass, or the loop goes back to implement with the failures.
• Review. An AI reviewer returns a structured verdict: decision, confidence, blockers, required changes and concerns.
• Human gate. Whether a clean commit stops for a person depends on the project's autonomy mode.

The loop is bounded. Each micro-commit gets up to five implement, test and review attempts before it escalates to a person. A test that was green and turns red goes to a read-only judge that rules whether the change or the test is wrong; if the same failures keep repeating, hashd escalates to a partial re-plan and then to a person instead of looping.

When an agent needs information to continue, it raises a clarification and the workstream waits for an answer (hashd answer).

#Final review and the merge gate

When every micro-commit is done, two branch-level gates run:

• Final review reads the whole branch diff. It marks the branch ready_to_merge, flags final_review_with_concerns for a person to decide, or, when you reject, adds a FIX micro-commit that runs through the same loop.
• The merge gate runs your merge-time tests, checks for conflicts against a fresh main and runs a gitleaks secrets scan. A secret finding blocks the merge.

Merge directly, or through a pull request on GitHub, GitLab, Bitbucket or Gitea. After the merge, hashd updates SPEC.md, retires the implemented requirements and removes the worktree.

#Autonomy modes

Every mode stops for a person when something fails. Override the mode for a single run with hashd run --supervised, --gatekeeper or --autonomous.

#Parallel work

Many workstreams can run at once, each in its own worktree. A second run of the same workstream is refused while the first is open, and hashd conflicts reports file overlap between workstreams.

#The event log

Every state change is written twice: pushed live to every connected interface, and stored in a durable events table. The durable log is the spine of the audit trail, and it is what makes provenance complete by construction. Long-running work runs as durable workflows that survive Ctrl-C and restarts.