Template: Design note

How to use this template: create a new wiki page named Design: <short title>, copy everything below the line, and fill it in. Keep it short: a design note records one decision, not a spec. When the decision is made, add a row to the Decision log that links here.

---

Design:

Status	Draft / Under discussion / Decided / Superseded by Design: <title>
Author	@
Date	YYYY-MM-DD
Issue / discussion	#
Area	hooks / engine / DevSwarm / statusline / Codex port / docs / CI

Problem

What is wrong or missing today, and who it hurts. Include the evidence: an issue, a log line, a measurement, a failing test. One or two paragraphs.

Constraints

What any answer must respect. Check these for every note:

• No hardcoding: tunables, texts and rules live in plugin config files, not in engine source (see Engine internals).
• Both ports: the Claude plugin and the Codex port, or a stated reason why one does not apply.
• Fail-open: a hook error never blocks or wedges a turn.
• Every feature has a settings key.
• No automated deletion of user data.

Options

Option A:

How it works, in a few sentences.

• For: ...
• Against: ...
• Cost: size (S/M/L/XL), files or modules touched.

Option B:

...

Option C: do nothing

What happens if we leave it.

Decision

The chosen option, in one sentence, and the main reason it beat the others.

Consequences

• What changes for users (settings, messages, behaviour).
• What changes for contributors (new files, tests, rules).
• What gets harder, and what we accept as a trade-off.
• How we will know it worked (the metric, test or replay that proves it).

Follow-up

• Issue for the implementation: #
• Docs to update
• Row added to the Decision log