@debonet/idd 0.0.0-stage → 0.1.1

package/specs/guidance/codex.md

@@ -0,0 +1,93 @@
+# Guidance: questions in Codex
+
+Statement ids: complete
+
+## Purpose
+
+How a Codex session asks a question, captures the human's answer in the
+project's shared files, and carries an answer across sessions until it is
+incorporated. Each `[o-…]` citation names an entry of
+`~/@idd/observations.md`.
+
+## His words
+
+> {#m-zbztp6} From this session, as read 2026-11-04: "Right, so the purpose of
+> this session is to add codex specific support for @idd"
+
+## Asking
+
+* {#g-p0f582 <m-zbztp6@c44613a for=main via=prompt} **Add to the shared question list.** Before presenting a
+  question to the human, add it to `idd/questions.json` in the matching IDD
+  data worktree with `npm exec -- idd add`, following
+  `specs/guidance/writing-questions.md`.
+* {#g-az3d5j <m-edvy4l@54198de,m-zbztp6@c44613a for=main via=prompt} **Use Codex's questionnaire.** Present one complete
+  question with `functions.request_user_input_async`. Put the title and body
+  together in its `title` field, and pass every option as a choice string
+  beginning with its key and followed by its text.
+* {#g-hh957h <m-be8ix1@1bb0e96 for=main via=prompt} **Use the hosted questionnaire as a
+  fallback.** If Codex's interactive questionnaire tool is unavailable,
+  publish the question to the matching IDD branch and provide its direct
+  hosted viewer link; do not ask the decision only in terminal text.
+
+## Capturing an answer
+
+* {#g-7x2hqd <m-edvy4l@54198de for=main via=prompt} **Save the result locally.** When the human answers in
+  Codex's questionnaire, pass the chosen option key, note and save time to
+  `npm exec -- idd answer <id>` in the form its specification requires.
+  A tapped option is that choice with an empty note. For free text beginning
+  with an exact option key followed by ` — ` or `: `, use that key as the
+  choice and the remaining text as the note. For other free text, use an
+  empty choice and the full text as the note.
+* {#g-94d4e1 <arch for=main via=prompt} **Record before acting.** The `answer` command records
+  the answer in `idd/answers.json` and `idd/pending.json`; only after it
+  exits successfully does the session act on the answer, by
+  `specs/guidance/answers.md`.
+
+## Starting a session
+
+* {#g-vqum6f <arch for=main via=prompt} **Read the local queue.** At the start of a Codex
+  session, read `idd/pending.json` when it exists. Act on each pending
+  answer before the task the session was started for, following
+  `specs/guidance/session.md` and `specs/guidance/answers.md`.
+* {#g-u0m8hp <arch for=main via=prompt} **Clear after incorporation.** After incorporating a
+  pending answer, clear it with `npm exec -- idd clear-pending <id>
+  <time>`, using the `time` read from that pending entry. A changed answer
+  with a different time stays pending.
+* {#g-vuueha <arch for=main via=prompt} **Refresh hosted answers.** Before saying a hosted
+  question is still unanswered, and at the start of a session that has
+  hosted questions, fetch its `idd-<branch>` branch in the data worktree and
+  read the latest `idd/answers.json`; a stale local copy is not evidence that
+  an answer is still pending.
+* {#g-f73yzy <arch for=main via=prompt} **Publish from the agent.** After adding or changing
+  a hosted question, commit its `idd/` files to the matching IDD data branch
+  and push that branch to the same GitHub repository; pushing the branch
+  makes the project appear in the user's viewer. Obtain the page link with
+  `npm exec -- idd viewer-url <owner/repository> <code-branch>`; open it when the
+  session can open a browser and repeat the link in progress updates while
+  questions remain unanswered.
+* {#g-7beaaa <arch for=main via=prompt} **Record a fetched answer locally.** For each newly
+  fetched hosted answer, pass its `choice`, `note` and `time` as `sChoice`,
+  `sNote` and `dtm` to `npm exec -- idd answer <id>`; incorporate it and clear the
+  resulting local pending entry by `specs/guidance/session.md` before
+  reporting the question as handled.
+* {#g-rczwav <arch for=main via=prompt} **Publish hosted agent status.** Work in a
+  separate data worktree checked out at the matching `idd-<branch>` branch. Use
+  `npm exec -- idd status <session-id> blocked` only when a human answer is the sole
+  thing preventing progress; use `working` as soon as work can proceed, and
+  `clear` before ending the session. Commit and push each status change so
+  the viewer can show it.
+* {#g-bd17rs <s-7ppa6w@305659d for=main via=prompt} **Listen for hosted changes.**
+  Configure the IDD MCP server once with
+  `codex mcp add idd --url https://interrogation.dev/mcp`, then restart Codex.
+  While waiting on a hosted answer, keep both the MCP
+  `idd_wait_for_change` tool and `npm exec -- idd wait <question-id>` active.
+  When either reports a change, sync the matching IDD branch and inspect its
+  latest answers, thoughts and conflicts. Treat a second signal for the same
+  branch update as a duplicate; incorporate an answer only once.
+
+## Dependencies
+
+* {#p-uonp7o >specs/project-files.md} The shared question, answer and pending answer files.
+* {#p-4v8nei >specs/idd-page.md} The command that records and clears pending answers.
+* {#p-nulz3q >specs/guidance/writing-questions.md} The shared rules for writing a question.
+* {#p-e4c7xe >specs/guidance/answers.md} The shared rules for reading and incorporating an answer.

package/specs/guidance/session.md

@@ -0,0 +1,238 @@
+# Guidance: the session and its questions page
+
+Statement ids: complete
+
+## Purpose
+
+What the session that talks with the human does with its project's
+questions page: at its start, each time it needs his decision, and while
+answers are pending. Each `[o-…]` citation names an entry of
+`~/@idd/observations.md`.
+
+## His words
+
+> {#m-ja6m5r} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04:
+> "Whenever a session needs my decision on anything (a blocking question, an
+> architect's question, a choice between options), put it on a questions page
+> rather than only in the terminal."
+
+> {#m-vmsvl8} From the same section: "The pending queue is the record of what
+> you still owe me. … When you have incorporated an answer (briefed it, built it, or
+> put a follow-up question on the page), delete `pending/<sId>` with
+> ArtifactData, pinned with `if_version` to the version you read (phase 2),
+> so a change I make while you work stays pending. List `pending/` at the
+> start of every turn that touches the page and before every reply that
+> lists questions as open; a non-empty `pending/` is work, not something to
+> wait on."
+
+> {#m-brdqfi} From the same section: "In the terminal, a new question is
+> one short line that names it and says it's on the page, unless it is
+> urgent."
+
+> {#m-cj0deu} RULING (CEO) 2026-10-12 (AIOS): "When you ask new question: 1)
+> collapse the group of already-answered questions. 2) open the local browser
+> to the page"; and 2026-10-15, after a question asked in the terminal: "use
+> the web page for questions"
+
+> {#m-qx1889} RULING (CEO) (AIOS), after decisions were asked only in chat:
+> "I don't see any open questions on the questionaire"
+
+> {#m-dom4ly} RULING (CEO) (AIOS), after reports listed saved answers
+> as awaited: "These are not showing up on the page, they are in the already
+> answered collapse."; and a second time: "These are not showing up in my
+> unanswered list"
+
+> {#m-vc3mky} RULING (CEO) 2026-10-01 (AIOS), while a design was still being
+> shaped and an architect had been launched on it: "STOP WORKING UNTIL WE
+> AGREE ON SOMETHING."
+
+> {#m-7xfv1u} RULING (CEO) 2026-11-04, q199. The question: "IDD: pending
+> answers when a session starts. A new session finds answers you saved that
+> no session has acted on yet. Example: you open a session to fix a typo,
+> and yesterday's answer to q201 is still pending.
+> A) The session acts on q201 first, then does the typo.
+> B) The session says in one line that q201 is pending, does the typo, then
+> acts on q201.
+> C) The session names q201 and asks whether to act on it now." His answer:
+> A.
+
+> {#m-kh7vgm} THOUGHT (CEO), 2026-11-13: “We need to make sure that
+> when a question is answered (or observation given or conflict resolved.)
+> that only one active agent picks up on that work. Which means that when
+> agents pull a new chunk of work, they need to write back to the Jason file
+> and check it in indicating that they are doing that work.”
+
+## Starting a session
+
+* {#g-3ncq2t <m-vmsvl8@415d9d6 for=main via=prompt} **Find the matching IDD branch first.** At
+  the start of every session in an adopting project, run
+  `npm exec -- idd guide`,
+  identify the checked-out code branch and its `idd-<branch>` data branch,
+  and open or reuse a separate data worktree under the code checkout's
+  `tmp/` directory. Fetch that IDD branch before reading `idd/page.json`,
+  `idd/questions.json` or pending answers. If it does not exist, create it
+  from the code branch's IDD parent branch, or as a data-only branch when
+  there is no parent, then initialize the files and push it. Run all
+  `npm exec -- idd` commands from the data worktree; never commit IDD files to the
+  code branch.
+* {#g-24zjbf <arch for=main via=prompt} **Keep questionnaire commits separate.** Commit question,
+  answer, history, conflict and status files only to the matching
+  `idd-<code-branch>` branch. When a code branch has a parent, base its IDD
+  branch on the parent's IDD branch so the data histories remain mergeable.
+* {#g-n4s36y <m-vmsvl8@415d9d6 for=main via=prompt} **List hosted answers that are pending.**
+  When the viewer has open questions, refresh the matching IDD branch and
+  list its newly committed answers before any other work, and tell the
+  human in one line which question ids are pending.
+* {#g-u5t8t0 <arch for=main via=prompt} **List local answers that are pending.** Before any
+  other work, a session reads `idd/pending.json` when it exists and lists
+  its question ids with the other pending answers.
+* {#g-w42ybb <m-7xfv1u@663fe96 for=main via=prompt} **Pending answers come before the
+  task.** A session that finds pending answers at its start acts on each of
+  them, by The pending queue below, before it begins the task it was started
+  for, even a task unrelated to them, as fixing a typo.
+* {#g-yve3y9 <arch for=main via=prompt} **Review project thoughts.** At session start,
+  run `npm exec -- idd thoughts` from the matching IDD data worktree and
+  review submitted thoughts in creation order. Treat each as a plain-text
+  idea or observation from the human, not as a question that requires an
+  answer. Work on it when it applies and is not already reflected in the
+  project; if it needs a decision, ask a follow-up through the normal IDD
+  question flow. Do not rewrite or remove submitted thoughts.
+* {#g-mfqz8n <m-kh7vgm@5b68e68 for=main via=prompt} **Claim shared work before acting.**
+  Before incorporating a pending answer or acting on a submitted thought or
+  answer conflict, claim that item's stable id for this session with
+  `npm exec -- idd claim <kind> <item-id> <session-id>`. Commit and push
+  `idd/claims.json` to the matching IDD branch before starting the work. If a
+  push is rejected, sync the branch and inspect the claim; do not start work
+  unless this session owns the claim. After the work is incorporated, release
+  the claim with `npm exec -- idd release <kind> <item-id> <session-id>`, then
+  commit and push the release.
+
+## Every decision goes through the tool's questionnaire
+
+* {#g-ji85m3 <m-ja6m5r@30b5494,m-cj0deu@1f006c3,m-qx1889@b94432f for=main via=prompt} **In the
+  tool's questionnaire.** Every decision the session needs from the human,
+  an architect's question and an option an architect chose on his behalf
+  included, is added to `idd/questions.json` and presented with that tool's
+  questionnaire, even when it is also stated in terminal text. Check, before
+  ending a turn that asks him anything: `grep -c '"id": "q<N>"'
+  idd/questions.json` prints 1 for each question the turn names. [o-7ioawk]
+* {#g-qykl4x <m-brdqfi@33c1124 for=main via=prompt} **One line in the Claude Code terminal.**
+  In the terminal a new question is one short line naming its id and saying
+  it is on the page, unless it is urgent.
+* {#g-7pywro <m-be8ix1@1bb0e96 for=main,architect via=prompt} **Keep the viewer reachable.**
+  After publishing a question, open its direct hosted viewer link when the
+  agent tool can open a browser and include the link in the same update. At
+  session start, after progress reports, and whenever the agent says it is
+  waiting while any question remains unanswered, include the direct link
+  again so the human can reopen the page.
+
+## Adding a question
+
+* {#g-otl2eg <m-ja6m5r@30b5494,m-cj0deu@1f006c3 for=main via=prompt} **Tool-specific steps.**
+  Follow `npm exec -- idd guide` and the installed package's tool-specific
+  instructions to write and present the question through that tool's native
+  questionnaire. For a hosted question, commit and push the data worktree,
+  get its direct URL with `npm exec -- idd viewer-url`, open the page when the tool
+  can open a browser, and include the link in the update. Codex follows
+  `specs/guidance/codex.md`.
+  A question is never added to the question file by hand, since two
+  sessions adding at once would take one id (`specs/idd-page.md`, Concurrent
+  runs).
+* {#g-ffrx1c <arch for=main via=prompt} **An answered question is never edited.**
+  A question that has a saved answer is never edited, renumbered or removed
+  from the question file, since its answer is keyed by its id; a correction
+  or a follow-up is a new question. An open question's text may be
+  corrected before he answers it. Removing a question whose answer is
+  recorded makes `npm exec -- idd build` fail (`specs/idd-page.md`, check); an
+  answer saved on the page but not yet recorded has no such check, so a
+  pending answer is recorded before any question is removed or edited.
+  [o-k3r7wq]
+* {#g-csu92e <arch for=main via=prompt} **A recovered question comes back
+  answered.** A question recovered from history (a transcript, an old page,
+  the checkpoint repo) is restored to the question file only with its saved
+  answer recorded in the answer file first, so it draws among the answered
+  questions. A recovered question with no saved answer is restored as an
+  open card only after the question file is searched for a later question
+  that replaced it (`grep -n -i "replaces q<N>\|<two words of its
+  subject>" idd/questions.json`) and none is found; one that a later
+  question replaced is not restored as open. [o-r5wq2m]
+* {#g-ed18pa <arch for=main via=prompt} **A question holds every build that would
+  decide it.** After adding a question, find every brief and message sent
+  since the decision arose that would decide it, those of running agents
+  included (`grep -n "<two words of the question's subject>"` over them);
+  each gets an explicit "HELD: do not build X until q<N>" line, sent before
+  the next tool call. [o-1asexx]
+* {#g-s3n1rz <m-vc3mky@ab7c0a0 for=main via=prompt} **Nothing is built while he shapes it.**
+  While he is still shaping a design ("something like", a refinement, a
+  question), no agent is launched on it: reply with the proposal and wait
+  until he states it as settled.
+
+## Hosted agent status
+
+* {#g-rdv6ht <arch for=main via=prompt} **Report whether the agent is blocked.** A session
+  working with a hosted questionnaire writes its session entry to
+  `idd/status.json` on the matching `idd-<branch>` branch with
+  `npm exec -- idd status <session-id> <blocked|working|clear>`, marks itself
+  blocked only when it cannot continue without a human answer, and refreshes
+  `updatedAt` when that state changes or it reports progress. It commits and
+  pushes each change so the viewer can show it, then removes its entry when
+  the session ends.
+
+## Changed answers and conflicts
+
+* {#g-q1onm6 <m-hvgu3e@374ddc6 for=main,fixer via=prompt} When `idd/conflicts.json` has a new
+  submission that differs from the committed answer, keep that committed answer in force and
+  add a follow-up question to the shared questionnaire. Name both answer
+  choices and their submission dates, explain that the original may already
+  have been implemented and later decisions may depend on it, and ask whether
+  to switch to the new answer. Do not rewrite the original answer or resolve
+  the conflict before the follow-up is answered. Once answered, record the
+  ruling and mark the conflict resolved immediately; this moves the question
+  to Answered even if the implementation work remains. Then do the work the
+  ruling requires. A revisit that repeats the current choice and note is not a
+  conflict.
+
+## The pending queue
+
+* {#g-ll6nbu <m-vmsvl8@415d9d6 for=main via=prompt} **Pending is work.** A pending answer is
+  work for the session, not something to wait on. List the page's pending
+  answers at the start of every turn that touches the page and before every
+  reply that lists questions as open.
+* {#g-key6h6 <arch for=main via=prompt} **Local pending is work.** List the local pending
+  answers at the start of every turn that touches IDD and before every
+  reply that lists questions as open.
+* {#g-8dij85 <m-vmsvl8@415d9d6,m-dom4ly@9201ac7 for=main via=prompt} **A saved answer is an
+  answer.** An answer saved on the page is acted on whether or not a Done
+  comment named it. Before writing "waiting on q<N>", read `answers/q<N>`
+  in the same turn as the reply; a saved choice or note is acted on now.
+  [o-x2i8vm]
+* {#g-ynkoin <arch for=main via=prompt} **Record it first.** Before acting on a
+  pending answer, record it in the project's answer file
+  (`specs/project-files.md`, The answer file) with `npm exec -- idd
+  answer <id>`, which must exit 0; this also records the answer as locally
+  pending in `idd/pending.json`.
+* {#g-z1cvl1 <arch for=main via=prompt} **Publish the pending queue.** Commit and push
+  the answer and pending files on the matching IDD data branch after
+  recording a native answer, and commit and push pending-queue changes after
+  recording or clearing a hosted answer, so a later session can see the work
+  that remains.
+* {#g-mh145q <m-vmsvl8@415d9d6 for=main via=prompt} **Clear it once incorporated.** Delete a
+  question's `pending/` document only once its answer is incorporated (briefed
+  to an agent, built, or answered by a follow-up question on the page), and
+  pin the delete to the version of the document read before acting on it,
+  so a change he makes meanwhile stays pending.
+* {#g-yml7dk <arch for=main via=prompt} **Clear the local record after incorporation.** After a
+  local pending answer is incorporated, run `npm exec -- idd clear-pending <id>
+  <time>` with the time read from that answer. A newer answer with a
+  different time stays pending.
+
+## Dependencies
+
+* {#p-ta0zif >specs/project-files.md} The page file, the question file and the
+  answer file.
+* {#p-vmgrfz >specs/idd-page.md} The command that creates, checks and builds them.
+* {#p-zwayt9 >specs/questions-page.md} The page, its answer and pending documents
+  and its Done comment.
+* {#p-1kdv9a >specs/guidance/claude-code.md} How these steps are done with Claude
+  Code's tools.

package/specs/guidance/writing-questions.md

@@ -0,0 +1,171 @@
+# Guidance: writing a question for the human
+
+Statement ids: complete
+
+## Purpose
+
+How a question for the human is written and checked before it goes on the
+page, whoever drafts it. Each `[o-…]` citation names an entry of
+`~/@idd/observations.md`.
+
+## His words
+
+> {#m-zis8nz} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04: "Each
+> question is complete on its own. Give a short title, then a body that says
+> what I see, where and when, with a concrete example, then 2–4 options as `{
+> sKey, sText }`. Never point back at an earlier message, and never use code
+> or spec vocabulary I didn't introduce."
+
+> {#m-d0xavz} RULING (CEO) 2026-09-28 (AIOS): "OMG. FOr each of those questions,
+> ASK A COMPLETE QUESTION. Why are you making me scroll through pages of
+> useless thoughts?"
+
+> {#m-hrtndz} RULING (CEO) 2026-09-23 (AIOS), asked a question holding a word
+> from the specs: "what do you mean by frame? that's your own word"
+
+> {#m-cubli8} RULING (CEO) 2026-09-29 (AIOS), asked about a nickname coined in
+> a message: "What is a "saved box"?"; and 2026-10-07, shown a test fixture's
+> value: "What is a "nomen"?"
+
+> {#m-ggebxz} RULING (CEO) (AIOS), answering questions his standing
+> principle already answered: "OMFG. How many times do I need to say it"
+
+> {#m-p1sufn} RULING (CEO) (AIOS), asked where a new element's form is filled
+> in: "You are being frustrating this morning. <analyze> acts like group for
+> the purposes of rendering"
+
+> {#m-u8pt83} RULING (CEO) 2026-10-07 (AIOS), offered as a choice a behaviour he
+> would plainly reject: "Huh? … No."
+
+> {#m-pmw2kw} RULING (CEO) 2026-10-11 (AIOS), choosing an option added
+> only after he asked for an example: "Yes, c is better, but you had not
+> offered that before"
+
+> {#m-xqs1m0} RULING (CEO) 2026-10-04 (AIOS), on a delay an architect chose that
+> he had never seen: "brutally slow"
+
+> {#m-vk1rcm} RULING (CEO) (AIOS), after a ruling gave a key a new meaning:
+> "Argh. Shift-tab was already taken."
+
+> {#m-g3vhaa} RULING (CEO) (AIOS), on a card that described links as
+> pointing from the spec to the code: "THe spec should not link to the code!
+> The code should link to the spec! VERY VERY IMPORTANT."
+
+> {#m-nuw5vs} RULING (CEO) 2026-11-04 (AIOS), on a question "Where does the
+> new Security tab sit in the settings tabs?" whose options were after Admin
+> at the end, just before Admin, and right after Models: "Don't ask stupid
+> stuff like this. Just make a decision."
+
+> {#m-hg4vjm} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Development of web apps", as read 2026-11-04: "dont provide defaults. I
+> want to be asked the questions from the Architect."
+
+> {#m-4p034f} RULING (CEO), 2026-11-12: "it needs to contain sufficient context";
+> "it should not include any terms that the model has made up for its own
+> internal reasoning but has not discussed with the user"; "it should be
+> important / make a difference in the product"; "it should be asked in a
+> way in which the OBSERVABLE user behavior is evident, not just internal
+> implementtion detail"
+
+## The shape of a question
+
+* {#g-3e7r04 <m-zis8nz@70625d5,m-d0xavz@dfa3c86 for=main,architect via=prompt} **Complete on its
+  own.** A question has a short title, then a body saying what he sees,
+  where and when, with a concrete example, then two to four options. It
+  never points back at an earlier message or question; a label pointing back
+  is rewritten as the full question.
+* {#g-s88zfh <m-zis8nz@70625d5,m-hrtndz@38bc9ad,m-cubli8@a1b60f5 for=main,architect via=prompt} **His
+  words only.** A word from the specs, the code, a test fixture or a
+  nickname coined in an earlier message is not his word: before the question
+  goes on the page, each is replaced by what he sees on screen and one
+  concrete example.
+* {#g-rc16tq <m-zis8nz@70625d5 for=main,architect via=prompt} **Where, when and what it
+  looks like.** Every on-screen thing a question names comes with where it
+  appears, when, and what it looks like, in the same sentence.
+* {#g-y1fy29 <m-4p034f@bc4dca3 for=main,architect via=prompt} **Enough context.** Give the reader the
+  context needed to understand the situation and decide without searching
+  earlier messages or guessing what the question refers to.
+* {#g-clgrqj <m-4p034f@bc4dca3 for=main,architect via=prompt} **No private model vocabulary.** Do not use
+  terms the model invented in its internal reasoning unless the user has
+  already discussed those terms with the agent.
+* {#g-7yrr59 <m-4p034f@bc4dca3 for=main,architect via=prompt} **A consequential choice.** Ask only about a
+  choice that matters to the product or changes what the user experiences;
+  decide internal details that do not make a product difference without
+  asking.
+* {#g-3vophc <m-4p034f@bc4dca3 for=main,architect via=prompt} **Observable behavior.** Describe choices through
+  actions the user can take and results the user can observe, not through
+  internal implementation details.
+* {#g-68x1u5 <m-g3vhaa@078cb26 for=main,architect via=prompt} **Direction as the files
+  point.** A question about a link, reference or dependency names the file
+  the line is written in and quotes one example line in its body. [o-oud1hd]
+* {#g-ktwj32 <arch for=main,architect via=prompt} **Markup as it reads.** A body is
+  text (`specs/project-files.md`): markup quoted in it is written as it
+  reads, `<form>`, never as character references.
+
+## Before it is asked
+
+* {#g-802y2i <m-ggebxz@c2d2747 for=main,architect via=prompt} **The project's standing
+  principles decide first.** Before a question goes on the page, check it
+  against the principles the human has laid down for the project (in its
+  rules files and specs, quoted in his words); a question a principle
+  answers is not asked: the principle is applied and briefed to an
+  architect. An architect's decision made on his behalf is checked the same
+  way before it is relayed to him. [o-faqe7j]
+* {#g-hs5uln <m-p1sufn@a345c1d for=main,architect via=prompt} **Map onto what exists.**
+  Before asking how a new thing behaves, name the existing thing it already
+  behaves like; when one maps, brief that mapping and do not ask. [o-il1nvy]
+* {#g-ypnfcj <arch for=main,architect via=prompt} **Its example is a claim.** Each
+  "for example, X happens" in a question, and each claim about today's
+  behaviour, is checked against the spec that owns it before publishing
+  (`grep -rn -i "<two words of X>" specs/`), or asked of an architect first.
+  [o-bpncb3] [o-r5wq2m]
+* {#g-su9bba <arch for=main,architect via=prompt} **"You ruled" needs his words.**
+  Before writing "you ruled" in a question, find his quoted words in the
+  specs (`grep -rn "RULING (CEO)" specs/ | grep -i "<subject word>"`); if the
+  claim is not in them, write "the spec says". [o-bpncb3] [o-a1t5mg]
+* {#g-2dz6r0 <arch for=main,architect via=prompt} **Its options' premise is
+  checked.** Name the mechanism an option rests on and read his own words on
+  it; when they do not state that premise, the premise goes to an architect
+  as a defect and the option is not sent. Before proposing a mechanism as
+  new, search the specs for it (`grep -rln -i "<two or three words>"
+  specs/`).
+* {#g-qqyc01 <m-vk1rcm@8f6e65b for=main,architect via=prompt} **A new meaning takes away an
+  old one.** When a ruling would give a key, gesture or word a new meaning,
+  search the specs for its existing meaning; any hit puts the collision on
+  the page before anything is built. [o-m7spcg]
+* {#g-s794hn <m-nuw5vs@c4a6df9 for=main,architect via=prompt} **An arrangement detail is
+  decided, not asked.** When he would accept every option of a question and
+  its only effect is an arrangement detail that is cheap to change later
+  (the order of items in a row, where a thing is placed, which side a label
+  sits on), the architect decides it, or the session when no architect is
+  involved, records the decision as a statement rooted `<arch`, and mentions
+  it to him in one line of the report that relays the work; it never goes on
+  the page. [o-tq4n8z]
+* {#g-zvah92 <m-nuw5vs@c4a6df9,m-hg4vjm@f42adfd for=main,architect via=prompt} **Only an
+  arrangement detail.** The rule above narrows which of an architect's
+  questions reach him; it defaults nothing he would feel. A decision that
+  changes what he can do, what he sees happen, or how long he waits (A
+  number he will feel is a question, under Options) still goes on the page,
+  as his instruction to be asked the architect's questions requires; a
+  detail that might be more than an arrangement detail is asked.
+
+## Options
+
+* {#g-lhd91k <m-pmw2kw@7653d9c for=main,architect via=prompt} **Offer the right
+  answer.** The option set includes the answer that follows from his
+  standing principles, written as an option he can tap.
+* {#g-tbgfhw <m-u8pt83@4a4e1a8 for=main,architect via=prompt} **Offer nothing he would
+  plainly reject.** Before offering an option, check it against the obvious
+  expectation of the product; a behaviour he would plainly reject is a
+  defect for an architect, not an option. A remedy offered is checked to
+  have the property it is offered for.
+* {#g-zthj3e <m-xqs1m0@41fcfbf for=main,architect via=prompt} **A number he will feel is a
+  question.** A delay, timeout or cap an architect chose on a path he waits
+  on goes to him as a question naming the number, where he waits on it and
+  the alternative; it is never a default.
+
+## Dependencies
+
+* {#p-hd2fyx >specs/project-files.md} The form a question is written in.
+* {#p-2s93p6 >specs/guidance/session.md} How a written question reaches the page.