@debonet/idd 0.0.0-stage → 0.1.0

package/specs/idd-merge-hook.md

@@ -0,0 +1,42 @@
+# idd-merge-hook
+
+Statement ids: complete
+
+## Purpose
+
+The Git hook command that makes agents reconcile project questionnaire
+branches before completing a code-branch merge.
+
+## API
+
+* {#s-e4kj5b <arch} `npm exec -- idd-merge-hook install` writes executable IDD
+  hooks to `.githooks/` and sets the clone's `core.hooksPath` to that
+  directory. The hooks invoke the package through `npm exec -- idd-merge-hook`.
+  In a Concord project, its pre-commit hook also runs the Concord spec gate.
+  It is repeatable and refuses a different configured hook directory or
+  existing default hooks that it cannot preserve.
+* {#s-t0r5nn <arch} `idd-merge-hook check` exits 0 only when the configured hook
+  directory and all required executable hook files and commands are present.
+* {#s-sjb7rh <arch} `idd-merge-hook reviewed` can run only during a code merge;
+  it fetches `origin` and records a review only when the source IDD branch is
+  an ancestor of the target IDD branch.
+* {#s-02z196 <arch} A review record binds the source and target code commits,
+  source and target code branch names, and both IDD branch commits. A later
+  change to any bound commit invalidates that review.
+* {#s-sj7f9n <arch} During an active code merge, `pre-commit` and
+  `pre-merge-commit` fetch `origin` and exit 0 only when no project
+  questionnaire branches exist or a matching review record covers an IDD
+  source history already merged into the target and the local IDD branches
+  have no unpublished commits. Otherwise they print the source and target
+  branches and the required IDD reconciliation steps, then exit 1. Outside a
+  code merge they exit 0 without fetching.
+* {#s-wjofsg <arch} After a code merge, `post-merge` fetches `origin`, verifies
+  that the reviewed source IDD history remains in the target IDD branch, and
+  removes the review record. It exits unsuccessfully if the review or
+  reconciled history no longer matches.
+
+## Dependencies
+
+* {#p-cqaul6 >specs/guidance/agent-merge.md} The agent's semantic reconciliation
+  process for duplicate, obsolete, or conflicting questions.
+* {#p-gpf7kp >specs/build.md} The package command and repository hook setup.

package/specs/idd-page.md

@@ -0,0 +1,340 @@
+# idd
+
+Statement ids: complete
+
+## Purpose
+
+The npm-installed command that prints IDD's workflow, creates a project's
+page file and question file, checks them, builds the questions page from
+them, adds questions with branch-scoped hash ids, records and clears answers
+in the project's answer and pending answer files, and imports questions
+from a page made from the older template; it also reports session status,
+prints a hosted viewer link, and counts questions on an IDD branch.
+
+## His words
+
+> {#m-f2iwx9} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04: "Every
+> time a question is added: insert the question object before the closing
+> `];` of `vaQuestion`, republish to the same URL, and open the page in my
+> local Chrome"
+
+> {#m-xoqfn9} From this session, 2026-11-11: “we should offer the agents tools to
+> quickly get a count of conflicts/unanswered/answered/suspended questions.
+> It should by default pull the current idd-<branch> to make sure its synched.
+> It can have a --nosync option to turn that off. And flags for returning just
+> one of the counts, e.g. --type {c,u,a,s,conflicts,unanswered,answered,suspended}.”
+
+> {#m-xhv3ci} In answer to the IDD question “What should the suspended count
+> measure?”, he wrote: “I meant \"superseded\" not \"suspended\"”
+
+## API
+
+* {#s-4lt6mo <m-f2iwx9@98efad1} **One command.** The command is `idd
+  <subcommand> [arguments]`, installed by the public `@debonet/idd` npm
+  package and run from the IDD data worktree; {#s-s1eg2z <arch} it reads and
+  writes every project path relative to that worktree, never writes outside
+  it, and finds its own resources relative to its installed package.
+* {#s-hsle36 <arch} **`guide`** prints the package's current canonical
+  adoption and session instructions to stdout and exits 0 without requiring
+  a project page or changing files.
+* {#s-7wfrt9 <arch} **`viewer-url <owner/repository> <code-branch>`** prints
+  a direct link to that repository branch's hosted questionnaire. It URL
+  encodes both values and uses `IDD_VIEWER_URL` when set, otherwise the
+  package's configured public viewer address. It does not read a GitHub
+  credential or change files.
+* {#s-dal2u7 <arch} **`wait <question-id> [interval-seconds]`** subscribes to
+  the hosted viewer's event stream and checks the matching remote IDD branch
+  through the current worktree's configured Git remote when the wait starts
+  and when an invalidation arrives. It defaults to a 30-second interval and
+  accepts intervals from 1 to 3600 seconds; it checks the remote branch at
+  that interval while push delivery is unavailable or the event stream is
+  disconnected. When the question has an accepted answer, it fast-forwards
+  the clean local data worktree, records that already-accepted answer in
+  `idd/pending.json` without rewriting `idd/answers.json`, prints the answer
+  as JSON and exits 0.
+* {#s-854kw7 <arch} `wait` refuses to run from a dirty worktree, does not
+  commit or push, and uses the repository's configured Git credentials
+  without storing or displaying them. It exits 1 if the remote cannot be
+  fetched or fast-forwarded, and exits 130 when interrupted.
+* {#s-dvurdo <arch} **Usage errors.** With no subcommand, an unknown one, or the
+  wrong number of arguments, it prints a usage line to stderr, writes
+  nothing and exits 2.
+
+## branch-hash
+
+* {#s-2bfbql <arch} **`branch-hash <repository-id> <full-ref>`** prints the lowercase
+  SHA-256 digest of the UTF-8 JSON serialization of `[String(repository-id),
+  full-ref]` and exits 0; `<full-ref>` is a full Git ref such as
+  `refs/heads/main`.
+* {#s-0ys3dr <arch} **Refused input.** When the repository id is not a positive
+  decimal integer or the full ref does not begin with `refs/heads/` and name
+  a non-empty branch, the command prints the problem to stderr and exits 2.
+
+## status
+
+* {#s-zqk718 <arch} **`status <session-id> <blocked|working|clear>`** updates
+  `idd/status.json`: `blocked` and `working` store the selected boolean
+  and the current ISO 8601 `updatedAt` under the session id; `clear` removes
+  that entry and leaves an empty object when it was the last one.
+* {#s-qvff9k <arch} **Session id and file validation.** A session id is a non-empty
+  string of at most 128 ASCII letters, digits, periods, underscores, colons or
+  hyphens. The command refuses malformed status data without changing the
+  file with exit 1; an invalid session id or state exits 2. `check` validates
+  every entry by `specs/hosted-questionnaire.md`. Clearing an absent entry
+  succeeds without writing the file.
+
+## count
+
+* {#s-vwase3 <m-xoqfn9@0df3826} **`count`** reports the counts of conflicting, unanswered,
+  answered and superseded questions in the current IDD data branch. With no
+  `--type` option, it prints one `<type>: <count>` line for each, in that order;
+  with `--type <type>`, it prints only that count as a decimal integer.
+* {#s-4w8iuj <m-xoqfn9@0df3826,m-xhv3ci@566158e} **Count types.** `--type` accepts `c`, `u`, `a`, `s` and their
+  full names `conflicts`, `unanswered`, `answered`, and `superseded`. `s` is
+  the alias for superseded questions.
+* {#s-83u8i8 <arch} **Conflicting questions.** Count each active question once when
+  at least one rejected answer has a different choice or note from its
+  accepted answer, or when it has a rejected answer and no accepted answer.
+* {#s-1mid3a <arch} **Unanswered questions.** Count each active question once when
+  it has neither an accepted answer with a choice or note nor a conflicting
+  rejected answer.
+* {#s-6uvlo6 <arch} **Answered questions.** Count each active question once when
+  it has an accepted answer with a choice or a non-empty note and no
+  conflicting rejected answer.
+* {#s-t8xsan <m-xhv3ci@566158e} **Superseded questions.** Count the entries in the IDD branch's
+  question history file; each entry is one superseded question.
+* {#s-jpjbwh <m-xoqfn9@0df3826} **Sync by default.** Unless `--nosync` is supplied, `count`
+  requires a clean Git worktree checked out on an `idd-<branch>` branch,
+  fetches `refs/heads/<current-branch>` from `origin`, and fast-forwards the
+  worktree before reading question data. It never commits or pushes.
+* {#s-yufw52 <m-xoqfn9@0df3826} **No sync.** `--nosync` skips the fetch and fast-forward and
+  counts the current worktree contents without requiring it to be clean.
+* {#s-14wrxl <arch} **Usage errors.** `--type` requires one supported type, may be
+  supplied once, and `--nosync` may be supplied once. Unknown options,
+  unsupported types or repeated flags print usage to stderr and exit 2.
+* {#s-amd1ad <arch} **Sync errors.** With `idd/page.json` present, a non-IDD
+  branch, dirty worktree during sync,
+  fetch failure or non-fast-forward update prints an error to stderr and exits
+  1 without changing tracked questionnaire files. Invalid question data exits
+  1 with the validation problems on stderr and prints no counts.
+
+## thoughts
+
+* {#s-8hvj7z <arch} **`thoughts [--nosync]`** lists the project's thoughts from
+  `idd/thoughts.json` in append order, printing each thought's id, timestamp
+  and plain text. It prints `idd: no thoughts` when the file is absent or
+  empty. It does not change files.
+* {#s-wapj39 <arch} By default, `thoughts` requires a clean worktree checked out on
+  an `idd-<branch>` branch, fetches the matching remote branch from `origin`
+  and fast-forwards before reading. `--nosync` skips synchronization and
+  reads the current worktree contents. It never commits or pushes.
+* {#s-twjecx <arch} `thoughts` validates each record against
+  `specs/project-files.md`; invalid data prints problems to stderr, prints no
+  thoughts and exits 1. A non-IDD branch, dirty worktree during sync, fetch
+  failure or non-fast-forward update also exits 1 without changing tracked
+  questionnaire files.
+* {#s-g5gxep <arch} `check` validates `idd/thoughts.json` when present, including
+  exact members, non-empty text, valid branch hash, ISO 8601 timestamp,
+  unique ids, and each id's digest.
+
+## init
+
+* {#s-51ncq9 <arch} **`init <title> <branch-hash>`** writes `idd/page.json`
+  holding `title` set to `<title>`, `url` set to `null`, and `branchHash`
+  set to `<branch-hash>`, and `idd/questions.json` holding an empty array,
+  then exits 0.
+* {#s-cd2jke <arch} **It never overwrites.** When either file exists, `init` writes
+  nothing, prints a line naming the existing file to stderr and exits 2.
+
+## check
+
+* {#s-hcsr5l <m-f2iwx9@98efad1} **`check`** reads both files and prints to stdout one line per
+  way they differ from `specs/project-files.md`, each `<file>: <problem>`
+  naming the question id where the problem is in a question, and exits 1
+  when it printed any; {#s-9exkpo <arch} with no problem it prints `idd: ok` and
+  exits 0.
+* {#s-2b5w6i <arch} **What it catches.** It reports a file that is not JSON, a
+  member missing, of the wrong form or not named by
+  `specs/project-files.md`, a branch hash that is not 64 lowercase
+  hexadecimal characters, a question id that differs from its hash of the
+  question's own `branchHash` and content, an id two questions share,
+  an options array of fewer than two or more than four options, and a key
+  two options of one question share, or a `createdAt` that is not an ISO
+  8601 time; it also checks question snapshots and replacement links in
+  `idd/history.json`, and accepts answers and pending answers for active or
+  historical question ids; when `idd/conflicts.json` exists, it validates
+  every rejected answer against its question and options.
+* {#s-pmnqlm <arch} **The answer file.** When `idd/answers.json` exists, `check`
+  also reports each way it differs from `specs/project-files.md`, The
+  answer file: a file that is not JSON or not an object, a member whose
+  name is no question's id, a value missing a member, holding another or
+  holding one of the wrong form, and a `choice` that is neither `""` nor a
+  key of its question's options. {#s-a1zj4t <arch} An absent answer file is not a
+  problem.
+* {#s-ikua3t <arch} **The pending answer file.** When `idd/pending.json` exists, `check`
+  reports each way it differs from `specs/project-files.md`, The pending
+  answer file, including an answer that differs from the answer file.
+* {#s-sse100 <arch} **No page file.** When `idd/page.json` does not exist, every
+  subcommand but `init`, `guide`, `viewer-url` and `branch-hash` exits 2 and
+  names the missing page file on stderr. `import`, when the question file does
+  not already hold questions, reports the missing page through its own import
+  error because it needs the page's branch hash to create question ids.
+
+## build
+
+* {#s-qzz6xu <m-f2iwx9@98efad1} **`build`** runs the check; when the check reports
+  any problem it prints the problems, writes nothing and exits 1;
+  otherwise it writes `tmp/idd/page.html`, creating `tmp/idd/` when absent,
+  prints that path and exits 0.
+* {#s-gcsqgg <m-f2iwx9@98efad1} **The built page.** The built page is the questions page
+  (`specs/questions-page.md`) drawing exactly the question file's questions
+  in its order, titled with the page file's title.
+* {#s-t2pr4c <arch} **Any text survives.** A title, body, option text or tag holding
+  any characters, `</script>`, quotes, backslashes and non-ASCII text
+  among them, is drawn by the built page exactly as the question file holds
+  it.
+
+## add
+
+* {#s-mvtsgu <m-f2iwx9@98efad1,m-edvy4l@54198de} **`add`** reads from stdin one JSON object
+  holding exactly the members `title`, `body` and `options`, each in the
+  form `specs/project-files.md` gives a question's (The question file),
+  appends the reserved X option from `specs/project-files.md` when absent,
+  computes its id as the lowercase SHA-256 digest of the UTF-8 JSON
+  serialization of `[branchHash, title, body, options]`, with each option,
+  including reserved X, represented as `[key, text, tag-or-empty-string]`, where `branchHash` is
+  the current page file's branch hash; stores that hash in the question,
+  adds the current ISO 8601 time as `createdAt`, appends it to
+  `idd/questions.json`, prints the id to stdout and exits 0. A legacy
+  question whose id predates X being included retains its id; the checker
+  accepts that prior formula, and duplicate detection compares a legacy
+  question after adding X for display so the same question cannot be added
+  again under a different id.
+* {#s-hbdizs <arch} **Only the end changes.** `add` leaves every question the file
+  held, and their order, as it was.
+* {#s-zopa6h <arch} **Refused input.** When stdin does not hold such an object,
+  `add` writes nothing, prints one line per problem to stderr, each naming
+  the member at fault, and exits 2. When the computed id is already in the
+  question file, including after normalizing a legacy question by adding the
+  reserved X option, it writes nothing, shows the existing question, and exits 2.
+* {#s-yx8tuh <arch} **Files that fail the check.** After stdin passes `add`'s
+  input validation, when the check reports any problem in the project's files
+  as they are, `add` prints the problems, writes nothing and exits 1.
+* {#s-xrkyna <arch} **No id-only subcommand.** No subcommand prints a question id
+  without adding the question: `next-id` is an unknown subcommand.
+
+## archive
+
+* {#s-9oyy6g <arch} **`archive <question-id> <replacement-id>`** moves the active
+  question named by `question-id` to `idd/history.json` with its complete
+  question snapshot, the replacement id and the current ISO 8601 time; it
+  removes the question from `idd/questions.json` and leaves its answer and
+  pending answer unchanged.
+* {#s-f9mmtf <arch} **Refused input.** It writes nothing and exits 2 when either id
+  is invalid, the question is not active, the replacement is not active, both
+  ids are equal, or the question already appears in history. It writes nothing
+  and exits 1 when the current project files fail `check`.
+
+## answer
+
+* {#s-2s3q95 <arch} **`answer <id>`** reads from stdin one JSON object holding
+  `sChoice`, `sNote` and `dtm`, in the form of the page's answer document
+  (`specs/questions-page.md`, API), and records it in `idd/answers.json` as
+  the member `<id>` whose `choice`, `note` and `time` are their values
+  (`specs/project-files.md`, The answer file), then exits 0. {#s-akhsa6 <arch} It
+  creates the file when it is absent and leaves every other member as it
+  was. {#s-19wno0 <arch} It also records the same answer under `<id>` in
+  `idd/pending.json`, creating that file when absent, and leaves every other
+  pending member as it was. {#s-pos9d5 <arch} Any other
+  member of the object read is ignored.
+* {#s-y1y75p <arch} **An accepted answer cannot be replaced.** With the page
+  file present, when the answer file
+  already holds `<id>`, `answer` writes nothing, prints the accepted answer
+  to stderr and exits 2.
+* {#s-o5jdcy <arch} **Refused input.** When `<id>` is the id of no question of the
+  question file, stdin does not hold such an object, `sChoice` is neither
+  `""` nor a key of that question's options, `sNote` is not a string, or
+  `dtm` is not an ISO 8601 time, `answer` writes nothing, prints a line
+  naming the problem to stderr and exits 2.
+
+## clear-pending
+
+* {#s-09iime <arch} **`clear-pending <id> <time>`** removes `<id>` from
+  `idd/pending.json` only when its recorded `time` exactly equals `<time>`;
+  when the id is absent or its time differs, it writes nothing and exits 0;
+  when the last member is removed, it leaves the file as an empty object.
+* {#s-p66ewo <arch} **Refused input.** When `<id>` is the id of no question or `<time>` is
+  not an ISO 8601 time, `clear-pending` writes nothing, prints the problem
+  to stderr and exits 2.
+
+## import
+
+* {#s-hnxl58 <arch} **`import <page>`** reads `<page>`, an HTML page made from the
+  older template, which holds its questions as a JavaScript array literal
+  assigned to `const vaQuestion`, and writes them, in the same order, to
+  `idd/questions.json` in the form `specs/project-files.md` gives.
+* {#s-vhstia <arch} **Keys.** Each question's `sTitle` and `sBody` become
+  `title` and `body`, its `vaOpt` becomes `options`, and each option's
+  `sKey`, `sText` and `sTag` become `key`, `text` and `tag`; its id is
+  computed from the page file's `branchHash` and converted question fields,
+  and `createdAt` is the time the import runs.
+* {#s-tasgnp <arch} **Bodies become text.** An imported body is
+  converted from HTML to text: each `<code>…</code>` becomes the same text
+  between backticks, each `<br>` and each paragraph break becomes a blank
+  line, every other tag is removed and its text kept, and every character
+  reference, as `&lt;`, becomes its character.
+* {#s-yl6bcx <arch} **Titles, option texts and tags stay text.** An imported title,
+  option text or tag is not converted from HTML: no tag in it is removed and
+  no backtick or blank line is added, so a title `<analyze> reading a
+  pop-up` imports as `<analyze> reading a pop-up`.
+* {#s-irxy7e <arch} **Their character references are decoded.** In an imported
+  title, option text or tag, each `&lt;`, `&gt;`, `&quot;` and `&amp;`, and
+  each numeric character reference, decimal (`&#60;`) or hexadecimal
+  (`&#x3c;`), becomes its character, decoded once, so `&amp;lt;` becomes
+  `&lt;`; every other character, other named references among them, is kept
+  as written.
+* {#s-zmh8z6 <arch} **It never overwrites questions.** When `idd/questions.json`
+  exists and holds any question, `import` writes nothing, prints a line
+  naming the file to stderr and exits 2.
+* {#s-51kf4i <arch} **An unreadable page.** When `<page>` cannot be read or holds
+  no `vaQuestion` array literal it can read, `import` writes nothing, prints
+  a line naming the page and the problem to stderr and exits 2.
+
+## Concurrent runs
+
+* {#s-lzdklu <m-edvy4l@54198de} **Concurrent adds preserve distinct questions.** Any number of
+  `add` runs started at once on one project preserve every distinct
+  question they add, each under its computed id; identical questions share
+  an id and only one is stored.
+* {#s-vhcbdr <m-edvy4l@54198de} **No answer is lost.** Any number of `answer` runs started at
+  once on one project for different ids leave every one of their answers in
+  the answer file.
+* {#s-z8braj <arch} **One step from read to write.** Every subcommand that writes a
+  project file makes its decision on the files as they are at the moment it
+  writes: no other run writes a project file between the read it decides on
+  and its write.
+* {#s-cals8z <arch} **No half-written file.** A run that reads a project file while
+  another run writes it reads the whole file as it was either before or
+  after that write.
+* {#s-4y820y <arch} **Consistent checks and builds.** `check` and `build` take the project
+  lock while reading the project files, so they do not see the interval
+  between `answer` writing the answer file and its pending answer file.
+* {#s-mm6l60 <arch} **Waiting for another run.** A run that must wait for another
+  run's write waits for it; when it has waited 10 seconds, it writes
+  nothing, prints a line to stderr saying the project's files are held by
+  another run, and exits 2. {#s-qt9vvj <arch} A run that ended, however it ended,
+  never makes a later run wait.
+* {#s-zb5ycj <arch} **Nothing left behind.** Once a run has exited, the only files it
+  has created or changed are the project files it wrote and files under
+  `tmp/idd/`.
+* {#s-rueqkl <arch} **One written form.** Every project file a subcommand writes is
+  JSON indented two spaces per level, a member written `"name": value`, and
+  ends with a newline, so that the full question digest appears as its `id`
+  in `idd/questions.json`.
+
+## Dependencies
+
+* {#p-tc5ji4 >specs/project-files.md} The files it creates, checks, reads and
+  records answers in.
+* {#p-88dl9g >specs/questions-page.md} The page it builds.

package/specs/project-files.md

@@ -0,0 +1,188 @@
+# Project files
+
+Statement ids: complete
+
+## Purpose
+
+The files on an adopting project's matching IDD branch that hold its shared
+questions, answers and pending answers, so sessions of any agent tool work
+from the same question list and recorded results, while each tool presents
+its own questionnaire.
+
+## His words
+
+> {#m-ec324x} RULING (CEO), 2026-11-10: “There should always be an
+> answer (the last one) which is: X. None of the above are right. Let me
+> explain: Also, by default, none of the answers should be selected.”
+
+> {#m-q2caxw} RULING (CEO), 2026-11-12, IDD question
+> `08a76cb8364300fab2aaf8345ba237d56cb66cafded6dc4143a7978193dc0fd7`:
+> “Should the question id hash include the reserved X option? A) Exclude it,
+> because it is added to older questions. B) Include it, because it can be
+> chosen.” His answer: “B”. His note: “Since it can be chosen, it should be
+> in the hash.”
+
+> {#m-tu5fn2} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04: "One
+> page per session or project. Start from
+> `~/.claude/templates/questions-page.html`. Copy it to the scratchpad,
+> replace `__TITLE__` with "<Project> Open Questions", and replace the
+> placeholder entry in `vaQuestion` with real questions."
+
+> {#m-90lcy5} From the same section: "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 }`."
+
+> {#m-polrzx} RULING (CEO) 2026-11-02 (Concord), on `concord.json`: "That is
+> weird. Concord.json should not use semantic hungarian tags. SH is really
+> limited to code."
+
+> {#m-edvy4l} RULING (CEO) 2026-11-04, q197. The question: "IDD: what do agent
+> tools other than Claude Code do? The new IDD package (interrogation-driven
+> development, in ~/@idd) puts every decision on a questions page like this
+> one. The page is a claude.ai artifact, so a Codex session cannot publish it
+> or read your answers. Example: a Codex session in AIOS needs to know
+> whether a new button saves on click or on Enter.
+> A) Codex writes the question into the project's question file and also
+> asks it in full in the terminal; it appears on the page the next time a
+> Claude Code session publishes it.
+> B) Codex asks in the terminal only, by the same writing rules, and records
+> your answer in the specs.
+> C) IDD gets a local page any tool can serve, with answers saved to a file
+> in the project; the claude.ai page is retired.
+> D) IDD is for Claude Code sessions only, for now." His answer, choosing no
+> option, with the note: "Each agent gets its own tool for interactive
+> questionnaires. The results should be captured in a local file so that
+> multiple agents can expand off of the same question list. For now, define
+> the claude approach, and leave open how other tools will solve it for
+> themselves (e.g. Codex, Gemini, etc.)"
+
+## Terms
+
+* {#d-wczec5 <m-tu5fn2@79447f9} **Page file** — `idd/page.json` at the root of an
+  adopting project's data worktree: the page's title and branch hash.
+* {#d-q6pb2e <m-tu5fn2@79447f9} **Question file** — `idd/questions.json` at the root
+  of that data worktree: every question presented with an agent tool's
+  questionnaire.
+* {#d-b4np1k <m-edvy4l@54198de} **Answer file** — `idd/answers.json` at the root of
+  that data worktree: the human's recorded answers.
+* {#d-z044ah <arch} **Pending answer file** — `idd/pending.json` at the root of
+  that data worktree: answers a session has not yet incorporated.
+## Shared by every agent tool
+
+* {#g-f1rxwm <m-edvy4l@54198de for=main,architect via=prompt} **One question list.** A
+  session of any agent tool takes its question ids from, and adds its
+  questions to, the project's one question file, and records and reads the
+  human's answers in the project's answer file; no agent tool keeps a
+  question list or an answer record of its own.
+* {#g-7pv35v <m-edvy4l@54198de,m-zbztp6@c44613a for=main,architect via=prompt} **Each tool its own
+  questionnaire.** How an agent tool puts the questions before the human and
+  collects his answers is that tool's own, and is specified in that tool's
+  guidance spec under `specs/guidance/`. IDD specifies Claude Code's
+  (`specs/guidance/claude-code.md`) and Codex's
+  (`specs/guidance/codex.md`).
+
+## The page file
+
+* {#s-f6ji64 <m-tu5fn2@79447f9,m-polrzx@d3b1d54} **Its members.** The page file holds one JSON
+  object with exactly three members: `title`, a non-empty string, as in
+  `"title": "AIOS Open Questions"`; `url`, the address the page is
+  published at, a non-empty string, or `null` while the page has never been
+  published; and `branchHash`, a lowercase, 64-character SHA-256 digest
+  identifying the source code branch whose questionnaire it holds.
+
+## The question file
+
+* {#s-rhzch5 <m-tu5fn2@79447f9,m-polrzx@d3b1d54} **An array.** The question file holds one JSON
+  array of questions, in the order they were presented to the human.
+* {#s-0yj34e <m-90lcy5@5b4a86e,m-polrzx@d3b1d54} **A question.** Each question is an object with
+  exactly the members `id`, `branchHash`, `title`, `body`, `options` and
+  `createdAt`. {#s-bjouc5 <arch,m-ec324x@c9504b3,m-q2caxw@e07030c} `id` is the lowercase,
+  64-character SHA-256 digest of the UTF-8 JSON serialization of
+  `[branchHash, title, body, options]`, with every option represented as
+  `[key, text, tag-or-empty-string]`, including the reserved final X option;
+  `branchHash` is the hash of the code branch where the question was first
+  created. A legacy question whose id predates including X retains its stored
+  id and is accepted under the prior formula; adding X for display does not
+  rewrite its identity. New questions with the same canonical content and
+  branch hash share one id, preventing duplicate questions. `createdAt` is
+  the ISO 8601 time the question was added.
+  {#s-s0obkh <m-90lcy5@5b4a86e} `title` and
+  `body` are non-empty strings. {#s-twjma0 <m-90lcy5@5b4a86e} `options` is an array of
+  two to four substantive options, optionally followed by the reserved final
+  option `{"key":"X","text":"None of the above are right. Let me explain:"}`.
+  {#s-wznig4 <m-ec324x@c9504b3,m-q2caxw@e07030c} A newly added question stores this reserved option
+  last; a legacy question without it remains valid and the viewer supplies it
+  when displaying the question. No other option may use key `X`.
+* {#s-0yp4n2 <m-90lcy5@5b4a86e,m-polrzx@d3b1d54} **An option.** Each option is an object with the
+  members `key`, a non-empty string no other option of its question holds,
+  and `text`, a non-empty string, and optionally `tag`, a non-empty string
+  drawn under the option's text; it has no other member.
+* {#s-fvhi3x <arch} **Bodies are text.** A body is plain text: backticks mark code
+  spans and a blank line separates paragraphs; HTML in a body is text, never
+  markup (`specs/questions-page.md`, What the page draws).
+
+## The answer file
+
+* {#s-hri503 <arch} **Its members.** The answer file holds one JSON object. Each
+  member's name is the id of a question in the active question file or
+  question history, and its value
+  is an object with exactly the members `choice`, the key of the option he
+  chose, a string, or `""` when he chose none; `note`, his note, a string,
+  `""` when he wrote none; and `time`, the time he saved the answer, an ISO
+  8601 string.
+* {#s-zrui8r <arch} **One accepted answer per question.** The answer file holds at
+  most one accepted answer per question. An accepted answer is never
+  replaced; a later submission is rejected and its submitter is shown the
+  accepted answer (`specs/idd-page.md`, answer; `specs/hosted-questionnaire.md`).
+* {#s-r40lfj <arch} **Absent means none recorded.** A project with no answer file
+  has no recorded answer; the first answer recorded creates it.
+
+## The question history file
+
+* {#s-g7mf6n <arch} `idd/history.json` holds a JSON array. Each entry has exactly
+  `questionId`, a full `question` snapshot of the removed question,
+  `replacedBy`, the id of its replacement, and `time`, the ISO 8601 time
+  it was removed from the active list. The snapshot's `id` equals
+  `questionId`.
+* {#s-0fiha8 <arch} An answer to a question in history remains in
+  `idd/answers.json` under its original `questionId`; it is not deleted or
+  rewritten during reconciliation.
+
+## The pending answer file
+
+* {#s-0ra8q5 <arch} **Its members.** The pending answer file holds one JSON object. Each
+  member's name is the id of a question in the active question file or
+  question history, and its value
+  has the same `choice`, `note` and `time` members and forms as an answer
+  file entry.
+* {#s-ejxfi4 <arch} **A pending answer is recorded.** Each member of the pending answer file
+  has an entry with the same id, choice, note and time in the answer file.
+* {#s-u52jq6 <arch} **Absent means none pending.** A project with no pending answer file has
+  no locally pending answer; recording the first answer creates it.
+
+## Thoughts and observations
+
+* {#s-61lmfb <arch} `idd/thoughts.json` holds one JSON array of thoughts in append
+  order. A thought has exactly `id`, `branchHash`, `text`, and `createdAt`.
+  `id` is a lowercase, 64-character SHA-256 digest of the UTF-8 JSON
+  serialization of `[branchHash, createdAt, text]`. `branchHash` identifies
+  the code branch, `text` is the non-empty plain-text statement, and
+  `createdAt` is its unique ISO 8601 submission time. Thoughts are separate from questions,
+  answers, conflicts and their counts.
+* {#s-bv05e2 <arch} A thought is immutable after submission. Repeating identical text
+  creates a distinct thought with a distinct id; appending never replaces or
+  merges an existing thought.
+* {#s-axz9ts <arch} If `idd/thoughts.json` is absent, the project has no submitted
+  thoughts. The first submission creates it.
+
+## Where the built page goes
+
+* {#s-9e2f7d <arch} **Built under `tmp/`.** `idd build` writes the page to
+  `tmp/idd/page.html` under the data worktree root; it is the file the session
+  publishes, and is never committed.
+
+## Dependencies
+
+* {#p-8khzfb >specs/idd-page.md} The command that creates, checks and builds from
+  these files.