AGENTS.md git:20261031.7538cd7A

Immutable. This exact content never changes and is served at /api/v1/blob/f29d68022457c140.

<!-- hyperfide-owned: generated-spec v1 -->
<!-- GENERATED by hyperfide spec render from spec/ kvx — DO NOT EDIT. -->

# Hyperfide Workflow

The single source of truth for how to work in this repo is **`spec/`** (kvx).
This file is a GENERATED pointer to it. Do not hand-edit it; edit `spec/workflow.kvx` and run `hyperfide spec render`.

> spec/ (kvx). Generated files are pointers — regenerate, never hand-edit.

## Principles

- **Task Driven**: Work is driven by the active feature's task list, in wave order, one claimed task per worker.
- **Verified Done**: A task is done only when hyperfide spec done reruns its verify_cmd and graph checks and they pass. A wave closes only after its regression checks and an independent correctness review; a component passing never certifies a full acceptance case.
- **Dependencies**: The hyperfide binary links sqlite, curl and crypto plus the C library and its pthread and math objects, and nothing else (the Makefile LDLIBS line is authoritative). The TypeScript services may use declared, pinned dependencies listed in their package.json. Anything else needs a permission Ask first.
- **Non Invasive**: Hyperfide observes and advises by default; it blocks only where the user asked it to.
- **Local First**: The local graph, memory and workflow work offline with no telemetry. Local caches state their freshness and never grant remote fleet ownership. Decision-model output narrows and ranks; verify_cmd and graph checks decide.
- **Distributed Authority**: Remote fleet ownership requires the authenticated coordinator and PostgreSQL; a disconnected client cannot obtain or renew it from cached state.
- **Anchor Intent**: Anchor what a reader could not derive from the code: purpose, contract, danger, pointer. Derivable comments are noise.

## The loop (every session)

1. hyperfide brief — load repo state, the active task and prior decisions.
2. hyperfide spec next — take the lowest-wave eligible task.
3. hyperfide spec start <id> — claim it in an isolated task worktree or sandbox.
4. hyperfide survey <area> for the wide picture, then hyperfide context <area> for the code you need.
5. Implement only the claimed task. Never default what you were not given: raise an Ask (MCP ask_raise, or hyperfide ask raise), keep working on what does not depend on it, and read the answer with ask_status. Raise a secret when a credential or token is missing (it is answered with a secret-ref, never a value); a variable when a configuration value, path or endpoint is unknown; a permission before anything destructive, outside the task's touches, or a new dependency; a decision when more than one design fits, naming the option you recommend; a question when the spec or a criterion is ambiguous, with your reading as the recommendation. secret, variable and permission block; decision and question proceed on the recommendation and are flagged ([asks]).
6. hyperfide review against the task's criteria; hyperfide guard for grounding, contract and hygiene; hyperfide anchors --stale for docs your edits outdated.
7. Update the task status in the feature spec.kvx, then commit explicit paths with a message tagged [spec:<feature>/<id>]. Publication beyond the task branch follows [publication].
8. hyperfide spec done <id> — qualification reruns verify_cmd; done means proven.

## Persistent project memory (when configured)

- **Recall**: hyperfide recall at session start; hyperfide brief includes it.
- **Remember**: hyperfide remember decisions and constraints as they occur, not afterwards.

## Active feature

`spec/hyperfide-source-control/spec.kvx` — read its `[meta]` status, `[req.*]` acceptance criteria, and the `[task.*]` list (status + wave + requires). Work one task at a time in wave order; update `status` in the kvx as you go.

## Hard rules

- **No Fakes**: Never fake or weaken a test to make it pass.
- **No False Done**: Never mark a task done that did not qualify.
- **No Silent Default**: Never default a secret, variable, permission or decision you were not given; raise an Ask.
- **Warn Dont Block**: New governance defaults to a warning. Blocking is opt-in, except the [asks] policy, where secret, variable and permission Asks block by design.