git:20261102.ffb1c8d to git:20261102.ee61610

---

name: items

description: >

The credo work-item model, where the FOLDER an item file lives in is the single source

of truth for its status, gated by a hard Definition of Done. Use whenever you create,

update, or track a work item; whenever you decide whether something is "done" and may

move to 2_done/; whenever you move an item between status folders (clarify, go, done,

archived, parked); whenever new code might be unwired; or when someone asks where a task

stands. This is the credo task system: .credo/items/ replaces ad-hoc task lists. Applies

inside subagents too - if you build or complete work, record and gate it as an item.

---

# items - the credo work-item model

A work item is a single Markdown file under `.credo/items/`. The **folder the file lives

in is the only source of truth for its status**. There is no status field, no marker, no

task-tracker entry - an item changes status by physically moving between folders. This is

deliberate anti-drift: multiple status sources drift out of sync, one physical location

cannot. `.credo/items/` IS the task system; do not mirror items into a separate task list.

"Do not mirror" does NOT mean "never use the harness task list at all" - it means no FULL

items live there; references to items are fine (see "Harness task-list vs .credo items"

below).

> **Task backend.** If the task backend is `gsd` (set in `.credo/config` as `task_backend`, or via the `CREDO_TASK_BACKEND` env override; resolve with `credo-config.sh backend`), the credo item system is inactive - GSD's

> phases are the task system for this project. Do NOT create or move `.credo/items/`; use

> GSD's workflow instead. This skill applies only when the backend is `credo` (the default)

> or `none`.

## Status = folder (the only truth)

The folder tree (created by `credo-init`) and what each folder means:

```

.credo/items/

1_todo/

1_clarify/ open questions - NOT buildable yet (human-owned: needs the user; agent-owned: decision rule below)

2_go/ clarified and approved - buildable (go-gate: only 2_go is buildable)

3_blocked/ GO'd but hard-blocked by another (unbuilt) credo item; auto-returns to its origin (unblock_to: go|clarify) when every blocker is delivered

2_done/ Definition of Done met (agent and/or user), gate passed

3_verified/ human-authorized - human-in-the-loop confirmation (main agent moves here only on explicit user instruction)

4_archived/ abandoned / deprecated / rejected

parked/

hold/ blocked by an EXTERNAL dependency (not another credo item)

future/ deliberately deferred

```

Never encode status anywhere else. If you want to know an item's status, look at which

folder its file is in - nothing else is authoritative.

## Harness task-list vs .credo items

The Claude Code harness has its own task list (the `TaskCreate` / `TaskList` tools). It is

NOT a second status source and NOT a mirror of `.credo/items/`. This section is the single

source for how the two relate; the credo `orchestration` and `session-init` docs only point

here.

1. **The GO folder is always the primary work set.** A task / build agent's PRIMARY work set

is ALWAYS the GO folder (`.credo/items/1_todo/2_go`). An EMPTY harness task list does NOT

mean "nothing to do" - the agent must always fall back to the GO folder. An empty harness

list is never a stop condition; the GO folder is the authority for what to build.

2. **The harness task list is the ephemeral coordination layer.** It is a temporary,

compact-surviving scratchpad: reminders, ordering constraints between item

implementations, HOLD conditions, and small things not worth their own `.credo` item. It

is NOT a mirror of `.credo` items and must NOT contain full items - only references.

3. **References are welcome; the substance stays in `.credo`.** An item's substance lives in

its `.credo` file, never in the task list; the harness list carries only references to it.

4. **Completed entries PERSIST - never clear them.** The user reviews the list after an

autonomous run to see completed vs pending as a next-day reference, so completed entries

must stay. "Tidying" the list means keeping it current and correct, NOT deleting completed

entries. This pairs with the end-of-run come-see-results moment and the fresh-listing

pending backstop in the credo `session-autonomous` skill (end-of-run), where the user

reviews completed vs pending after an unattended run.

Tag convention: each line is one of `[GO]` / `[HOLD]` / `[REMINDER]` / `[DONE]`, then a

backticked item `#ref`, then a short topic. The `#ref` is written in backticks, matching the

inline-code item-reference convention used throughout the credo skills. Example lines:

```

1. [GO] `#xyz` - topic (an ordering constraint)

[HOLD] `#xyz` do not build until the user explicitly orders it

[REMINDER] `#1234` X still needed there, but only later after Y is done

```

**Numbering: `#N` only for real items.** `#N` is reserved for real items (credo items, issues,

PRs, tickets). A harness task entry is never referred to as `#N`, because the harness ids

