@debonet/idd 0.0.0-stage → 0.1.1

package/INSTRUCTIONS.md

@@ -0,0 +1,159 @@
+# IDD instructions for coding agents
+
+<!-- @implements g-mfqz8n@63b06e1 -->
+
+This project uses IDD when its `AGENTS.md` says so. The npm package supplies
+the agent workflow and commands. The hosted questionnaire runs separately at
+`https://interrogation.dev`; installing the npm package does not install or
+run the web application. Each tool uses its native questionnaire.
+
+## Opt in a project
+
+Install IDD in the project with `npm install @debonet/idd`. Add this short
+instruction to its root `AGENTS.md`:
+
+```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.
+```
+
+Before expecting the viewer to discover a questionnaire, install the IDD GitHub App on each project repository. [Add the repository to the IDD app
+installation](https://github.com/apps/interrogation-driven-development/installations/new)
+and grant it access to that repository.
+
+## Start a session
+
+1. Identify the checked-out code branch and matching `idd-<branch>` branch.
+2. Open or create a separate Git worktree for that IDD branch under the code
+   checkout's `tmp/` directory. Keep the questionnaire files out of the code
+   branch. A branch based on another code branch starts from that parent's
+   IDD branch so the data histories can merge.
+3. Fetch the latest IDD branch before reading its questions or answers. Run
+   `npm exec -- idd` from the data worktree for every questionnaire
+   command.
+4. Read its pending answers and incorporate those before the task.
+5. Run `npm exec -- idd thoughts` and review the project's submitted
+   thoughts in creation order. Work on a note when it applies and has not
+   already been addressed. Ask through the usual IDD question flow when a
+   note needs a decision. Leave submitted notes in the shared log.
+6. Before incorporating an answer or acting on a thought or conflict, claim
+   that item with `npm exec -- idd claim <answer|thought|conflict>
+   <item-id> <session-id>`. Commit and push `idd/claims.json` before starting
+   the work. If the push is rejected, sync and inspect the branch; proceed
+   only if this session owns the claim. Release it with
+   `npm exec -- idd release <kind> <item-id> <session-id>` after the work is
+   incorporated, then commit and push the release.
+
+For a project's first IDD branch, get its numeric GitHub repository id and
+run `npm exec -- idd branch-hash <repository-id>
+refs/heads/<code-branch>`. Create an orphan data branch named
+`idd-<code-branch>`, then run `npm exec -- idd init "<Project> Open
+Questions" <printed-hash>` from that worktree. Commit and push the `idd/`
+files to the same GitHub repository. For a new code branch with a parent,
+create its IDD branch from the parent's IDD branch and set the page's branch
+hash to the new code branch hash; keep inherited question hashes unchanged.
+
+## Ask and publish a question
+
+Write a complete, self-contained question with a short title, enough context
+to decide without looking elsewhere, a concrete example, and two to four clear
+options. Do not use terms the model invented in private reasoning unless they
+have been discussed with the user. Ask only about choices that matter to the
+product or change what the user experiences; decide internal implementation
+details without asking when they make no product difference. Describe the
+choices in terms of what the user does and can observe, not hidden
+implementation details. Add it with
+`npm exec -- idd add`, using one JSON object on stdin with `title`,
+`body` and `options`. Use the question id it prints. Present the question
+with the current tool's native questionnaire when available. Commit and push
+the changed IDD files to the matching `idd-<branch>` branch.
+
+Get a direct viewer URL with
+`npm exec -- idd viewer-url <owner/repository> <code-branch>`. Open it
+when the tool can open a browser and include the link in the same update.
+Repeat the link in progress updates while questions remain unanswered so it
+is easy to reopen the page. Anyone with repository read access can view the
+questionnaire; submitting an answer requires repository write access.
+
+In Codex, present the question with `functions.request_user_input_async`:
+put the title and body together in the question title, and pass each option
+as a choice string beginning with its key. Save the returned choice and note
+with `npm exec -- idd answer <question-id>` before acting on it. The
+Codex-specific details are in `specs/guidance/codex.md` in this package.
+
+## Receive an answer
+
+When a person answers through the hosted page, run
+`npm exec -- idd wait <question-id>` from a clean data worktree. It
+waits for the hosted viewer's push event, checks the remote IDD branch when
+an event arrives, fast-forwards the local worktree when it changes, records
+the answer as pending and prints it as JSON. If push delivery is unavailable
+or the event stream disconnects, it checks the branch every 30 seconds by
+default. Continue work only after incorporating that answer. If the tool's
+native questionnaire returns the answer directly, record it with
+`npm exec -- idd answer <question-id>` using one JSON object on stdin
+with `sChoice`, `sNote` and `dtm` (the current ISO 8601 time). Commit and
+push the answer files to the IDD branch before continuing. Commit and push
+changes to `pending.json` when you record an answer and after you clear it,
+so another session can see the remaining work.
+
+In Codex, connect the IDD MCP server once with
+`codex mcp add idd --url https://interrogation.dev/mcp`, then restart Codex.
+While waiting for a hosted answer, keep an `idd_wait_for_change` MCP call active
+and run `npm exec -- idd wait <question-id>` as a second listener. The MCP tool
+signals any IDD branch change; `idd wait` synchronizes and records that
+question's answer. After either signal, inspect the latest branch state. Both
+may report the same update, so check pending data before incorporating an answer.
+
+Never replace an answer already accepted on the IDD branch; show the
+accepted answer if another submission conflicts.
+
+When a human answer is the only thing preventing progress, publish the
+session's `blocked` status on the data branch with
+`npm exec -- idd status <session-id> blocked`. Change it to `working`
+when work can proceed and clear the entry when the session ends. Commit and
+push status changes so the viewer shows the current state. Commit and push
+the pending queue after recording or clearing an answer, so later sessions
+can see what still needs work.
+
+## Count questions
+
+From the IDD data worktree, run `npm exec -- idd count` to print conflicts,
+unanswered, answered and superseded question counts. By default, the command
+requires a clean worktree, fetches the matching `idd-<branch>` from `origin`,
+and fast-forwards before counting. Use `--nosync` to count the current local
+files without fetching; this also permits a dirty worktree.
+
+Use `--type` to print just one numeric count:
+
+```sh
+npm exec -- idd count --type conflicts
+npm exec -- idd count --type u
+```
+
+The accepted types are `conflicts` (`c`), `unanswered` (`u`), `answered`
+(`a`) and `superseded` (`s`).
+
+## Thoughts and observations
+
+The questionnaire page has an always-open text box for project ideas and
+observations. Submitting a note writes it to `idd/thoughts.json` on the
+project's IDD branch, where repository writers can post notes and project
+readers can see them. The note is kept as plain text and does not change
+question counts.
+
+From the IDD data worktree, run `npm exec -- idd thoughts` to sync and list
+the notes. Use `npm exec -- idd thoughts --nosync` to list the current local
+copy without fetching. Notes stay in the repository after an agent has acted
+on them; a follow-up decision becomes a normal IDD question.
+
+## Keep IDD data separate and reconcile branches
+
+Commit questionnaire files, answers, history, conflicts and agent status
+only to `idd-<code-branch>`; do not include unfinished code in those commits.
+Before merging code branches, merge the source IDD branch into the target
+IDD branch, review duplicate, obsolete and overlapping questions, resolve
+answer conflicts, and complete any work needed to implement the accepted
+decision. Push the reconciled IDD branch before completing the code merge.
+
+Install the repository's merge hooks with
+`npm exec -- idd-merge-hook install` when the project uses that merge gate.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# Interrogation-Driven Development (IDD)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img align="right" src="assets/logos/idd-logo-icon.png" alt="IDD logo" width="140">
+
+## Purpose / Why
+
+Interrogation-Driven Development (IDD) is a framework for progressive
+software development. As an agent works through a specification, it records
+asynchronous questions for the engineer when it reaches an ambiguity or a
+decision boundary. The engineer answers through the project's questionnaire;
+those answers become recorded decisions that guide the implementation.
+
+IDD exists because decisions asked in a terminal or chat are easy to miss,
+repeat, or lose between sessions. A shared question list and recorded answers
+keep the agent and engineer aligned while the work advances one decision at a
+time.
+
+[Horizontal logo](assets/logos/idd-logo-horizontal.png) ·
+[Square logo](assets/logos/idd-logo-square.png) ·
+[Icon](assets/logos/idd-logo-icon.png)
+
+## TL;DR
+
+* Every decision a coding session needs from the human is added to the project's shared question list and presented through that agent tool's questionnaire.
+* Each code branch has its own `idd-<branch>` branch in the same GitHub repository. Questionnaire files stay out of code commits.
+* Any repository reader can view questions; submitting an answer requires repository write access. The browser commits answers directly to GitHub.
+* Agents can wait for answers with `idd wait`; GitHub push events wake the command when configured, with branch polling as a fallback. ChatGPT Work chats can subscribe to the hosted MCP event for idle-session notifications.
+* A project adopts IDD with one line in its `AGENTS.md`; every new session then reads the package's `INSTRUCTIONS.md` and acts on pending answers first.
+* The rules for writing questions and reading answers were earned in AIOS, one observed mistake at a time; they live here once, for every project.
+* IDD is a ConcordSTC project: its rules are marked statements rooted in the human's own words, and its code is tested against them.
+
+## Adopt IDD
+
+Install the package in the project with `npm install @debonet/idd`, then
+paste this line into the project's `AGENTS.md`:
+
+```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.
+```
+
+The path is resolved from the project's npm installation, so the instruction
+does not depend on where npm placed the package. The package's
+[`INSTRUCTIONS.md`](INSTRUCTIONS.md) explains branch setup and the session
+workflow.
+
+## Solution (what?)
+
+IDD has two parts: the agent-side npm package and the hosted questionnaire at
+`https://interrogation.dev`. The `idd` command manages question data, prints
+a direct viewer link, counts question states, and polls the matching remote
+IDD branch for answers. Its package includes the agent instructions and a Git
+merge hook; it does not include or run the hosted web application. An adopting project installs the tools with
+`npm install @debonet/idd`; the model reads the installed instructions using
+`node -p "require.resolve('@debonet/idd/INSTRUCTIONS.md')"`.
+
+Questionnaire, answer, status and history files live on the `idd-<branch>`
+branch in the same repository as the code. Agents edit them from a separate
+Git worktree, so an unfinished implementation never enters an IDD commit.
+Codex can present a question through its interactive questionnaire. The
+hosted viewer also lets the human answer from any device, and the agent can
+wait for that committed answer with `idd wait`.
+
+IDD also includes an optional hosted viewer for GitHub projects. It runs on
+Cloud Run, discovers questionnaire branches across repositories available to
+the signed-in user, and commits answers from the browser directly to GitHub.
+It does not store repository data or user tokens. It stores only ChatGPT MCP
+event subscription metadata in Firestore. ChatGPT Work chats can subscribe to
+the global answer-change event; each event contains no repository or answer
+data and asks the chat to inspect its current project. See
+[`docs/hosted-viewer.md`](docs/hosted-viewer.md) for GitHub App setup and
+deployment instructions.
+
+## Method (how?)
+
+An agent can present a question through its native questionnaire. The hosted
+viewer provides the same question on a web page; the browser commits the
+answer to GitHub. An agent waiting with `idd wait` receives a prompt event
+when the GitHub push webhook is configured, then fetches the answer and
+queues it as pending. Branch polling covers environments without push
+delivery. ChatGPT Work chats can receive the same webhook-triggered change
+through MCP Events while idle. Claude.ai currently uses an active `idd wait`
+call. A session lists pending answers at its start and acts on them
+before the task it was started for.
+
+The core workflow is harness-independent: the npm package supplies the data
+format, branch commands and agent instructions. The hosted viewer runs as a
+separate Cloud Run service at `interrogation.dev`. Tool-specific guidance
+describes how each agent presents a question and reads its immediate response.
+
+Each rule is a guidance line in `specs/guidance/`, rooted in the human's quoted words or marked as an architect's decision for him to ratify, and cites the observations in `observations.md` that it rests on. The page's behaviour and the command's are specified in `specs/questions-page.md`, `specs/project-files.md` and `specs/idd-page.md`, and tested against those statements. How a project adopts IDD is in `specs/adoption.md`; how a project with an existing page moves over, keeping its address and every saved answer, is in `docs/existing-page-migration.md`.

package/bin/idd

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// @implements s-cg2j10@e28309f
+// @implements s-vfgnzf@47216b8
+const { aRun } = require( "../scripts/commands" )
+
+Promise.resolve( aRun(
+  process.cwd(), process.argv.slice( 2 ),
+  () => require( "fs" ).readFileSync( 0, "utf8" )
+)).then(( aResult ) => {
+  process.stdout.write( aResult.sOut )
+  process.stderr.write( aResult.sErr )
+  process.exitCode = aResult.nExit
+}).catch(( xError ) => {
+  process.stderr.write( "idd: " + xError.message + "\n" )
+  process.exitCode = 1
+})

package/bin/idd-merge-hook

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+"use strict"
+
+// @implements s-e4kj5b@45aff9e
+const { fzMain } = require( "../scripts/merge-hook" )
+
+process.exitCode = fzMain(
+  process.argv.slice( 2 ),
+  process.cwd(),
+  ( s ) => process.stdout.write( s ),
+  ( s ) => process.stderr.write( s ),
+  process.env
+)

package/docs/existing-page-migration.md

@@ -0,0 +1,92 @@
+# Moving a project with an existing questions page to IDD
+
+This guide is for a project that already has a questions page made from the older template (`~/.claude/templates/questions-page.html`, questions held in a `vaQuestion` array inside the page) and rules of its own about questions for the human in its `AGENTS.md`, `CLAUDE.md` or specs. After it, the project's page is built from `idd/questions.json` and published to the same address, every saved answer still shows, and the project's rules files hold the IDD line in place of the rules IDD now holds. AIOS is the worked example throughout; another project substitutes its own files.
+
+Do it when no agent is running in the project, since it edits rules files, a spec and the observations file.
+
+## 1. Save the current state
+
+From the project root:
+
+```sh
+mkdir -p tmp/idd-migration
+npm run spec-map > tmp/idd-migration/spec-map-before.txt
+npm run spec-map -- --gate > tmp/idd-migration/gate-before.txt
+cp AGENTS.md CLAUDE.md observations.md tmp/idd-migration/
+cp specs/guidance/human-interaction.md tmp/idd-migration/
+```
+
+Write down the page's address (the session that published it has it; it is the artifact the human answers on). List the page's pending answers and its saved answers (in Claude Code, ArtifactData `list` on `pending` and on `answers`) into `tmp/idd-migration/store-before.txt`. Count the answered questions the page shows.
+
+## 2. Find the page's source
+
+The older practice copied the template to a scratch directory. Find the file that was last published: it holds `const vaQuestion = [`.
+
+```sh
+grep -rl "const vaQuestion" tmp/ 2>/dev/null
+```
+
+If it is not under `tmp/`, look in the publishing session's scratchpad. Copy it to `tmp/idd-migration/page-before.html`, and count its questions:
+
+```sh
+grep -c 'sId: "q' tmp/idd-migration/page-before.html
+```
+
+## 3. Create the IDD files and import the questions
+
+```sh
+~/@idd/bin/idd init "AIOS Open Questions"
+~/@idd/bin/idd import tmp/idd-migration/page-before.html
+~/@idd/bin/idd check
+```
+
+Edit `idd/page.json` and set `url` to the address from step 1. Confirm the question count is unchanged (`grep -c '"id": "q' idd/questions.json` equals the count from step 2), and read a few imported bodies against the old page: code shown in backticks, quoted markup shown as text.
+
+Build and publish to the same address:
+
+```sh
+~/@idd/bin/idd build
+```
+
+Publish `tmp/idd/page.html` to the recorded `url` (`~/@idd/specs/guidance/claude-code.md`, Publishing) and open it. The answered group's count must equal the count from step 1, since the answers are kept by question id. Commit `idd/page.json` and `idd/questions.json`.
+
+## 4. Add the IDD line
+
+Add this line, on its own line, near the top of the project's `AGENTS.md`:
+
+```
+Read @~/@idd/AGENTS.md before any other work; every decision for the human goes on this project's questions page.
+```
+
+## 5. Remove the rules IDD now holds
+
+From the rules files, delete each rule that IDD's guidance now states, keeping any fact of the project's own that the rule carried. In AIOS:
+
+* `AGENTS.md`, section 1, Communication: delete the rules on pointer answers, a question's example scenario, the standing-principles check, mapping onto an existing element, a ruling that gives a key a new meaning, a card's verbs, a question holding builds, nouns naming a tab, a saved answer being an answer, and a gloss of a ruling. Keep the human's quoted rulings that state AIOS's own principle (his q124, q131 and q172 words) under THE FIRST COMMANDMENT, which IDD's standing-principles check reads, and keep the list of AIOS specs that give keys their meanings as a fact beside it.
+* `CLAUDE.md`: delete the section "The questions page (Claude Code artifacts)".
+
+In the spec of guidance for dealing with the human (`specs/guidance/human-interaction.md` in AIOS), an architect deletes the guidance lines IDD now holds and keeps the project's own: in AIOS it keeps When to report, Orthogonality, the two product nouns (dialog, harness) and the on-screen-control rule, and deletes the rest of Questions, His rulings cited, the line on product decisions reaching the specs, and the nouns lines on spec words and on-screen things. A motive line left with no line rooted in it is deleted too (`grep -rn "<m-id>" specs/` prints only the motive line itself). The spec gains one sentence pointing at `~/@idd/AGENTS.md` for questions and answers.
+
+## 6. Move the observations
+
+For each observation cited only by rules deleted in step 5, list its citations and delete them and the entry:
+
+```sh
+npm run spec-map -- --sid o-x2i8vm
+```
+
+In AIOS these are o-7ioawk, o-x2i8vm, o-8rmpk8, o-65eyze, o-8qre78, o-il1nvy, o-bpncb3, o-a1t5mg, o-m7spcg, o-oud1hd and o-1asexx; each lives on in `~/@idd/observations.md` under the same id. o-faqe7j stays in AIOS as well, since THE FIRST COMMANDMENT cites it.
+
+## 7. Check and compare
+
+```sh
+npm run spec-map -- --assign
+npm run spec-map > tmp/idd-migration/spec-map-after.txt
+npm run spec-map -- --gate
+```
+
+Lists (34) and (35) are empty, and stale links, unresolved link lines, dangling targets, re-derive, unstamped, underived and malformed are all 0. Compare with the saved state: every rule removed in step 5 has a line in `~/@idd/specs/guidance/` stating it, and the store listing matches `store-before.txt`.
+
+## 8. Check a fresh session
+
+Start a new session in the project and give it an unrelated first task. Before that task, it reads `idd/page.json`, lists the pending answers and names them in one line. If it does not, check that the IDD line is in `AGENTS.md` outside backticks and that the session's tool loads `AGENTS.md`.

package/docs/hosted-viewer.md

@@ -0,0 +1,164 @@
+# Hosted viewer setup
+
+The IDD viewer runs as a small Node HTTP service on Cloud Run. Questionnaire
+files live in each project repository, on branches named `idd-<code-branch>`.
+The viewer discovers those branches through the signed-in user's GitHub App
+access and reads and writes their `idd/` files from the browser.
+
+## GitHub App
+
+Create a GitHub App for the viewer with these settings:
+
+* Homepage URL: `https://interrogation.dev`.
+* Callback URL: `https://interrogation.dev/auth/callback`.
+* User authorization callback URL: the same callback URL.
+* Repository permissions: Contents read and write; Metadata read-only.
+* The viewer requests GitHub's `offline_access` OAuth scope so sessions can
+  refresh without adding repository permissions.
+* Webhook URL: `https://interrogation.dev/github/webhook`.
+* Webhook secret: a separate random secret, stored in Google Secret Manager
+  under `GITHUB_APP_WEBHOOK_SECRET` in Cloud Run.
+* Subscribe to the Push event.
+* Install the app on each repository whose IDD questionnaire should appear.
+
+GitHub sends push events for branches in installed repositories. The viewer
+service validates the webhook signature and only notifies browsers about
+`idd-*` branches. It sends a content-free invalidation over Server-Sent Events;
+each browser then reads current data directly from GitHub. The browser sends
+repository requests directly to GitHub. Its encrypted, HttpOnly authentication
+cookie is sent only to the IDD service's `/auth` endpoints and the service does
+not persist the cookie contents. When push delivery is not configured or the
+event stream is disconnected, the browser checks branch
+heads every 30 seconds until the stream reconnects.
+
+The Cloud Run service is mapped to `https://interrogation.dev` and uses a
+Google-managed HTTPS certificate. Set the GitHub App homepage, callback and
+webhook URLs to the custom-domain values in the GitHub App section above.
+
+The Cloud Run service needs `GITHUB_APP_CLIENT_ID`,
+`GITHUB_APP_CLIENT_SECRET`, `IDD_OAUTH_STATE_SECRET`,
+`GITHUB_APP_WEBHOOK_SECRET` and `IDD_PUBLIC_URL`. After the GitHub App is
+configured to send push events to the service, set `IDD_GITHUB_PUSH_ENABLED`
+to `true`; otherwise the viewer keeps its branch-head polling fallback. Create independent random
+secrets for the OAuth state and webhook. Bind the client secret, state secret
+and webhook secret from Google Secret Manager; set the client ID and public
+URL as environment variables. Set `IDD_PUBLIC_URL` to
+`https://interrogation.dev`, with no trailing slash. To update an existing
+service, run:
+
+```sh
+gcloud run services update idd-service --project idd-platform --region us-east4 \
+  --update-env-vars=IDD_PUBLIC_URL=https://interrogation.dev
+```
+Do not commit credentials or pass them as plain deployment environment values.
+
+## ChatGPT event notifications
+
+The service's `/mcp` endpoint exposes an `idd.data.changed` MCP Event for
+ChatGPT Work chats. Enable the Firestore API, create the default Firestore
+database in Native mode, and grant the Cloud Run service account Firestore
+read/write access so subscriptions persist across service restarts. Add the
+hosted MCP endpoint as a ChatGPT custom connector and enable its event
+subscriptions. The event is global and carries no project or answer content;
+instruct a subscribed chat to check the IDD answers for the project it is
+working on when an event arrives.
+
+After Firestore is ready, set `IDD_MCP_EVENTS_ENABLED=true` on Cloud Run. The
+ChatGPT connector URL is `https://interrogation.dev/mcp`.
+
+Claude.ai's documented remote MCP connector does not support MCP Events. A
+Claude.ai chat can use the standard `idd_wait_for_change` tool during an
+active conversation; its tool call returns when a push arrives or after four
+minutes. Add `https://interrogation.dev/mcp` as a custom connector under
+Settings > Connectors. Claude Code can use the local `idd wait` command
+instead.
+
+## Deploy
+
+Use the deployment script from the IDD checkout. It requires the Google Cloud
+CLI (`gcloud`) installed and authenticated to a Google account with permission
+to deploy Cloud Run services in the `idd-platform` project. Run:
+
+```sh
+npm run deploy
+```
+
+The script builds the root Dockerfile and deploys `idd-service` in
+`us-east4`, with at most one instance and concurrency 1000. It preserves the
+service's existing environment variables, Secret Manager bindings, and access
+policy. It does not take credentials or secret values as arguments. The
+existing instance limit keeps the webhook and its open event streams on one
+instance; browsers reconnect and refresh after a restart.
+
+To print the deployed service URL, run:
+
+```sh
+gcloud run services describe idd-service --project idd-platform --region us-east4 --format='value(status.url)'
+```
+
+Add the GitHub App client ID as an environment variable and bind the client
+secret, OAuth state secret, and webhook secret from Secret Manager in the Cloud
+Run service configuration. Later deployments with `npm run deploy` preserve
+those settings.
+
+Set Cloud Run ingress to the intended public access policy. Firestore holds
+only MCP event subscription metadata; the service stores no questionnaire or
+user-token data server-side. The OAuth callback uses the app secret to
+exchange a one-use authorization code, sends the access token to the opener
+window, and writes the access and optional refresh tokens into an encrypted,
+Secure, HttpOnly, SameSite cookie. On page load, `/auth/session` restores the
+access token into JavaScript memory and refreshes it with GitHub when needed.
+GitHub access tokens last eight hours and refresh tokens last six months;
+after the refresh token expires, sign in again. Signing out clears the cookie.
+Keep `IDD_OAUTH_STATE_SECRET` stable across deployments so existing cookies
+can be decrypted.
+
+## Publish a project questionnaire
+
+Create the IDD data branch matching the code branch, for example
+`idd-main` for `main` and `idd-feature/login` for `feature/login`. Commit the
+questionnaire's `idd/` JSON files there and push the branch to the same
+repository. The viewer will discover it for users who can access the
+repository through the GitHub App. Answer submissions are committed by the
+browser, so no GitHub credential is needed in the agent environment.
+
+Use worktrees so IDD branches contain questionnaire files without a second
+copy of the source tree. For a repository's first code branch, create its
+matching IDD branch as an orphan with
+`git worktree add --orphan idd-<branch> tmp/idd-data`, initialize its
+question files there with `npm exec -- idd init`, then stage, commit
+and push those files to `refs/heads/idd-<branch>`. Never copy IDD data into
+the code branch. The data worktree can ignore generated files under `tmp/`.
+For a code branch based on another code branch, create its matching IDD
+branch from that base branch's IDD branch with
+`git worktree add -b idd-<branch> tmp/idd-data idd-<base-branch>`; this keeps
+the IDD branch histories mergeable. Set `idd/page.json`'s `branchHash` to the
+new code branch's hash, but leave inherited questions' `branchHash` values
+unchanged; new questions use the new page hash. For later updates, add the existing IDD
+branch as a worktree, edit its `idd/` files there, commit and push, then
+remove the temporary worktree. Do not copy the IDD data branch into the code
+branch.
+
+Initialize question ids with the branch hash computed from the GitHub
+repository's numeric id and full code ref by running
+`npm exec -- idd branch-hash <repository-id> refs/heads/<branch>`, then
+pass the printed hash to `npm exec -- idd init`.
+
+The viewer never merges code branches. The agent compares the corresponding
+IDD branches, reconciles duplicate, obsolete or conflicting questions, and
+completes the code decision before completing the code merge, as
+`specs/guidance/agent-merge.md` specifies.
+
+## Agent-aware merges
+
+Before a project uses the merge gate, run `npm exec -- idd-merge-hook install`
+from its root and commit the generated `.githooks/` files. Each participant
+runs the installer once in their clone to set Git's local `core.hooksPath`.
+Use `git merge --no-ff` for code branches. If the hook stops a merge, the
+agent first merges the source IDD branch into the target IDD branch, resolves
+file conflicts, consolidates duplicate or obsolete questions, and resolves
+answer conflicts. If the decisions still disagree, it adds a clarifying
+question and waits for the answer and implementation. Once reconciliation is
+complete, it pushes the target IDD branch and runs
+`npm exec -- idd-merge-hook reviewed`. The pre-merge hook then permits the code
+merge, and the post-merge hook confirms the same IDD history was reviewed.

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@debonet/idd",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Interrogation-driven development: the questions page and its command",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/debonet/idd"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "INSTRUCTIONS.md",
+    "README.md",
+    "bin/",
+    "docs/existing-page-migration.md",
+    "docs/hosted-viewer.md",
+    "scripts/check.js",
+    "scripts/commands.js",
+    "scripts/html-text.js",
+    "scripts/import-page.js",
+    "scripts/merge-hook.js",
+    "scripts/page-build.js",
+    "scripts/project-lock.js",
+    "specs/",
+    "templates/"
+  ],
+  "workspaces": [
+    "web"
+  ],
+  "bin": {
+    "idd": "bin/idd",
+    "idd-merge-hook": "bin/idd-merge-hook"
+  },
+  "scripts": {
+    "start": "node web/server.js",
+    "build:web": "node scripts/build-web.js",
+    "deploy": "npm run build:web && node scripts/deploy.js",
+    "test": "npm run build:web && jest",
+    "spec-map": "$HOME/@concord/bin/spec-map",
+    "spec-coverage": "$HOME/@concord/bin/spec-coverage",
+    "hook-install": "$HOME/@concord/bin/concord-hook install"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2",
+    "jest": "^29.7.0",
+    "jsdom": "^24.1.0"
+  },
+  "jest": {
+    "rootDir": ".",
+    "roots": [
+      "<rootDir>/test"
+    ],
+    "testEnvironment": "node"
+  }
+}