@debonet/idd 0.0.0-stage → 0.1.0

package/specs/guidance/session.md

@@ -0,0 +1,223 @@
+# 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.
+
+## 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.
+
+## 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.