overlap with item numbers: in replies and task subjects write it as `§cct_N` (cct = Claude Code task, e.g. "task `§cct_2`

is still open", never "task #2"). The same goes for any other numbering that is not a real

item. The user writes it the same way ("§cct_2 dd" = harness task 2 done).

> **Terminology.** "task list" / "task liste" means primarily the harness `TaskCreate` /

> `TaskList` entries; only if none exist may the agent interpret what was otherwise meant.

**When the task-list tools are missing.** Newer Claude Code versions offer `TaskCreate` /

`TaskGet` / `TaskUpdate` / `TaskList` on newer models only when the env var

`CLAUDE_CODE_ENABLE_TODO_TOOLS=1` is set (profile `settings.json` `env` object or the process

environment), and subagents only get them when the parent session has them. If you need the

list and the tools are not available to you:

1. Say so ONCE in the session (one short line, not on every turn), naming the opt-in: run

`/credo:setup` (Step 10) or answer yes to the `[credo-todo-tools]` session-start offer,

which sets the variable with a backup of `settings.json`. A subagent reports it back to

the main agent instead.

2. Do NOT silently emulate the list in prose (no hand-numbered `§cct_N` lists in replies

pretending to be the harness list). The GO folder stays the primary work set, so work

continues; coordination notes that must survive go into the relevant `.credo` item body

or the handoff instead.

3. Never set the variable yourself without the user's yes, and never ask about it in

autonomous mode (there, note it once in the end-of-run report). This also applies to

the `[credo-todo-tools]` session-start offer: at a fresh start the session mode is

often not set yet when the hook runs, so the offer itself opens with that rule - check

the mode before asking.

4. After a yes, the tools may only appear after a restart of Claude Code

(`credo-todo-tools.sh status` shows `restart_needed=yes` while the variable is in

settings.json but not yet in the session).

## go=go - the folder is authoritative for building

An item in `2_go` IS buildable, by definition of the folder. This is the build-side

counterpart to the entry gate that governs what may enter `2_go` in the first place (the

credo `migrate` skill owns the G1-G6 entry gate).

- **The folder overrides body-level doubt.** An unproven root-cause hypothesis, a

"GO unclear" note, or any hedge in the body does NOT override the folder. If the file is

in `2_go`, build it (best effort).

- **A stale-looking body is NEVER grounds to self-skip or self-demote.** A head or a note

that still reads "open / not built / needs clarification" is by itself never a reason to

skip a `2_go` item or to treat it as not-yet-buildable - such prose goes stale (the item

was already built or clarified but the text was not reconciled; see the Full-body

reconciliation sweep and the Body-freshness invariant below). Before you treat a `2_go`

item as still-open or non-buildable on the strength of its prose, you MUST first read the

WHOLE body AND check the requirements log (`.credo/process/requirements/*.md`) and any

existing audit reports (`.credo/process/reports/`) - the clarification or the build is

often already there, just not written back into the head. This is distinct from the

Named-Decision-Test below: stale prose is NOT a Named-Decision. Only a genuine, still-open

user-only decision that passes that test sends an item back; a merely stale-looking body

is reconciled (Full-body reconciliation sweep) and built.

- **Never self-skip, never self-demote.** The building agent does NOT skip a `2_go` item and

does NOT move it down for reasons of size, UI, or "not sure it is verifiable". It MAY

re-scope or phase a large item into slices, but it must build. The ONE carve-out is a

genuine user-only decision that passes the Named-Decision-Test (below) - that is not a

size/difficulty demotion and is the only sanctioned `2_go -> 1_clarify` path.

- **Verify the real scope before calling a point LARGE.** Before you classify a point as

large or move it into a follow-up item for size reasons, FIRST briefly verify feasibility

and the real scope - sketch how it would actually be done - instead of guessing. Size must

be checked, not assumed: a size claim used to defer must be backed by a quick actual look

at the implementation, not an estimate. This does not forbid genuine follow-up items when

they are warranted; it only bars deferring on an assumed size ("too big / too hard" is

still not grounds - see the Named-Decision-Test). This build-time scope check has a PRE-GO

cousin: obligations (b) brief pre-measure and (c) brief pre-investigate of the over-clarify

standard sketch scope and sanity-check measurements DURING clarify, before GO (credo

`session-active` skill, CLARIFY-FIRST).

- **`ui: true` is not a reason not to build.** UI items are verified via the credo `verify`

skill, which is autonomous-capable; a required visual verify does not make an item

unbuildable.

- **Uncertainties are NOTED, not a veto.** Record an uncertainty in the item History or a

note; it is never a reason to leave a `2_go` item unbuilt.

- **Hypothesis vs open decision (the fine line).** An unproven *hypothesis* WITH a clear fix

approach (for example a root-cause hypothesis pinned to `file:line`) is buildable - build

it. An open *design decision / build-detail* is NOT a build-side call: per the entry gate

(G5) such an item should never have entered `2_go`. If one is found in `2_go` anyway, the

agent does NOT invent the decision and does NOT silently build on a made-up one - it

applies the Named-Decision-Test below (a deferred question in autonomous mode, an Ask in a

presence session, and a move back to `1_clarify` when the test passes).

## Named-Decision-Test - the only ground for sending a 2_go item back

GO=GO is the norm: an item in `2_go` is clarified and gets built. Sending one back to

`1_clarify` is a RARE exception, and only this test authorizes it - never "too big / too

hard / not sure it is verifiable / UI". A `2_go` item may return to `1_clarify` ONLY when

ALL three hold:

1. **A genuine user-only decision exists** - the requirement does not determine the

outcome, and choosing needs product / taste / scope / UX judgement that is the user's to

make, not a technical detail the agent can settle with a defensible engineering default.

2. **It is phrasable as an explicit either/or question** - "decide A vs B, because the

requirement is silent on X". If you cannot write it as a concrete choice, you do not have

a decision, you have an excuse: build it (go=go).

3. **It blocks correct completion** - the item's core cannot be finished without that

decision (not a cosmetic detail with an obvious default).

Explicitly NOT grounds (these stay in `2_go` and get built): "too big / too hard /

uncertain whether verifiable", UI, an unproven root-cause *hypothesis that has a clear fix

approach*, or anything resolvable by a defensible engineering default. The test must be

well-founded and must NOT be used as an argument against building the item itself.

Every item in `2_go` is agent-owned (`clarify_owner: agent`, set by the move helper on

entry), so a question surfacing mid-build first goes through the agent decision rule

("Clarify owner and the agent decision rule" below): the agent decides it itself per the active

mainagent-prompt (`credo-preset.sh mainagent`) and builds on. Only a question on the fixed escalation list ("Clarify owner and

the agent decision rule" below: user taste or preference, a change to the verbatim

requirement, the hard safety rules, deletions of user data, installs beyond the item's approvals (`## Freigaben`), money beyond an approved budget) can pass

condition 1 here. An item sent back by this test gets

`clarify_owner: human` again, because its open question is the user's by definition:

`credo-item-move.sh <id> clarify` sets it and logs `clarify_owner <old> -> human` in the

History. A GO line from before the send-back no longer counts; the item needs a new GO.

Typically this surfaces DURING the build, not at read time: an item is normally fully

clarified when it reaches `2_go`, but something critical can still come up mid-build where

building on naively would be wrong instead of clarifying. When the test passes, the agent

MAY move the item back (the one carve-out from "never self-demote" above). Because such an

item was interrupted for a critical reason and likely leaves something broken, it is

URGENT - see below.

## URGENT clarify (surfaced first)

An item sent back to `1_clarify` via the Named-Decision-Test - especially one interrupted

mid-build - is top priority: it probably leaves something broken and must be resolved

before things run clean again. Mark it in the item body with a short

`> URGENT: <what is broken / which decision blocks it>` note at the top of the History

section, rather than adding a priority field or a new folder - "folder = status" and the

lean frontmatter stay intact. The rule that rides on the marker: when the user is available,

an agent surfaces these URGENT clarify items FIRST, before any other clarify or build work.

## GO stall classification (no "waits on the owner" for a 2_go item)

A `2_go` item never stays in `2_go` as "waits on the owner" (or "waits on T38", "waits on

approval"). A GO item without progress - listed by `scripts/credo-go-stall.sh`, or any GO

item you are about to report as waiting - is classified as exactly one of:

- **buildable** - build it, including the buildable slice of a partly blocked item (split the

rest into its own item if needed). Re-read the whole DoD before you decide it is not.

- **Named-Decision** - a genuine user-only decision (Named-Decision-Test above): move the item

to `1_clarify` with an URGENT note (`credo-item-move.sh <id> clarify`). An install beyond

the item's `## Freigaben` is such a decision only when the grant check of credo `rules` and

`safety` finds no grant or an unclear check.

- **human-only verify** - everything the agent can build and check is `exercised`; only a

human check remains: move it to `2_done` with `human-only: pending` in `## Verify` (see

"Human-only checks do not block done"). `3_verified` stays the user's step.

- **blocked** - hard-blocked by another unfinished item: `3_blocked` with `blocked_by`

(block-guard above).

An idle heartbeat and any "nothing to do" report come only after this classification and

name the class of every GO item that is not built. "All GO items wait on the owner" is not a

valid report.

## Clarify owner and the agent decision rule

How an agent decides an open question is set by the active model preset: the

`mainagent-prompt` (and the `universal-prompt`) that `scripts/credo-preset.sh mainagent`

prints, delivered at every SessionStart. This section fixes only who decides, the GO line

requirement and the safety calls below; the decision philosophy itself lives in the preset

config, not here. Follow the active mainagent-prompt for every agent-owned decision.

**Who decides, by owner and by mode.** Three parts:

1. **Owner-owned clarify items** (`clarify_owner: human`, or the field missing) are clarified

with the owner in EVERY mode. The agent never decides them. In an autonomous run they are not

clarified at all: they stay in `1_clarify` and go into the end-of-run report.

2. **Agent-owned clarify items** (`clarify_owner: agent`) are decided by the agent ONLY in an

autonomous run. In an interactive mode (active, passive) every clarify decision goes to the

human, agent-owned items included: the agent recommends (Recommended option first) and the user

decides.

3. **Build-time details of a GO item** (questions that come up while building it) are the agent's

to decide in every mode, per the active mainagent-prompt, logged in the item History. They are

not clarify decisions, and the escalation list below still goes to the user.

A repo rule in `.credo/RULES.md` (credo `rules`) can extend this; it cannot lower the safety floor.

Where another credo text states otherwise, this section wins.

**Who decides depends on the owner** (frontmatter `clarify_owner`, missing = `human`):

- **Human-owned clarify items** (`clarify_owner: human` or missing) are ALWAYS clarified

with the user, never decided autonomously. In a clarify round the agent recommends per

the rule below (the recommended option first) and the user decides. Only the user gives

the GO: `credo-item-move.sh` refuses `-> go` for a human-owned item unless the History

carries a `(GO: <user quote>)` line or the main agent passes `--user-authorized` on the

user's explicit GO. A detour via `parked/*` or `3_blocked` does not get around it.

- **Agent-owned items** (`clarify_owner: agent`, plus everything in `2_go`): in an autonomous

run, uncritical questions are decided by the plan agent. If no plan agent peer is known (none

was announced as owning this responsibility), the EXECUTING agent takes this pseudo plan role

for the moment, without changing its real role, and decides per the active mainagent-prompt.

In an interactive mode these questions go to the user (see "By mode"). The fixed escalation list is never a preset decision: user taste or

preference, a change to the verbatim requirement, the hard safety rules, deleting user

data, installs beyond the item's `## Freigaben` and money beyond an approved budget go to the user. Feasible = GO (autonomous runs only): an agent-owned clarify item may

move to `2_go` with the History line `-> go <date> (GO: agent decision, <reason>)`. The

older marker `(GO: agent per SOTA rule, <reason>)` stays valid (the move helper accepts both).

**No slicing around the user:** an item with `parent: <id>` may only be agent-GO'd while

its parent is GO'd (in `2_go`, `2_done`, `3_verified`, or `3_blocked` with a GO). Children

of a human-owned parent that is still in `1_clarify` (or parked, archived, missing) are

human-owned until the user decides the parent; the move helper refuses the agent GO.

**Provable owner:** `clarify_owner: agent` counts only when the move helper wrote the flip

(`clarify_owner human -> agent` in the History) or the item was created as an agent item

(`parent:` or a `created by agent` History line). A hand-edited `clarify_owner: agent` on a

user item is treated as human.

Log EVERY such decision in the item History (what was decided, why). A decision the owner

notices in the product is also named in the next reply or report with a veto code (credo

`verify`, "Typed codes"), so the user can veto it; an internal process decision stays in

the History.

**Still escalated to the user, also on agent-owned items:**

- anything infeasible or really not good (step 3 above);

- the user's taste or preference (look, wording, product direction);

- deleting user data, installs beyond the item's `## Freigaben`, money beyond an approved budget, and the hard safety rules (credo `safety`);

- **verbatim guard:** a question whose answer would change or narrow the user's verbatim

requirement (the `Requirement (verbatim)` section of the item or of its `parent`) always

goes to the user (credo `requirements-verbatim`).

**By mode:** interactive (active, passive) - every clarify decision goes to the user via the Ask

tool, agent-owned items included (one item per round, Recommended option first; the agent's

recommendation follows the active mainagent-prompt). Autonomous - decide the uncritical questions

of agent-owned items (GO with the agent-decision marker), park the owner-owned clarify items and

the escalated questions for the end-of-run report (deferred-question flow, credo

`session-autonomous`); never adopt a default for an escalated question. In every mode, build-time

details of a GO item are the agent's to decide and log.

A user GO in the user's own words is always a valid GO for any item; this rule only adds

that, in an autonomous run, agent-owned items do not wait for one.

## Mandatory frontmatter (lean)

Exactly five required fields. Keep it minimal:

```yaml

---

id: 124 # integer from credo-id-next.sh (monotone counter, folder is a safety floor)

title: Short imperative title

created: 2026-07-04 # YYYY-MM-DD, the day the item was created (in 1_clarify)

type: feature # one of: bug | optimization | feature | question | chore

ui: false # bool - true means a visual verify is a DoD requirement

---

```

- `type`: `bug` | `optimization` | `feature` | `question` | `chore`.

- `ui`: boolean. When `true`, a passing **visual** verification (the credo `verify` skill,

measured layout + real interaction at every configured viewport) is a mandatory part of

this item's Definition of Done.

- `audit` (optional, normally absent): the single value `audit: full` forces the full audit

tier for this item (credo `audit` skill, "Audit depth (risk tiers)"). Absent = the main

agent picks the tier by risk. There is no `audit: lean` override - an item can only be

pushed up to `full`, never down.

Everything else (`priority`, `source`, `relates_to`, `regression`, ...) is

**not** a mandatory field. Do not add speculative frontmatter. Write such information only

when it actually applies, free-form in the body.

The one exception is the blocker relation `blocked_by: [ids]` / `blocks: [ids]`: these are

structured (not free-form) and are REQUIRED while an item sits in `1_todo/3_blocked` (see

"GO-but-blocked" below). Outside that state they are omitted. They form a relational

dependency graph, NOT a second status source, so principle "folder = status" stays intact

and the lean-frontmatter philosophy is not broken.

The other documented optional field is `clarify_depth`. It is normally unset/empty, which

means the full over-clarify standard and the pre-GO self-check apply (credo `session-active`

skill, CLARIFY-FIRST). The single value `clarify_depth: waived` records that the USER has

explicitly decided this item does NOT need the deep clarify - a small / easy item, or simply

their choice - so the depth obligations and the self-check are intentionally skipped and

never re-done against their will. Add a short reason inline or on an adjacent line, e.g.

`clarify_depth: waived # user: trivial rename, no deep clarify`. Only the user sets this;

an agent NEVER self-waives to save effort (same spirit as "never self-demote / size is not

grounds"). Like the blocker relations it is optional and adds no second status source - the

folder still owns status.

Further optional fields serve parallel scheduling (credo `orchestration` skill,

"Parallel code tracks: touches and resource gate"). All are normally absent and, like the

fields above, add no second status source:

- `touches` (optional): a list of paths or globs the item will likely edit, e.g.

`touches: [plugins/credo/scripts/credo-touches-check.sh, docs/*.md]` or a block list.

The plan / clarify agent sets it, at the latest at GO. It is guidance, not a contract:

the main agent re-checks it right before spawning builders and updates it when files were

renamed or moved. `credo-touches-check.sh <id> <id> ...` reports overlapping items, which

then run sequentially. Absent = the main agent classifies the item itself (parallel by

default).

- `heavy` (optional): `heavy: true` marks model / benchmark tests or large downloads. A

heavy item never runs in parallel to another heavy item and, like every start, starts only

when `credo-resource-check.sh` says `ok`.

- `disk_gb` (optional): `disk_gb: 12` is the free disk in GB the item needs on the target

drive while it runs (model files, large downloads, big build outputs). The start checks

`credo-resource-check.sh --disk-gb <disk_gb>`: the free space must cover `disk_gb` plus the

reserve `resources.disk_reserve_gb` (credo config, default 3 GB). An item without `disk_gb`

needs only the reserve. Not enough space = no start; the item stays in `2_go` and is retried

later, like a RAM wait (credo `orchestration`, "Disk space").

- `polish` (optional): `polish: true` marks pure polish, with a lighter audit and a best-effort

done (see "Polish items" below). Absent = the normal flow.

Two optional fields record who owns an item's open questions (the full rule is in

"Clarify owner and the agent decision rule" below). Like the fields above they add no

second status source:

- `clarify_owner` (optional): `human` or `agent`. **Missing = `human`** (fail-safe); any

other value is also treated as `human`. `human` = the item comes from the user's own

words, so its open questions are clarified with the user and only the user gives its GO.

`agent` = a builder, plan or task agent created it (a slice, a follow-up, a build

question, an audit finding), so the agent decision rule applies. `credo-item-move.sh`

sets `clarify_owner: agent` on every move into `2_go` and keeps the origin in the History

(`(origin: created by user; clarify_owner human -> agent)`): once an item is GO'd, a later

question about it very likely had no human in the loop. The helper is the only writer of

the human -> agent flip; never edit `clarify_owner: human` to `agent` by hand (the GO gate

then treats the item as human). On every move into `1_clarify` the helper sets

`clarify_owner: human` and logs `clarify_owner <old> -> human`; only an agent-internal

re-clarify passes `--keep-owner` (the unblock sweep does so for `unblock_to: clarify`).

- `parent` (optional): `parent: <id>` on an agent-created item names the item it came from

(the sliced, audited or built item). Set it together with `clarify_owner: agent`. While

the parent is not GO'd, the child counts as human-owned (no agent GO, see the rule below).

When creating an item: from the user's own words (a request, a bug report, an idea the

user stated) -> `clarify_owner: human` (or leave it out); created by a builder, plan or task

agent -> `clarify_owner: agent` plus `parent: <id>`, and the first History line says so:

`- created by agent (clarify) <date> (<why: slice / follow-up / build question / audit

finding of #<id>>)`. Without `parent:` or that line the GO gate treats a `clarify_owner:

agent` item as human. When in doubt, human.

## Filenames and ids

- File name: `<id>-<slug>.md`, e.g. `124-live-reload-panel.md`. The slug is a short,

lowercase, ASCII, dash-separated summary of the title.

- Frontmatter `id:` matches the number in the filename.

- Reference an item elsewhere as `#124` (plus its date/short context - transcript line

numbers are not stable references).

> **Output convention.** Item references are always written in inline-code style: `#37`,

> `#90`, `#91` (backticks) - never bold or plain. This improves scannability of item numbers.

- **Get ids only from the counter helper, never compute one yourself.** Issue the next id with:

```

"${CLAUDE_PLUGIN_ROOT}/scripts/credo-id-next.sh"

```

It is deterministic and never-reuse: the monotone counter, not the folder, decides the

number, so a deleted `#124` is never reissued. On each call the helper also scans the

items tree as a safety floor and takes `max(counter, highest existing id) + 1`, so a

stale or rolled-back counter (merge, clone, restore, sync) never hands out an id that is

already in use (it warns on stderr when it reconciles). Do not compute an id by scanning

files or taking `max+1` yourself - that reuses deleted ids and skips the lock.

## Body sections

Use these English headings in this order. A blank template ships at

`"${CLAUDE_PLUGIN_ROOT}/templates/item.template.md"`.

1. **Requirement (verbatim)** - the requirement in the user's own words, quoted exactly,

with its source. Never trim, soften, reinterpret, or invent constraints. Keep

user-verbatim text strictly separate from any assistant proposal (label proposals as

such). This mirrors the credo `requirements-verbatim` rule. Facts the owner already stated

(in chat, in clarify answers, in the requirements log) are written into the item, so the

owner never has to repeat them; the audit checks it.

2. **Success Criteria (= DoD)** - observable "the user can X" statements, each one

checkable. These ARE the Definition of Done for this item. Vague criteria that cannot

be observed are not acceptable; make each one exercisable.

- **Measure-then-user-decide is not one blocking DoD point.** A criterion where the

decision is the user's alone and only arises AFTER a measurement the build itself

produces (for example "measure whether the full solution is worth the cost, then decide

build vs skip") is NOT a single blocking criterion. Split it at the GO gate (see the

Definition of Done gate below and the `migrate` G4/G5 entry gate): the buildable

MEASUREMENT (produce the numbers / the concrete cost-benefit finding) stays in this item

as a criterion the builder CAN complete; the user-only decision becomes a SEPARATE item

in `1_clarify`, blocked on the measurement until the numbers exist, and only then does

the user decide. The parent then stays a clean all-or-nothing item over its buildable

criteria (the measurement included); it does not sit stuck half-done and is not bounced

whole back to `1_clarify` over a decision that is not yet open.

- **Tricky items carry their acceptance measurement BEFORE the build.** An item whose

result is an algorithm, a detection, or a quality or numeric outcome names in its

Success Criteria, before the build starts, the data set to measure on and the target

value (e.g. "on `fixtures/set-a` (120 cases) at least 95 % detected, 0 false

positives"). The builder measures against it before reporting done and records the

measured value in `## Verify`. This is different from the measure-then-user-decide

split above: here the target is fixed up front.

- **One state-of-the-art check per feature.** A `type: feature` item carries one DoD line for a state-of-the-art

check. The chosen approach is compared once against the best solution known today, and

the result is recorded in `## Implemented`. There is no recurring re-scan.

- DoD targets may be extended, never lowered; everything beyond the DoD goes into the

collection item ("Scope of an item" below).

3. **Implemented** - what was actually built, with concrete `file:line` references. This

is where the wiring is recorded (which caller reaches the new code).

4. **Verify** - the honest 4-valued verification state, per layer. See below.

5. **History (MANDATORY)** - the folder journey with dates. Every move writes a line

`-> <target> <date> (<reason>)`, e.g.

`created (clarify) 2026-07-04 -> go 2026-07-04 (GO: user, chat) -> done 2026-07-05`.

Record why an item moved, especially any move backwards. **Folder<->History invariant:**

the folder an item is in MUST match the target of its last History line. A mismatch is a

detected mis-move - flag it and correct it. This is the contradiction detector, achieved

without adding a second status source.

### Freigaben - approvals for downloads and installs (optional)

Only for an item that downloads or installs something (a model file, a package, a tool). The

optional section is `## Freigaben` (the German heading is kept; "approvals" in English). It is

filled in during clarify, BEFORE the GO, with one line per download or install, name, source

and version when known:

- `- pip: requests 2.32.3 (PyPI)`

- `- Download: <file> from <source>`

Rules:

- A GO covers exactly the listed entries and nothing beyond them. Anything else that turns up at

build time is a question: asked interactively, parked when autonomous. It is never installed

on the builder's own initiative.

- The security check stays mandatory for approved entries too: source, author, license and known

supply-chain problems (credo `safety`). Suspicious means nothing is installed and the item goes

back to `1_todo/1_clarify`.

- Clarify fills the section before the GO, so the owner sees every download and install in the

GO decision.

- No `## Freigaben` section means nothing is approved. The no-autonomous-installs rule (credo

`safety`) applies unchanged.

### Scope of an item (DoD targets, collection item, own items, legacy)

- **DoD targets are never lowered.** Agents may extend a DoD target where sensible (a useful

addition the owner would otherwise have to ask for), but a target is never lowered or moved

to pass. The audit judges against the target as it stood at GO plus any extension.

- **Facts the owner already stated** go into the item (Requirement section above), so the

owner never repeats them.

- **One collection item per project.** Everything beyond the DoD - MINOR and NIT findings the

DoD does not order, residual cases, and the residual risk of a best-effort goal (credo

`audit`, "Beyond the DoD and best-effort goals") - goes into ONE collection item per

project, with no own items and no new fix rounds for it. Reuse the open collection item;

create it only when none exists (in `1_todo/1_clarify`, without `parent:`, so it stays

human-owned and the owner decides what of it gets built). Each entry is one line with the

source item `#<id>`, the finding and its evidence.

- **Large new requirements get their own items** instead of widening an existing one. A

large requirement that turns up during clarify or build and goes beyond the item's scope

becomes a new item; it is not folded into the current item's DoD.

- **No legacy code.** No legacy or compatibility code (shims, fallbacks for old formats,

dual code paths) in the development state unless the owner explicitly marks it in the

item.

### Body-freshness invariant

A second contradiction detector, a sibling of the Folder<->History invariant above: the

body must NOT claim open / unbuilt / decision-needed for anything the reality of the item

contradicts - History `(GO:` and later `-> done` lines, `## Implemented` `file:line`

evidence, the requirements log (`.credo/process/requirements/*.md`), an audit report

(`.credo/process/reports/`), or the code / version itself. When the body says

"open / not built / still to decide" but one of those shows it was already GO'd, built,

clarified, or shipped, that is a detected contradiction. On such a contradiction, do NOT

silently build on it and do NOT silently keep reading past it: FLAG it fail-loud AND

reconcile the body in the SAME move (the Full-body reconciliation sweep in the

Build-completion gate is what performs that reconciliation). Like the Folder<->History and

not-started contradictions, this is a skill-level judgement, not a script: the staleness

lives in free-form prose, so it is caught by reading, not by a mechanical scan.

**Handoff labels and unticked DoD boxes.** A per-item status label carried in a handoff

("waits on T38", "waits on owner") is re-checked against the item's open DoD boxes and Body

before it is carried on. A label the DoD no longer supports is dropped, and any buildable work

it hid is listed as next (credo `compact-plus`, step 3). The same reconcile applies to DoD

boxes left unticked after a PASS audit: tick the fully met ones in the same move (the

Full-body reconciliation sweep).

## Item text is perspective-neutral (no "who is doing it")

An item file is durable and read by whoever builds it later - often a different agent or

session than the one that wrote it. Its text therefore describes the WORK and its

DEPENDENCIES, never who is currently handling it. Perspective-relative wording like

"another agent", "hands-off (other agent)", or "I do X, the other agent does Y" breaks

this: a later builder reads "another agent" as someone other than themselves and misreads

the item. Keep who-does-what coordination OUT of the item - it belongs only in the harness

task list (the ephemeral coordination layer defined in "Harness task-list vs .credo items"

above), not in the durable item. State dependencies

by item id (for example `blocked_by: [807]`), not by actor.

## The 4-valued Verify (honest, per layer)

For each relevant layer (`backend`, `ui`, `human-only`), record exactly one of four

states - honestly, never optimistically:

- **not-started** - the code/behavior for this layer does not exist yet; work on it has

not begun. Distinct from `n/a`, which means the layer does not apply at all.

- **present** - the code/behavior exists in the source, but has not been shown to run.

- **wired-but-behavior-unverified** - it is reachable and called (wired into a real code

path), but its actual runtime behavior has not been observed.

- **exercised** - the behavior was actually driven end-to-end and observed to be correct

(for `ui`, that means a real visual verify - see the credo `verify` skill).

For any `human-only` layer that only a person can confirm, add a `why_human` note

explaining what the user must check and why an agent cannot. Until the user has run it,

that layer reads `human-only: pending` (see below).

A verify attempt that surfaces a defect is a **failed** verify: that is not one of the

four progress states above, it is a defect outcome that sends the item back (see "Bug

found during verify"). Only `exercised` counts toward the Definition of Done; a

`human-only: pending` point does not hold the item back (next section).

### Human-only checks do not block done

Checks that only a human can run belong to the verify phase, not to done. An item is done

as soon as everything is built and the agent cannot do anything more on it without a human;

the human-only tests it still needs are recorded in the done item.

- An item moves to `2_done` once everything is built and every check the agent CAN run is

`exercised`. Pending human-only tests never hold an item in `2_go`.

- Write each one into the done item's `## Verify` as `human-only: pending` with the

`why_human` note and what to check (a numbered step list per the credo `verify` skill).

The user runs them in the verify phase (`2_done -> 3_verified`); a failure there sends the

item back per "Bug found during verify".

- Not a loophole: a check the agent can run itself (a test, a CLI call, a local browser) is

never human-only. Human-only means it genuinely needs the human - their hands or eyes on

real hardware, their account, a remote or shared environment the agent must not touch.

Wiring matters: new code with no caller / not reachable is a gap, not "done". At most it

is `present`. The DoD requires `exercised`, which forces the wiring to exist and to run.

If you find unwired code, that is a gap - raise or reopen an item for it.

### Wiring items (only for split server/client architectures)

This rule is CONDITIONAL: it applies ONLY when the project actually has a separated

server/client (or backend/frontend) architecture. Not every repo does - a single-surface

project has nothing to wire across a boundary, and this rule does not apply to it. State

the condition explicitly before invoking the rule.

Where the two halves ARE separate, an item without its wiring is useless: a server-side

capability that no UI ever calls delivers nothing. So when server and client parts are

split, a SECOND wiring item MUST exist that connects them, with a bidirectional reference

between the two (`blocked_by` / `blocks`).

- A server-side item MAY reach `2_done` while its UI-wiring item exists but is still in

`1_clarify` - the existence of the wiring item is what makes the server work meaningful;

it does not have to be built first.

- An agent MAY autonomously create and GO this wiring item and build it best-effort. It

is an agent-created item (`clarify_owner: agent`, `parent:` the server-side item), so

this is the agent decision rule applied ("Clarify owner and the agent decision rule");

human-owned items still follow clarify-first (only the user sets their GO).

Before you record `failed` or "not started" for a capability, you MUST first run a wiring

check against the real code: search the source for the endpoint, class, function, or

tests that would implement it. This matters most for items cut from older specs - the

feature may already have been built under a DIFFERENT task or item number, so assuming it

is missing is often simply wrong. If the check shows it is built but its runtime behavior

has not been observed, record `wired-but-behavior-unverified`, not `failed`. Reserve

`failed` for a real defect actually surfaced by exercising the code.

## Build-completion gate (record what you built, in the same move)

The moment build code is committed - an item has actually been built, not just planned -

the building agent MUST, in the SAME turn, bring the item file into line with that reality

(steps 1-3) and check its own work (step 4):

1. Fill `## Implemented` with concrete `file:line` evidence for what was built (which

caller reaches the new code).

2. Update the DoD / Success-Criteria ticks to match what is now true. Tick only fully met

points, never with a caveat ("done, but ..." stays unticked).

3. Move `## Verify` off `not-started` for the built layer(s) - at minimum to `present`, or

`wired-but-behavior-unverified` when the code is reachable and called. (`not-started`

means "work has not begun"; a build commit proves it has.)

4. Before reporting done, run an adversarial self-check: try to break what you built

(edge cases, bad input, the failure path, a second run, the unhappy UI path) and list in

the report what you tried and what held or was fixed. For a tricky item, also measure

against its acceptance measurement (Success Criteria above). This list is input for the

audit, not a replacement for it.

This is a mandatory step of the build routine, not a new script. An item with a build

commit that still says "not started" (in any language, e.g. German "noch nicht begonnen") is a CONTRADICTION between

the committed code and the item text - flag it and resolve it, exactly as with the

Folder<->History invariant. Leaving the item stale after committing build code is a

detected mis-state, never an acceptable end.

### Full-body reconciliation sweep (mandatory after every build AND every clarification)

The three steps above cover the fields you just touched. They are the floor, not the

ceiling: after every build (a build commit) AND after every clarification (a question

answered, a decision recorded), you MUST additionally reconcile the WHOLE item body against

the new reality, not only the fields you happened to edit. An item must NEVER be left

claiming "open / not built / decision needed" for anything that is now built or clarified -

items must not go stale. Sweep the entire file:

- ALL Success-Criteria / DoD ticks (not just the ones you touched) against what is now true.

- Every `## Verify` state against the real commit / verify reality.

- Any free-form "open / not built / still to decide / GO unclear" prose ANYWHERE in the

file - including the head, the `Requirement` section, and `History` notes (for example a

`> URGENT:` note that a now-answered decision has resolved) - updated or removed.

- Cross-references to other items that a change has made stale.

"Where needed / sensible": this is not a licence-to-churn - it forces no cosmetic edit and

no rewrite of prose that is still accurate. But every stale CLAIM must go: nothing in the

body may still assert open / unbuilt / undecided once the build or the clarification has

made it true. This applies to CLARIFY as well as BUILD - a clarified question is recorded

in the body as clarified and the old open-question prose is updated or removed in the SAME

move, not only after a code build. Leaving stale claims standing after a build or a

clarification is a detected mis-state, exactly like the Folder<->History invariant and the

not-started contradiction above - flag it and reconcile it in the same turn.

## Polish items (optional `polish: true`)

Polish is a best-effort kind of done for pure fine-tuning: wording, layout, small behavior

details. It is set during clarify, before the GO, by the owner's words or the clarifying agent

for an item the owner accepted as polish. It is NOT derived from `type`.

- **Flow:** one build, then one light audit (credo `audit`, "Polish items"). Findings are fixed

once, best effort. Then the item goes to `2_done`. There is no second audit round and no

fix-round loop.

- **Model and effort are not changed.** The user's own setting (preset or config) applies, with

no special tier for polish.

- **Leftovers** are listed under `## Verify` as a list for the next verify round with the owner

("best effort", not "perfect").

- **Not polish:** a broken function, data loss, or a security problem is an error. Such an item

takes the normal flow, without the polish shortcut.

- **Small findings never loop.** On a normal item, MINOR and NIT findings the DoD does not

order start no fix round. The auditor fixes them once or they go into the project's collection

item ("Scope of an item" above). The original item goes on, or goes to `done` once its DoD is

met.

## Definition of Done (the gate into 2_done/)

An item may move into `2_done/` ONLY when ALL of these hold. This gate is hard.

1. **Every Success Criterion the agent can check is `exercised`.** Nothing left at

`not-started`, `present`, or `wired-but-behavior-unverified`. A genuinely human-only

criterion does not block: it is recorded as `human-only: pending` with what to check and

runs in the verify phase ("Human-only checks do not block done").

2. **If `ui: true`, a passing visual verify is mandatory** - the credo `verify` skill at

every configured viewport (measured layout, real interaction, live update where

required, hard reload after rebuild), with screenshots saved under

`.credo/screenshots/`. Verify screenshots ALWAYS live under `.credo/screenshots/` and

follow the name pattern `<slug>-<viewport>-<YYYY-MM-DD>.png` - this holds even when an

ad-hoc verifier (not the formal `verify` skill) produces them, so every screenshot is

found in one place under one convention. The required level of test obligation is

defined by the credo `verify` skill (config `verify.primary_test`), not here. Only a

visual verify the `verify` skill itself defers as human-only (locality not established)

may stay `human-only: pending`.

3. **No open remainder** - nothing needed for the item's core is still outstanding that

the agent could do without the human (pending human-only tests are not a remainder).

4. **Mandatory audit-after-completed by a DEDICATED subagent** - the credo `audit` skill

MUST be run by a subagent that is NOT the builder of this item. A builder auditing

their own work does not satisfy the gate. This applies in every session mode (active,

passive, autonomous), no exceptions. Only a passing audit lets the item enter

`2_done/`. The audit DEPTH follows risk (`full` or `lean` tier, see the `audit` skill,

"Audit depth (risk tiers)"); the gate itself is never skipped.

5. **Docs updated in the same change** - documentation is part of the change, not a

follow-up. Any change that affects documented behavior MUST update the docs in the same

change; stale docs = incomplete (C14). Prefer `/dogma:docs-update` when dogma is

installed - it is the canonical README + wiki sync; if dogma is not installed, do a

best-effort manual update of the affected docs (companion tool when present, graceful

degrade when not). Scope explicitly includes the project wiki (a separate repo) and

in-repo READMEs, not just files inside this commit - "same change" is not "same repo

only". Search `docs/**`, `.credo/docs/`, in-repo READMEs, and the wiki for what the

change affects and update it now.

6. **Version bump as part of the DoD** - bump the version as part of completing the work,

dogma-first (follow dogma's versioning if present), credo as fallback only.

The parent's DoD is all-or-nothing over its BUILDABLE criteria ONLY. A

"measure-then-user-decide" point (a user-only decision that arises only after a measurement

the build produces) is NOT a blocking DoD point of the parent: at the GO gate it is split

into a buildable measurement criterion that stays in this item and a separate user-decision

item in `1_clarify` blocked on the measurement (see Success Criteria above and the `migrate`

G4/G5 entry gate). So the parent completes cleanly once its buildable criteria - the

measurement included - are `exercised`; it does not stay stuck half-done waiting on a

user-only decision, and it is not bounced whole back to `1_clarify` by the Named-Decision-Test.

`completed != done`: a builder saying "I finished" is not done. Done is the physical

`2_done/` folder, reached only after the audit gate passes. The marker is the folder, not

a claim and not a task-tracker field.

### Main-agent verification before claiming status or moving

Before the main agent asserts an item's status OR moves it between folders, it MUST read

the WHOLE item file - especially the latest verbatim statements and decisions in the

History and Requirement sections - and check the actual code/state against the item's

INTENT. Inferring status from a commit grep, a commit headline, or a subagent's report

ALONE is not grounds for approval: those are signals, not verification. Already-committed

work is not blindly blessed as done just because a commit exists - the main agent confirms

the built reality matches what the item requires before it claims a status or advances the

item.

The same whole-file read is required before the READ / BUILD decision, not only before a

status move: before ANY agent (main or subagent) treats a `2_go` item as still-open or

not-buildable, it reads the WHOLE body plus the requirements log and existing audit reports

(the read/build-gate in "go=go" above), never the head alone. A stale-looking head is not a

build decision - the whole body and the log are.

## 3_verified/ is human-authorized

An agent NEVER moves an item into `3_verified/` on its own initiative. `3_verified/` is

human-in-the-loop confirmation: the human is the sole authority for it. The agent's job is

to actively ask the user to re-test items sitting in `2_done/`, handing over a numbered

step-by-step test list (credo `verify` skill, "Handing a manual test to the user").

When the user explicitly instructs the move ("schieb #X nach verified", "item X =

verified", or similar), the MAIN agent - the one in direct user contact - executes it; it

does NOT refuse and does NOT tell the user to `mv` the file themselves. It runs:

```

"${CLAUDE_PLUGIN_ROOT}/scripts/credo-item-move.sh" <id> verified --user-authorized

```

The `--user-authorized` opt-in (or the env `CREDO_VERIFIED_USER_AUTHORIZED=1`) is what the

move helper requires for this target; without it the helper refuses. This does not weaken

the rule: the agent still never decides to verify on its own - it only mechanically carries

out an explicit user instruction. Subagents NEVER perform this move; they report back and

the main agent does it.

A `PreToolUse` hook (`credo-item-move-guard.sh`) additionally blocks a raw `mv` / `git mv`

of any item file in the status tree, so status changes go through the helper (which enforces

this opt-in for `3_verified/`).

A duplicate item file (a typo copy with the same `<id>`) is removed only through the helper and

only on the owner's explicit yes: `credo-item-move.sh --remove-duplicate <path>

--user-authorized`. It refuses unless another file with that id exists in the items tree, the

file is untracked or byte-identical to that other copy, and it is a regular file inside

`.credo/items`. Nothing else is removed, and the agent never runs a raw `rm` on item files.

## Bug found during verify -> back to 1_todo/1_clarify

`2_done/`**: an agent does not silently move a done item down; it records the finding and

moves it back to clarify per this rule (or, for a clear and approved fix, the audit skill

governs whether it returns to `2_go`).

Fix rounds after a failing audit follow the credo `audit` skill: a FRESH fix agent gets

only the findings, the branch state and the test commands (never the builder's resumed

context). There is no fixed fail count. Fix rounds follow only the active preset stage

ladder (`credo-preset.sh stage <role> <attempt>`), each stage with its configured attempts

(`until-done` has no attempt cap; the budget caps stop it), then back-to-human. While the

ladder has attempts left, whether another fix round runs is the main agent's decision, never

an owner question; an audit subagent never declares a brake itself. The item goes back to the

owner only at the ladder's back-to-human or for a genuine owner decision (the escalation list

and the Named-Decision-Test). By default the same finding returning unchanged twice is an early

hand-back as well; a repo's `.credo/RULES.md` can switch that default off.

This is the DONE-work case. A different case is a critical open user-only decision that

surfaces while building a `2_go` item (not yet done): that is governed by the

Named-Decision-Test above, which sends the item `2_go -> 1_clarify` (URGENT), not by this

done-work rule.

## GO-but-blocked (1_todo/3_blocked)

`3_blocked` holds an item that is fully clarified and GO'd (by the user, or for an

agent-owned item by the agent decision rule), but which is

hard-blocked by ANOTHER, still-unbuilt credo item. It is NOT a demotion of the GO - the GO

stands; the block only pauses it. When every blocking item is delivered, the item

auto-returns to its origin folder (its `unblock_to` target, `go` or `clarify`).

Distinct from `parked/hold`, which is for an EXTERNAL dependency (not another credo item) or

a block on something not yet GO'd. `3_blocked` is specifically an internal-item block on an

already-GO'd item, and that internal relation is what enables the automatic return.

### Blocker relations (structured, not a second status)

- `blocked_by: [ids]` on the blocked item, and `blocks: [ids]` on the blocking item.

- Bidirectional dependency graph, relational only - NOT a second status source. The folder

still says "blocked"; the relations only say by which item(s). Keep both sides in sync.

- Required whenever an item sits in `3_blocked`.

- `unblock_to: go|clarify` records the RETURN target for the auto-unblock sweep - the folder

the item came from before it was blocked. `credo-item-move.sh <id> blocked` writes it

automatically (source `1_clarify` -> `clarify`, `2_go` -> `go`, anything else -> `go`);

override with `--unblock-to clarify|go`. It is set only while the item sits in `3_blocked`

and is NOT a status source (the folder still owns status). A legacy blocked item WITHOUT

`unblock_to` defaults to `go` on unblock (the old contract).

### Block-guard (a block needs a concrete blocker)

An item may move to `3_blocked` ONLY with a concrete `blocked_by` referencing an unfinished

item. "Too big / too hard / uncertain" is NOT a block: such an item stays in `2_go` and gets

built (see "go=go" above). This stops an agent from parking buildable work as "blocked" to

avoid building it - the exact RETRO regression this guards against.

### Auto-unblock (deterministic, no new GO needed)

Auto-unblock is ENFORCED by `credo-unblock-sweep.sh`, not left to an agent to remember. The

sweep runs at two moments, so a delivered blocker never leaves a dependent stranded:

- **On every successful move into `2_done` or `3_verified`** - `credo-item-move.sh` invokes

the sweep (defensively; a sweep error never fails the move), so dependents return the

instant their last blocker is delivered.

- **At every SessionStart** (startup, resume, clear, compact, fork) via a hook, which

reconciles any backlog that built up while no move happened.

What the sweep does, for each item in `3_blocked`:

1. It reads the item's OWN `blocked_by` ids - the FORWARD edge - and looks up each blocker's

status (the folder it lives in). It deliberately does NOT walk the `blocks:` back-pointers,

which drift; the forward `blocked_by` edge is authoritative.

2. If EVERY blocker is in `2_done` OR `3_verified`, the block is over: it moves the item to

its `unblock_to` target (`go` or `clarify`; a legacy item without the field -> `go`) and

appends a History line `-> <target> <date> (auto-unblock: #<ids> done)`. **`4_archived`

does NOT count as delivered** - an archived blocker means the dependency was abandoned, so

the item stays blocked and is surfaced (below).

This is NOT a new GO - the original GO (the user's, or for an agent-owned item the logged

agent decision) still stands; the block merely paused it. The move helper still applies its

owner gate on this return, so a human-owned item that never had a user GO stays blocked

instead of slipping into `2_go`. The sweep is idempotent

(an unblocked item leaves `3_blocked`, so a re-run does not touch it) and never deletes

anything (it moves via `credo-item-move.sh`).

### Surfacing stranded blocked items (a nudge, no move)

For items that REMAIN in `3_blocked` after the auto-unblock pass, the sweep emits a short

nudge (at SessionStart, as `additionalContext`) when a blocker is not heading toward done:

- blocker in `1_clarify` - waiting on an undecided question;

- blocker in `4_archived` - stranded: the dependency was abandoned;

- transitive dead-end - the blocker is itself still `3_blocked`.

This is surfacing ONLY - the sweep never moves these; it just makes the dead-end visible so

the user or agent resolves the blocker (or re-decides). A blocker still in `2_go`/`parked` is

normal in-progress work and is NOT surfaced.

### Decision-hub items unblock their dependents by reaching done

A decision / clarify-hub item whose deliverable is a DECISION, not code (for example "decide

A vs B" that several other items are `blocked_by`), is **done once its decisions are captured

AND propagated into the dependent items** - then it may move to `2_done`, so it stops blocking

its dependents permanently. This is a convention, not a mechanism: there is no auto-move to

`2_done` for such an item; a human/agent moves it through the normal DoD gate once the

decision is recorded and the dependents updated. (Because `4_archived` does not count as

delivered, closing such a hub by archiving it would leave its dependents stranded - resolve

it to `2_done` instead.)

## Moving items (lifecycle)

Prefer the move helper - it is atomic, never deletes, and gates the human-authorized

`verified` target behind an explicit opt-in:

```

"${CLAUDE_PLUGIN_ROOT}/scripts/credo-item-move.sh" <id> <target>

# target: clarify | go | blocked | done | verified | archived | hold | future

# verified needs the --user-authorized opt-in and only on explicit user instruction:

# credo-item-move.sh <id> verified --user-authorized

# go for a human-owned item needs a "(GO: <user quote>)" History line, or the main agent's

# --user-authorized on the user's explicit GO (see "Clarify owner and the agent decision rule")

```

A raw `mv` / `git mv` of an item file inside the status tree is blocked by the

`credo-item-move-guard.sh` PreToolUse hook - always use the helper.

### Worktree cleanup at item close

Every item close - a move to `done`, `verified` or `archived` via `credo-item-move.sh` -

also cleans up finished parallel-track worktrees, automatically, without any prior command.

The same cleanup runs after every release (credo `orchestration`, "Default batch workflow";

credo `session-autonomous`, "Release when nothing is buildable").

The helper reads the DOGMA-PERMISSIONS checkbox in the `### Hydra` subsection (via

`credo-dogma-mode.sh`, works without dogma):

```

- [x] clean up merged worktrees automatically

```

- `[x]` - remove now, without asking (the user authorized it with the setting). The move

output lists `worktree cleanup: removed ...` and every kept worktree with its reason.

- `[?]` or no checkbox (older files predate the setting) - the move output lists the

`candidate` worktrees and the owner questions (kept, marked `(ask owner)`) and says to ask

the user; on a yes run

`"${CLAUDE_PLUGIN_ROOT}/scripts/credo-worktree-cleanup.sh"` (after the owner's yes, add one

`--allow-lossless <branch>` per approved `(lossless)` candidate; the hint prints them; in autonomous mode leave

them for the user and mention them in the run report).

- `[ ]` - never.

`credo-worktree-cleanup.sh [--dry-run] [--json]` removes ONLY worktrees whose branch is

merged into the main branch (the branch checked out in the main worktree). The branch tip is

an ancestor of it, or every commit of the branch is patch-equivalent in it (a rebased branch,

found with `git cherry`). The worktree must also be free of changes, meaning no uncommitted changes to

tracked files, no untracked non-ignored files (`git status --porcelain` is empty, apart from the

exceptions below), and no live

process with its working directory inside it. Ignored files (caches, build output) go with it;

an untracked symlink whose real target lies in the main checkout (a setup link) does not count.

**Lossless `.credo/` changes.** A merged worktree whose only changes are `.credo/` files is

lossless when every line of each changed file (untracked files and staged content included) is

already present in the same file of the main checkout; a repeated line needs a second copy there.

A deleted or renamed `.credo/` file, a file without a counterpart in the main checkout, a symlink

or any path outside `.credo/` is not lossless. A lossless worktree is removed like a clean one,

but only with `[x]`. With `[?]` or no setting the report lists it as `candidate ... (lossless)`;

after the owner's yes the agent runs the script with `--allow-lossless <branch>` for each approved

worktree (a path or a branch, repeatable; a bare `--allow-lossless` is an error; the one-off

approval never overrides `[ ]`). With `[ ]` it is kept. A helper that is missing or fails is read

as `[ ]`. A real ignored file under `.credo/` makes a worktree dirty; a setup link into the main

checkout does not count.

It never touches the main worktree, the worktree it runs in, ones named by `--keep`, unmerged

ones, and a worktree whose branch has no commit of its own (a fast-forward from main is not

one) while it is younger than 24h (an agent may be starting in it).

A merged worktree that is locked, has changes or has a live process in it is an owner question,

not a removal. Its report line ends with `(ask owner)`, for example

`kept <path> branch=<b> reason=uncommitted changes to tracked files (ask owner)`. Put it to the

owner as a ❓ question; the agent never removes it or unlocks it to get it out of the way.

Unmerged worktrees are kept without that marker. A locked one is reported as

`kept <path> branch=<b> reason=locked: <lock reason>` (plus `(ask owner)` when merged), also on

`--dry-run`.

It removes via `git worktree remove --force` (git unlinks symlinks and never follows them) and

deletes the merged branch with `git branch -d`. A rebased branch is not an ancestor, so `-d`

refuses it. The branch is kept, and the output carries `owner_command=git branch -D <branch>`.

Hand that command to the owner; the agent never runs `-D`. Every run covers all worktrees of the

repository, so the first run also sweeps the backlog. A cleanup error never fails the move.

**Keeping a worktree (opt-out = `git worktree lock`).** When the user says to keep a

worktree, lock it right away, with the reason `keep: owner`:

```

git worktree lock --reason "keep: owner" <path>

```

A locked worktree is never removed (cleanup script, `[x]` auto mode and `/hydra:cleanup`

alike) and shows up as `kept <path> branch=<b> reason=locked: <lock reason>` (with `(ask owner)`

when the branch is merged, so the owner can confirm the keep). List the locks and their reasons with

`credo-worktree-cleanup.sh --list-locked` (or `git worktree list --porcelain`, the `locked`

lines). Before closing an item, run `--list-locked` once and name the kept worktrees (and

their reasons) in the close note or run report, so the owner sees what stays around. For a

single run without locking, pass `credo-worktree-cleanup.sh --keep <path|branch>`

(repeatable; a string that is an existing directory is matched as a path first, so a

branch of the same name is not kept as well).

Unlocking (`git worktree unlock <path>`) follows one rule:

- credo AUTONOMOUS mode: the agent may unlock a `keep: owner` lock on its own once the keep

reason no longer applies (the instruction was fulfilled or revoked); it logs the unlock

and the reason in the run report.

- Every other mode (active, passive, default): only after asking the user via the Ask tool.

- A lock with any other reason (set by git, the harness, another tool or person; e.g. a

running agent's worktree) is not ours: never unlock it on your own, in any mode - report

it and ask the user. Autonomous mode leaves it locked.

Valid transitions (folder = status):

- `1_clarify -> 2_go` once the user gives an explicit GO (go-gate: only `2_go` is

buildable; `1_clarify` is not). For an agent-owned item (`clarify_owner: agent`) in an autonomous run the agent

decision rule may give the GO instead (`(GO: agent decision, <reason>)`, see "Clarify

owner and the agent decision rule"); a human-owned item always needs the user's GO, and

the move helper refuses it otherwise. In a presence session, clarify and propose that GO one

item at a time, each item in its own Ask round - see "One item per Ask round" in the

common core (session-active skill). Before proposing that GO, discharge the over-clarify

standard and its pre-GO self-check unless `clarify_depth: waived` (credo `session-active`

skill, CLARIFY-FIRST). At the latest at GO, set the optional `touches:` (and `heavy: true`

where it applies) when the likely edited files are foreseeable - see the optional fields

above.

- `2_go -> 3_blocked` when a concrete blocker on another unbuilt item is found (block-guard

above; requires `blocked_by`). NOT for "too big / too hard".

- `2_go -> 1_clarify` when a genuine user-only decision surfaces (the Named-Decision-Test

passes), typically mid-build. Agent-permitted - the one carve-out from "never self-demote";

NOT for "too big / too hard". Mark the returned item URGENT (see above) and record why;

the move helper sets `clarify_owner: human` (the open decision is the user's) and logs it.

- `3_blocked -> <unblock_to>` (`go` or `clarify`; legacy item without the field -> `go`) on

auto-unblock when EVERY blocker is in `2_done`/`3_verified` (not a new GO), enforced

deterministically by `credo-unblock-sweep.sh` on done/verified moves and at SessionStart.

`4_archived` does NOT count as delivered.

- `2_go -> 2_done` only after the full Definition of Done gate above passes (pending

human-only tests do not hold it in `2_go`).

- `2_done -> 1_clarify` when a bug is found (see above). The move helper sets

`clarify_owner: human` on entry into `1_clarify`; for a bug found by an audit or an agent

that the agent decision rule may settle, pass `--keep-owner` to keep `agent`.

- any -> `parked/hold` (external block) or `parked/future` (deferred), or `4_archived`

(abandoned/rejected); `3_blocked -> parked/*` or `4_archived` as usual.

- `2_done -> 3_verified` is **human-authorized**: an agent never does it on its own

initiative. Only the MAIN agent, and only on the user's explicit instruction, runs

`credo-item-move.sh <id> verified --user-authorized`; subagents never (they report back,

the main agent moves it). The human stays the sole authority - the agent only mechanically

executes an explicit instruction.

After any move, update the item's `History` section with the transition and its date.

Whenever you move something by hand instead of the helper, use `mv` (never delete + write)

so the id-counter invariant and the file's identity are preserved.

## dogma-first

Where dogma already governs a concern (versioning, git rules, language, linting), follow

dogma first and treat these credo rules as fallback only, never as a duplicate or a

conflict. DOGMA-PERMISSIONS always take precedence.