@debonet/idd 0.0.0-stage → 0.1.0

package/specs/adoption.md

@@ -0,0 +1,133 @@
+# Adopting IDD
+
+Statement ids: complete
+
+## Purpose
+
+What a project does to use interrogation-driven development, so that every
+new session in it finds the shared question and answer files and uses its
+tool's questionnaire with no further instruction.
+
+## His words
+
+> {#m-f2so64} RULING (CEO) 2026-11-04: "We should consolidate all of the best
+> practices/instructions/code for this interrogation-driven-development into
+> a separate package so that many projects can use it. Stick it in ~/@idd and
+> use the ConcordSTD framework. Your goal should be a package that can be
+> included in AGENTS.md that makes a new session use the questionaire
+> framework for pending questions"
+
+> {#m-1g0dvt} RULING (CEO) 2026-11-04, q198. The question: "IDD: every
+> project, or only projects that opt in? Your global Claude Code instructions
+> already tell every session in every project to use a questions page. IDD
+> is opted into by one line in a project's AGENTS.md. Example: a session in a
+> project whose AGENTS.md lacks that line needs a decision from you.
+> A) The global section becomes one pointer to IDD, so every project uses
+> it.
+> B) The global section is deleted; only projects with the IDD line use the
+> page." His answer: B, with the note: "Just like Concord. Each project
+> should specify whether or not they want to use each framework."
+
+> {#m-o27vtp} RULING (CEO) 2026-11-04, q202 (Concord). The question: "Is
+> ConcordSTC used by every project, or only by projects that say so?" His
+> answer: A, only projects whose `AGENTS.md` says so, with the note: "The
+> global claude should be set to ask if the user has not specified."
+
+> {#m-wzc76j} RULING (CEO), 2026-11-06: "idd-merge-hook already uses node, so we have a node requirement. Just use npm."
+
+> {#m-be8ix1} RULING (CEO), 2026-11-06: "the agent should open it for the
+> user, or at least provide a link (frequently, because the page gets closed
+> sometimes)"
+
+> {#m-yqrzks} RULING (CEO), 2026-11-06, on keeping IDD data on branch-specific
+> IDD branches and using a data worktree: "Agreed. Or do we provide a skill
+> or direct cut and paste agent instructions?"
+
+> {#m-0f7o0n} RULING (CEO), 2026-11-08: “So the instructions need to say
+> to install the idd app on your project.”
+
+## Terms
+
+* {#d-ihn44p <m-f2so64@36c95e2} **Adopting project** — a project whose root `AGENTS.md`
+  holds the IDD line.
+* {#d-vl5tvf <m-f2so64@36c95e2} **IDD line** — the one line that includes IDD in an
+  adopting project's `AGENTS.md`.
+
+## The line
+
+* {#g-4oj61n <m-wzc76j@812ba8b for=main,architect via=prompt} **Install the npm package.**
+  Add the public `@debonet/idd` package to the adopting project's npm
+  dependencies with `npm install @debonet/idd`.
+* {#g-8m8doy <m-0f7o0n@0780303 for=main,architect via=prompt} **Install the GitHub App on
+  the repository.** Before expecting the viewer to discover a project's
+  questionnaire, include that repository in an installation of the IDD
+  GitHub App.
+* {#g-6jkb7v <m-f2so64@36c95e2,m-wzc76j@812ba8b for=main,architect via=prompt} **One short copy-paste
+  instruction.** An adopting project's root `AGENTS.md` includes this text:
+
+  ```text
+  This project uses IDD. Before other work, read the installed package's instructions at the path printed by `node -p "require.resolve('@debonet/idd/INSTRUCTIONS.md')"`. If IDD is not installed, run `npm install @debonet/idd` first.
+  ```
+
+* {#g-dpmdxo <m-yqrzks@7d9b3bc for=main,architect via=prompt} **Tool instructions use native
+  questionnaires.** The shared package documents the project workflow;
+  tool-specific guidance supplies only the mechanics of that agent's native
+  questionnaire and browser. A concise tool-specific instruction is
+  available for tools without skill support.
+* {#g-0rz7vz <m-1g0dvt@dfb4edf for=main,architect via=prompt} **Per project, by its own
+  line.** A project uses IDD only when its own root `AGENTS.md` holds the
+  IDD line, as a project uses ConcordSTC only when it declares it; a
+  session in a project without the line follows none of IDD's rules.
+* {#g-t4154n <m-1g0dvt@dfb4edf for=main,architect via=prompt} **Never for every project
+  at once.** IDD's rules, and any pointer to them, are never written into an
+  instruction file that sessions in every project read, as a user's global
+  `~/.claude/CLAUDE.md`.
+* {#g-bl9a8z <m-o27vtp@5d340a6 for=main,architect via=prompt} **Ask when the project says
+  neither.** A user's global instruction file may hold one line telling a
+  session to ask the human whether to use a framework (IDD, ConcordSTC) in a
+  project whose root `AGENTS.md` says neither that it uses it nor that it
+  does not. That line holds none of IDD's rules and no pointer to them, so
+  Never for every project at once does not bar it.
+* {#g-gkcg3x <m-o27vtp@5d340a6 for=main via=prompt} **His answer is written into the
+  project.** When he answers yes to IDD, the session writes the IDD line into
+  the project's root `AGENTS.md`; when he answers no, it writes there, on a
+  line of its own, exactly `This project does not use IDD.`; either line
+  means the project is never asked again. Until he answers, the session
+  follows none of IDD's rules.
+* {#g-sbu6iu <arch for=main via=prompt} **Asked in the terminal.** The question
+  whether to use IDD is asked in the terminal, since a project that has not
+  adopted IDD has no questions page.
+* {#g-0pni9q <m-f2so64@36c95e2 for=main,architect via=prompt} **Nothing copied.** An
+  adopting project's rules files and specs hold no copy of IDD's rules;
+  they hold the IDD line and the project's own standing principles, which
+  IDD's checks read (`specs/guidance/writing-questions.md`, Before it is
+  asked).
+* {#g-ze1gq8 <m-f2so64@36c95e2 for=main via=prompt} **Its files.** An adopting project
+  holds its page file and question file, and its answer and pending answer
+  files once answers are recorded (`specs/project-files.md`); the first session that finds the
+  page file and question file absent creates them
+  (`specs/guidance/session.md`, Starting a session).
+
+## IDD's own files, read from other projects
+
+* {#g-suwilu <m-f2so64@36c95e2 for=main,architect via=prompt} **Tool mechanics apart.**
+  The installed IDD guidance holds the shared project workflow; a skill may
+  add only the mechanics of one agent tool's questionnaire or browser.
+
+## Migrating a project with an existing page
+
+* {#g-ze1mh5 <m-f2so64@36c95e2 for=main via=prompt} **Follow the migration note.** A
+  project that already has a questions page made from the older template,
+  or rules of its own on questions for the human, adopts IDD by
+  `~/@idd/docs/existing-page-migration.md`, which keeps the page's address
+  and every saved answer.
+
+* {#s-fm0j9h <m-0f7o0n@0780303} The package instructions tell adopters to
+  install the IDD GitHub App on each project repository and link to its
+  installation page.
+
+## Dependencies
+
+* {#p-e3n6ry >specs/project-files.md} The IDD data worktree and files an adopting project holds.
+* {#p-zrzy09 >specs/guidance/session.md} What a session in an adopting project
+  does first.

package/specs/build.md

@@ -0,0 +1,176 @@
+# Build, Layout, and Run
+
+Statement ids: complete
+
+## Purpose
+
+IDD's toolchain, layout, dependencies and the named commands every fixer
+invokes; no fixer runs `node`, `jest` or an ad-hoc pipeline outside these.
+
+## Toolchain
+
+* {#g-94bsyg <arch for=main,architect,fixer via=prompt} Use Node >= 20 and plain
+  JavaScript with CommonJS modules (`require` / `module.exports`) for the
+  command and its modules; do not add TypeScript, ESM or a bundler.
+* {#g-d4bbao <arch for=main,architect,fixer via=prompt} Keep Jest at major version
+  29, and test the page in a DOM emulated by `jsdom`, with the page's store
+  and comment services replaced by fakes the test controls.
+* {#g-kv15zk <arch for=main,architect,fixer via=prompt} Keep this an
+  interpreted-language project. Developers install its dependencies with
+  `npm install`; adopters add the public package to their project with
+  `npm install @debonet/idd`.
+
+## Project Layout
+
+```
+~/@idd
+  package.json               agent package metadata and project scripts
+  package-lock.json          committed
+  README.md
+  INSTRUCTIONS.md            canonical agent workflow installed with npm
+  AGENTS.md                  what a session in an adopting project follows
+                             (specs/adoption.md)
+  CLAUDE.md                  imports AGENTS.md for sessions in this repository
+  concord.json               IDD's Concord declaration
+  observations.md            IDD's observations
+  idd/                       IDD's own page, question, answer and pending
+                             answer files (specs/project-files.md)
+  bin/                       the command: idd
+                             and the merge-hook installer
+  scripts/                   the modules behind the command
+  templates/                 the questions page template
+  .githooks/                 IDD and Concord Git hooks
+  web/                       Cloud Run viewer, OAuth callback and workspace package
+  web/package.json           hosted service runtime dependencies
+  Dockerfile                 Cloud Run container
+  docs/                      migration notes for adopting projects
+  specs/                     IDD's specs; specs/guidance/ the session rules
+  test/                      IDD's jest tests
+  .githooks/pre-commit       IDD's pre-commit hook (Concord's gate)
+  tmp/                       scratch and fixture trees (gitignored)
+```
+
+* {#g-dt9a19 <arch for=main,architect,fixer via=prompt} Keep `node_modules/` and
+  `tmp/` gitignored.
+
+## Hosted viewer
+
+* {#g-tskk4b <arch for=main,architect,fixer via=prompt} Keep the hosted viewer in
+  `web/` and implement its HTTP service with Node's built-in modules; the
+  service listens on `process.env.PORT` and serves files from `web/`.
+* {#g-b9fjxa <arch for=main,architect,fixer via=prompt} The service requires
+  `GITHUB_APP_CLIENT_ID`, `GITHUB_APP_CLIENT_SECRET`, and
+  `IDD_OAUTH_STATE_SECRET`, and the public origin in `IDD_PUBLIC_URL`;
+  production supplies the client secret and state secret from Google Secret
+  Manager.
+* {#g-xutz05 <arch for=main,architect,fixer via=prompt} The service uses
+  `@google-cloud/firestore` to retain MCP event subscriptions across Cloud Run
+  restarts; production supplies a Firestore database and grants the Cloud Run
+  service account Firestore read/write access.
+* {#g-u68buh <arch for=main,architect,fixer via=prompt} Keep
+  `@google-cloud/firestore` and `standardwebhooks` in the hosted workspace's
+  runtime dependencies and
+  keep every external request used by MCP event delivery injectable for
+  hermetic tests.
+* {#g-hq4lnx <arch for=main,architect,fixer via=prompt} Run the service locally
+  with `npm start`; the root `Dockerfile` installs runtime dependencies from
+  `package-lock.json` before starting the Cloud Run service.
+* {#g-otococ <arch for=main,architect,fixer via=prompt} Keep the GitHub App
+  configuration and Cloud Run deployment steps in `docs/hosted-viewer.md`;
+  do not commit credentials.
+* {#s-gu3zl2 <arch} `npm run deploy` runs `scripts/deploy.js` to deploy the
+  root Dockerfile to Cloud Run service `idd-service` in project `idd-platform`
+  and region `us-east4`, with one maximum instance and concurrency 1000.
+  It uses the authenticated `gcloud` CLI and leaves the service's existing
+  environment variables, secret bindings, and access policy in place.
+* {#s-emm7r0 <arch} The deployment script reports a missing `gcloud`
+  executable or a failed deployment with a nonzero exit status and does not
+  print credentials or secret values.
+* {#g-hfipex <arch for=main,architect,fixer via=prompt} The hosted MCP endpoint is
+  `/mcp`; implement its Streamable HTTP tools and events protocol with Node
+  built-ins and use `standardwebhooks` for signed callbacks. Keep callback
+  network validation, signing, retries and subscription storage behind
+  modules with hermetic tests.
+* {#g-ami8kh <arch for=main,architect,fixer via=prompt} Keep the canonical
+  adopter workflow in root `INSTRUCTIONS.md`; `idd guide` prints that
+  file verbatim, and npm installs it with the package.
+* {#g-w20g67 <arch for=main,architect,fixer via=prompt} Expose `idd-merge-hook` from
+  `bin/idd-merge-hook`; its installer writes hooks to the adopting project's
+  `.githooks/` and configures Git to run them; each hook calls the installed
+  package with `npm exec -- idd-merge-hook` (`specs/idd-merge-hook.md`).
+
+## The command
+
+* {#s-cg2j10 <arch} `bin/idd` is executable, has no file extension, and opens
+  with the line `#!/usr/bin/env node`, so it runs by its path from any
+  working directory (`specs/idd-page.md`).
+* {#s-vfgnzf <arch} It loads every npm module it uses from IDD's own
+  dependencies, never from the adopting project's.
+
+## Packages and Dependencies
+
+> {#m-47zf2p} RULING (CEO), 2026-11-12: “we need two different things:
+> 1) the idd back end, which runs in interrogation.dev
+> 2) the idd instructions and tools which live in npm”
+
+* {#s-nifxq3 <m-47zf2p@5c93368} The published npm package contains the agent command, its required modules,
+  templates, specifications and canonical instructions; it excludes the hosted
+  web application, its runtime dependencies, Dockerfile and Cloud Run deployment
+  script. The hosted service has a separate workspace manifest and is deployed
+  from the IDD repository; it is reached at `https://interrogation.dev`.
+* {#g-aiemo2 <arch for=main,architect,fixer via=prompt} Publish the package
+  publicly as `@debonet/idd`, exposing `idd` and `idd-merge-hook` from
+  their matching files under `bin/`, so adopters can install it from npm.
+* {#g-7o7fu3 <arch for=main,architect,fixer via=prompt} Keep every module the
+  command loads in `dependencies`, and Jest `^29`, `jsdom` and other
+  test-only modules in `devDependencies`.
+* {#g-haeoa5 <arch for=main,architect,fixer via=prompt} Set the scripts: `"start"`
+  to `"node web/server.js"`; `"test"` to `"jest"`; `"spec-map"` to
+  `"$HOME/@concord/bin/spec-map"`;
+  `"spec-coverage"` to `"$HOME/@concord/bin/spec-coverage"`;
+  `"hook-install"` to `"$HOME/@concord/bin/concord-hook install"`; each
+  passes its arguments through unchanged and in order.
+* {#g-5phruy <arch for=main,architect,fixer via=prompt} Set Jest's root to
+  `<rootDir>/test`.
+
+## Build and Test
+
+* {#g-2avaz9 <arch for=main,architect,fixer via=prompt} Install dependencies with
+  `npm install --cache ./tmp/npm-cache` at `~/@idd`.
+* {#g-6gajca <arch for=main,architect,fixer via=prompt} Run the suite with
+  `npm test` at `~/@idd`; add tests under `test/**/*.test.js`.
+* {#g-va67x1 <arch for=main,architect,fixer via=prompt} Check the specs and links
+  with `npm run spec-map [-- <arguments>]` (assign: `npm run spec-map --
+  --assign`; hash table: `npm run --silent spec-map -- --hashes`); measure
+  coverage with `npm run spec-coverage [-- <arguments>]` on demand, never as
+  part of `npm test`.
+* {#g-fj4oz8 <arch for=main,architect,fixer via=prompt} Keep commits gated by
+  `.githooks/pre-commit`, installed in each clone with
+  `npm run hook-install` once `npm run spec-map -- --gate` passes over the
+  tree.
+
+## IDD's own settings
+
+* {#g-g10hm9 <arch for=main,architect,fixer via=prompt} Declare in `concord.json`
+  IDD's name `IDD`, its one suite `root` over `test`, its languages
+  `javascript`, `html` and `css`, its read directories `bin`, `scripts`,
+  `templates`, `test` and `web`, the ignored directory `node_modules`, the record
+  file `test/interactive-passes.jsonl`, the observations file
+  `observations.md`, the rules files `AGENTS.md` and `CLAUDE.md`, and one
+  coverage run at the root over `bin` and `scripts` with the review file
+  `spec-coverage-review.md`; include `web` in the coverage sources and keep
+  those values aligned with this spec.
+
+## Hermeticity
+
+* {#g-qq5g54 <arch for=fixer via=prompt} Keep tests hermetic: do not write outside
+  the project's `tmp/`, read files outside the project, open network
+  connections or run `git`; build each fixture project under `tmp/` and run
+  the command with that fixture as its working directory.
+* {#g-grm59h <arch for=fixer via=prompt} Tests do not read files under `specs/`
+  or `idd/`; build the files a case needs in its fixture.
+
+## Error Handling
+
+* {#s-ddc95k <arch} The command's errors reach its caller as its exit code and
+  stderr lines, as `specs/idd-page.md` gives them.

package/specs/guidance/agent-merge.md

@@ -0,0 +1,63 @@
+# Guidance: IDD-aware branch merges
+
+## His words
+
+> {#m-mc5vkw} RULING (CEO) 2026-11-05: “So the merge for idd can
+> involve creating new questions and deleting the duplicates and then doing
+> the work required to implement the decision.”
+
+## Merge process
+
+* {#g-rt5s9p <m-mc5vkw@076749d for=main,architect,fixer via=prompt} Before an agent completes a code-branch merge, it
+  compares the source and target IDD branches and reviews questions and
+  answers that may describe the same decision.
+* {#g-k07zt5 <arch for=main,architect,fixer via=prompt} Exact duplicate questions are consolidated into one active
+  question; earlier question and answer records remain in the IDD history
+  and point to the consolidated question.
+* {#g-8ux1b9 <arch for=main,architect,fixer via=prompt} When the same question id has
+  different accepted answers on the source and target IDD branches, the
+  target answer remains accepted and the source answer is recorded as a
+  rejected answer conflict with its submitting GitHub user.
+* {#g-9p1iiw <arch for=main,architect,fixer via=prompt} When questions describe the same decision but their answers
+  do not settle it, the agent adds one clarifying question to the target
+  IDD branch, then waits for its answer before doing the implementation
+  work and completing the code-branch merge.
+* {#g-wjcjlc <arch for=main,architect,fixer via=prompt} When a follow-up question makes an earlier question obsolete,
+  the agent archives it with `npm exec -- idd archive <old-id> <follow-up-id>`;
+  its full question record and answer remain in history.
+* {#g-y1uuo7 <arch for=main,architect,fixer via=prompt} During reconciliation, keep the target
+  page's branch hash and each retained question's origin branch hash; a new
+  clarifying question gets the target branch hash.
+* {#g-gn96qw <arch for=main,architect,fixer via=prompt} An agent may use this process without ConcordSTC.
+
+## Git integration
+
+* {#g-3fmwel <arch for=main,architect,fixer via=prompt} Every code-branch merge uses
+  `git merge --no-ff` so Git runs the IDD pre-merge hook.
+* {#g-tu3fn2 <arch for=main,architect,fixer via=prompt} Each clone installs the IDD hooks
+  with `npm exec -- idd-merge-hook install`; the project's `.githooks/` files
+  are committed, and the session checks installation before merging.
+* {#g-1b9rc2 <arch for=main,architect,fixer via=prompt} The committed `pre-merge-commit` hook asks the IDD merge
+  command to check for unresolved questionnaire conflicts before Git
+  creates a merge commit.
+* {#g-qzhgum <arch for=main,architect,fixer via=prompt} When Git first stops for code conflicts, the `pre-commit`
+  hook performs the same check before the agent commits the resolved merge.
+* {#g-uhed71 <arch for=main,architect,fixer via=prompt} A hook that finds unresolved IDD work exits unsuccessfully and
+  prints the source and target branches and the IDD reconciliation
+  command for the agent to continue the process.
+* {#g-qi307t <arch for=main,architect,fixer via=prompt} When the agent finds related questions that do
+  not require a clarifying answer, it records its review with
+  `npm exec -- idd-merge-hook reviewed`; the confirmation is tied to the current source
+  and target commits and cannot authorize a later merge state. The source IDD
+  branch must already be merged into and reconciled on the target IDD branch.
+* {#g-xvyj2c <arch for=main,architect,fixer via=prompt} The agent does not record a review while
+  duplicate, obsolete or conflicting questions remain unresolved, or while
+  a clarifying answer or its implementation is pending.
+* {#g-lwnark <arch for=main,architect,fixer via=prompt} Before completing the code merge, the agent merges the
+  source IDD branch into the target IDD branch, reconciles and commits the
+  result, and pushes the target IDD branch. The `post-merge` hook verifies
+  that the reviewed IDD state remains in place and clears the review record.
+
+## Dependencies
+
+* {#p-afnv8o >specs/hosted-questionnaire.md} The IDD branch data and its reconciliation rules.

package/specs/guidance/answers.md

@@ -0,0 +1,108 @@
+# Guidance: reading and recording the human's answers
+
+Statement ids: complete
+
+## Purpose
+
+How the session reads an answer from the page, replies to it, and records
+it as a ruling where the project's agents will find it. Each `[o-…]`
+citation names an entry of `~/@idd/observations.md`.
+
+## His words
+
+> {#m-s43qto} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04:
+> "**Handling my answers:** when a comment arrives (an auto-reply or "sent to
+> Claude"), read the thread, act on the answer, reply in the thread only if
+> the auto-reply didn't already cover it, resolve the thread, and write one
+> line in the session. If my answer includes a note, the note refines the
+> option; read both together. If the note leaves the choice ambiguous, add a
+> follow-up question to the page."
+
+> {#m-yo3wtj} RULING (CEO) (AIOS), after a pointer answer ("I answered this
+> in 97") was read as one of the question's options: "NO. This is not what I
+> said."
+
+> {#m-gcnebt} RULING (CEO) (AIOS), after a note naming a tab was re-asked
+> as ambiguous: "OMG. You're making this complicated."
+
+> {#m-bbat3q} RULING (CEO) 2026-09-30 (AIOS), asked back about slips in his
+> answer: "Its frustrating repeating myself multiple times on the same topic
+> ... you learn to listen the first time"
+
+> {#m-mbhrcu} RULING (CEO) (AIOS) 2026-09-28: "why are you putting my
+> decisions into claude.md instead of the architect putting them into spec/
+> files?"; 2026-10-01: "why are you copying all of my sentences to a cdeo
+> file?"; 2026-10-08: "Those are product specifications. They belong in the
+> appropriate spec/ file(s)"
+
+> {#m-a7o9fh} RULING (CEO) (AIOS), after a gloss of his ruling added a
+> limit: "I never said a parent only limits its direct children."
+
+## When an answer arrives
+
+* {#g-y2queb <m-s43qto@adbad2e for=main via=prompt} **The thread.** When a page comment
+  arrives, an automatic reply's notice included, or he says "done" or
+  "updated": read the thread, act on the answer, reply in the thread only if
+  the automatic reply did not already cover it, resolve the thread, and
+  write one line in the session.
+* {#g-c7bap6 <m-s43qto@adbad2e for=main via=prompt} **The automatic reply speaks for the
+  session.** Compare every automatic reply with the chosen option's own text
+  in the question file; where it assumed, defaulted or promised anything the
+  option does not say, reply with the correction before resolving.
+  [o-8rmpk8]
+* {#g-1499zt <arch for=main via=prompt} **A note cut off mid-sentence.** When a
+  note ends mid-sentence, read the question's `answers/` document for the
+  latest text before acting, and act only on a note that ends cleanly.
+
+## Reading an answer
+
+* {#g-btj8e4 <m-s43qto@adbad2e for=main via=prompt} **The note refines the option.**
+  Read the chosen option and the note together; when the note leaves the
+  choice ambiguous, add and present a follow-up with the current tool's
+  questionnaire (`specs/guidance/session.md`).
+* {#g-jigpd2 <m-yo3wtj@e906838 for=main via=prompt} **A pointer is not an option.** An
+  answer that points elsewhere ("I answered this in 97"), or a note with no
+  option, is never mapped onto one of the question's options; unless the
+  pointed-to answer's options literally cover this question's case, the
+  question goes back through the current tool's questionnaire as a new
+  question quoting his note, and the
+  thread reply says so. No reading of it is relayed to an architect.
+  [o-65eyze]
+* {#g-7h9l11 <m-gcnebt@f88839e for=main via=prompt} **His nouns name what he sees.**
+  A noun in his note that names a visible part of the thing the question
+  shows, a tab, a view or a field, means that part; read it so before
+  calling the note ambiguous. [o-8qre78]
+* {#g-0wfhwz <m-bbat3q@8bd203e for=main via=prompt} **A typo is read as its intent.** An
+  evident typo in his answer is read as its evident intent when exactly one
+  reading fits his earlier rulings and the project's vocabulary: act on it
+  and mention the correction in one clause; ask only when two readings
+  would build different things.
+
+## Recording a ruling
+
+* {#g-q5375r <m-mbhrcu@1ffe48c for=main,architect via=prompt} **Into the specs, through the
+  architect.** His answer reaches the project's rules only through the spec
+  that owns its subject: the main thread pastes his answer and the question
+  it answered verbatim into an architect's brief, and the architect records
+  them in that spec as a motive line, `RULING (CEO) <date>, q<N>:` and his
+  words, then writes each conclusion as its own statement rooted in it. His
+  decision is never written into a rules file or a scratch file.
+* {#g-zvulrj <arch for=main,architect via=prompt} **Dated from the clock.** The date
+  on a recorded ruling is taken from `date` run in the same turn, never from
+  memory.
+* {#g-p37e2s <m-a7o9fh@11c5476 for=main,architect via=prompt} **A gloss adds nothing.**
+  A sentence that restates a ruling of his carries his quoted words beside
+  it and adds no limit he did not state; before relaying a limit on a
+  ruling, find it in his words (`grep -rn "<the limit's words>" specs/ |
+  grep "{#m-"`) or do not relay it. [o-a1t5mg]
+* {#g-7x0l5s <arch for=main via=prompt} **Citing his rulings.** Before saying
+  something rests on a ruling of his, find his quoted words and read the
+  question they answered; a ruling that cannot be found is an architect's
+  decision and goes to him as a question, never as a default.
+
+## Dependencies
+
+* {#p-hd5c3l >specs/questions-page.md} The Done comment and the answer documents.
+* {#p-nbpmws >specs/guidance/session.md} The pending queue an incorporated answer
+  is cleared from.

package/specs/guidance/claude-code.md

@@ -0,0 +1,76 @@
+# Guidance: the questions page in Claude Code
+
+Statement ids: complete
+
+## Purpose
+
+The Claude Code tools that carry out the steps of
+`specs/guidance/session.md` and `specs/guidance/answers.md`: publishing the
+page, reading and clearing its store, recording its answers in the
+project's answer file, and handling its comment threads.
+Each `[o-…]` citation names an entry of `~/@idd/observations.md`.
+
+## His words
+
+> {#m-ceg9ie} From his instructions file `~/.claude/CLAUDE.md`, section
+> "Questions for me go on a web questions page", as read 2026-11-04:
+> "**Publish with the Artifact tool, with `capabilities: {comments: {}, db:
+> {}, user: {}}`.**"
+
+> {#m-p8am7s} From the same section: "republish to the same URL, and open the
+> page in my local Chrome (`mcp__claude-in-chrome__navigate`)."
+
+> {#m-2nhxvl} From the same section: "**If my answers stop reaching you**
+> (I say "updated", or a notice says a comment is awaiting a reply), read the
+> page's comments yourself with `ArtifactComments` action "comments" and act
+> on every comment of mine marked "sent to you". Do this also before going
+> idle while questions are open. Auto mode's permission check can block the
+> automatic reply that would have woken you; the answer still sits in the
+> thread."
+
+## Publishing
+
+* {#g-g4nbtw <m-ceg9ie@e62db2e for=main via=prompt} **Publish the built page.** Publish
+  `tmp/idd/page.html` with the Artifact tool and the capabilities `comments`,
+  `db` and `user`. On the first publish, write the address the tool returns
+  into the page file's `url`; every later publish updates the artifact at
+  that address, never a new one.
+* {#g-k3cqou <m-p8am7s@e496a8d for=main via=prompt} **Open it for him.** After every
+  publish, open the page's `url` in his local Chrome with
+  `mcp__claude-in-chrome__navigate`, screenshot the new card, and check its
+  options are drawn.
+
+## The store
+
+* {#g-x76kn8 <arch for=main via=prompt} **Pending answers.** List the page's
+  pending answers with ArtifactData `list` on `pending`; read one with
+  `get` on `pending/<id>`, noting its version; clear it with `delete` on
+  `pending/<id>` pinned with `if_version` to that version.
+* {#g-2jje15 <arch for=main via=prompt} **Saved answers.** Read a saved answer
+  with ArtifactData `get` on `answers/<id>`; its `sChoice` is the chosen
+  option's key and its `sNote` his note (`specs/questions-page.md`, API).
+* {#g-oauw82 <arch for=main via=prompt} **Recording an answer.** The page's
+  store is where his answers reach the session, and the answer file is
+  their record. To record a pending answer, read `answers/<id>` with
+  ArtifactData `get` and pass its value, the object holding `sChoice`,
+  `sNote` and `dtm`, on stdin to `npm exec -- idd answer <id>` through
+  a heredoc with a quoted delimiter, so his note reaches it unchanged; it
+  must exit 0 before the answer is acted on.
+* {#g-u09697 <arch for=main via=prompt} **The local queue.** `idd answer` also records
+  each page answer in `idd/pending.json`. After incorporating it, clear the
+  local entry with `idd clear-pending <id> <time>`, using the `dtm`
+  just recorded. At session start, also act on local pending answers that
+  have no matching page-store entry, as `specs/guidance/session.md` gives.
+
+## Comment threads
+
+* {#g-ckcyd7 <arch for=main via=prompt} **On every automatic-reply notice.** On an
+  `artifact-auto-react` notice, read the thread with ArtifactComments,
+  compare the reply with the option's text (`grep -n -A8 '"id": "q<N>"'
+  idd/questions.json`), reply with any correction, then resolve it.
+  [o-8rmpk8]
+* {#g-liax1o <m-2nhxvl@6923e6a for=main via=prompt} **When answers stop reaching the
+  session.** When he says "updated", when a notice says a comment is
+  awaiting a reply, and before going idle while questions are open, read
+  the page's comments with ArtifactComments action `comments` and act on
+  every comment of his marked "sent to you".

package/specs/guidance/codex.md

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