@debonet/idd 0.1.0 → 0.1.1

package/INSTRUCTIONS.md

@@ -1,5 +1,7 @@
 # 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
@@ -33,6 +35,13 @@ and grant it access to that repository.
    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>
@@ -86,6 +95,15 @@ 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.
 

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@debonet/idd",
-  "version": "0.1.0",
+  "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"
   },
@@ -21,15 +25,18 @@
     "specs/",
     "templates/"
   ],
-  "workspaces": [ "web" ],
+  "workspaces": [
+    "web"
+  ],
   "bin": {
     "idd": "bin/idd",
     "idd-merge-hook": "bin/idd-merge-hook"
   },
   "scripts": {
     "start": "node web/server.js",
-    "deploy": "node scripts/deploy.js",
-    "test": "jest",
+    "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"
@@ -38,12 +45,15 @@
     "node": ">=20"
   },
   "devDependencies": {
+    "esbuild": "^0.28.2",
     "jest": "^29.7.0",
     "jsdom": "^24.1.0"
   },
   "jest": {
     "rootDir": ".",
-    "roots": [ "<rootDir>/test" ],
+    "roots": [
+      "<rootDir>/test"
+    ],
     "testEnvironment": "node"
   }
 }

package/scripts/check.js

@@ -26,6 +26,9 @@
 // @implements s-r40lfj@d88f3b2
 // @implements s-g5gxep@784430f
 // @implements s-61lmfb@6451bc6
+// @implements s-0u0b06@9b94e8d
+// @implements s-8ffele@5deea72
+// @implements s-upxu0m@00fd9f6
 const crypto = require( "crypto" )
 const sFilePage = "idd/page.json"
 const sFileQuestion = "idd/questions.json"
@@ -35,6 +38,7 @@ const sFileStatus = "idd/status.json"
 const sFileHistory = "idd/history.json"
 const sFileConflict = "idd/conflicts.json"
 const sFileThoughts = "idd/thoughts.json"
+const sFileClaims = "idd/claims.json"
 
 function fbString( x ){
   return typeof x == "string" && x.length > 0
@@ -388,6 +392,28 @@ function fvsStatusProblem( aStatus ){
   })
 }
 
+function fvsClaimsProblem( aClaims, aWorkIds ){
+  if( !fbObject( aClaims )) return [ "not a JSON object" ]
+  return Object.entries( aClaims ).flatMap(([ sKey, aClaim ]) => {
+    const vsProblem = []
+    const aMatch = sKey.match( /^(answer|thought|conflict):([0-9a-f]{64})$/ )
+    if( !aMatch ) vsProblem.push( sKey + ": invalid claim key" )
+    if( !fbObject( aClaim )) return [ ...vsProblem, sKey + ": claim is not an object" ]
+    vsProblem.push( ...fvsMemberProblem( aClaim,
+      [ "sessionId", "claimedAt" ], [ "sessionId", "claimedAt" ], sKey + ": " ))
+    if( "sessionId" in aClaim && !/^[A-Za-z0-9._:-]{1,128}$/.test( aClaim.sessionId )){
+      vsProblem.push( sKey + ": invalid session id" )
+    }
+    if( "claimedAt" in aClaim && !fbIsoTime( aClaim.claimedAt )){
+      vsProblem.push( sKey + ": claimedAt is not an ISO 8601 time" )
+    }
+    if( aMatch && aWorkIds[ aMatch[ 1 ]] && !aWorkIds[ aMatch[ 1 ]].has( aMatch[ 2 ])){
+      vsProblem.push( sKey + ": item id is not present in its source file" )
+    }
+    return vsProblem
+  })
+}
+
 function faActiveQuestionIds( sTextQuestion ){
   try {
     const vaQuestion = JSON.parse( sTextQuestion )
@@ -493,7 +519,7 @@ function fvsParsed( sFile, sText, fvsProblem ){
 function fvsProblem(
   sTextPage, sTextQuestion, sTextAnswer = null, sTextPending = null,
   sTextStatus = null, sTextHistory = null, sTextConflict = null,
-  sTextThoughts = null
+  sTextThoughts = null, sTextClaims = null
 ){
   const aQuestionOfId = faQuestionOfId( sTextQuestion, sTextHistory )
   const vsActiveQuestionId = faActiveQuestionIds( sTextQuestion )
@@ -527,6 +553,34 @@ function fvsProblem(
     ...( sTextThoughts === null ? [] : fvsParsed(
       sFileThoughts, sTextThoughts, fvsThoughtsProblem
     )),
+    ...( sTextClaims === null ? [] : fvsParsed(
+      sFileClaims, sTextClaims, ( aClaims ) => {
+        const faIds = ( sText, sName ) => {
+          try {
+            const aData = JSON.parse( sText || ( sName === "thought" ? "[]" : "{}" ))
+            return new Set( sName === "conflict"
+              ? Array.isArray( aData ) ? aData.map(( a ) => a && a.id ) : []
+              : sName === "thought"
+                ? Array.isArray( aData ) ? aData.map(( a ) => a && a.id ) : []
+                : Object.keys( fbObject( aData ) ? aData : {} ))
+          } catch( xError ){ return new Set() }
+        }
+        return fvsClaimsProblem( aClaims, {
+          answer: new Set([
+            ...( () => {
+              try {
+                const vaQuestion = JSON.parse( sTextQuestion || "[]" )
+                return Array.isArray( vaQuestion )
+                  ? vaQuestion.map(( a ) => a && a.id ) : []
+              } catch( xError ){ return [] }
+            })(),
+            ...Object.keys( sTextAnswer === null ? {} : faAnswerOrEmpty( sTextAnswer )),
+          ]),
+          thought: faIds( sTextThoughts, "thought" ),
+          conflict: faIds( sTextConflict, "conflict" ),
+        })
+      }
+    )),
   ]
 }
 
@@ -535,4 +589,5 @@ module.exports = {
   sFilePending, fsQuestionId, fsLegacyQuestionId, fsBranchHash, faQuestionOptions, sXOptionText,
   sFileStatus, sFileHistory, sFileConflict, fvsStatusProblem, faQuestionOfId,
   sFileThoughts, fvsThoughtsProblem, fsThoughtId,
+  sFileClaims, fvsClaimsProblem,
 }

package/scripts/commands.js

@@ -5,6 +5,7 @@
 // @implements s-s1eg2z@e4283c0
 // @implements s-hsle36@555b1d8
 // @implements s-7wfrt9@cf88f5c
+// @implements s-q3kge1@ba97ef3
 // @implements s-854kw7@d393719
 // @implements s-y1y75p@326b683
 // @implements s-zrui8r@5a4422e
@@ -61,6 +62,10 @@
 // @implements s-14wrxl@7a4474b
 // @implements s-amd1ad@5c9c949
 // @implements s-8hvj7z@4ee0664
+// @implements s-2jdc1d@964ddde
+// @implements s-ky6iv4@0879c7a
+// @implements s-7pdsig@761907d
+// @implements s-7uz5pq@ea5a63d
 // @implements s-wapj39@5412047
 // @implements s-twjecx@96950c4
 // @implements s-g5gxep@784430f
@@ -73,7 +78,7 @@ const {
   fvsProblem, fvsAddProblem, fbIsoTime, sFilePage, sFileQuestion, sFileAnswer,
   sFilePending, fsQuestionId, fsLegacyQuestionId, fsBranchHash, faQuestionOptions,
   sFileStatus, fvsStatusProblem,
-  sFileHistory, sFileConflict, faQuestionOfId, sFileThoughts,
+  sFileHistory, sFileConflict, faQuestionOfId, sFileThoughts, sFileClaims,
 } = require( "./check" )
 const { fxWithLock } = require( "./project-lock" )
 const { fsHtml } = require( "./page-build" )
@@ -93,6 +98,8 @@ const sUsage = [
   "       idd import <page>",
   "       idd answer <id>   (a JSON answer on stdin)",
   "       idd status <session-id> <blocked|working|clear>",
+  "       idd claim <answer|thought|conflict> <item-id> <session-id>",
+  "       idd release <answer|thought|conflict> <item-id> <session-id>",
   "       idd count [--nosync] [--type <c|u|a|s|conflicts|unanswered|answered|superseded>]",
   "       idd thoughts [--nosync]",
   "       idd clear-pending <id> <time>",
@@ -164,7 +171,7 @@ function aViewerUrl( project, vsArg ){
   try {
     uViewer = new URL(
       process.env.IDD_VIEWER_URL ||
-        "https://idd-service-778162731919.us-east4.run.app"
+        "https://interrogation.dev"
     )
   } catch( xError ){
     return aResult( 2, "", "IDD_VIEWER_URL is not a valid URL\n" )
@@ -195,7 +202,7 @@ async function fOpenEventStream(){
   try {
     const uViewer = new URL(
       process.env.IDD_VIEWER_URL ||
-        "https://idd-service-778162731919.us-east4.run.app"
+        "https://interrogation.dev"
     )
     if( ![ "http:", "https:" ].includes( uViewer.protocol )) return null
     uEvents = new URL( "/events", uViewer )
@@ -408,7 +415,7 @@ function fvsProblemOf( project ){
     project.sReadOrNull( sFileAnswer ), project.sReadOrNull( sFilePending ),
     project.sReadOrNull( sFileStatus ), project.sReadOrNull( sFileHistory ),
     project.sReadOrNull( sFileConflict ),
-    project.sReadOrNull( sFileThoughts )
+    project.sReadOrNull( sFileThoughts ), project.sReadOrNull( sFileClaims )
   )
 }
 
@@ -645,6 +652,58 @@ function aStatus( project, vsArg ){
   return aResult( 0 )
 }
 
+function aWorkClaim( project, vsArg, bRelease ){
+  const [ sKind, sItemId, sSessionId ] = vsArg
+  if( ![ "answer", "thought", "conflict" ].includes( sKind ) ||
+    !/^[0-9a-f]{64}$/.test( sItemId ) ||
+    !/^[A-Za-z0-9._:-]{1,128}$/.test( sSessionId )){
+    return aResult( 2, "", "claim kind, item id or session id is invalid\n" )
+  }
+  const vsProblem = fvsProblemOf( project )
+  if( vsProblem.length ) return aProblem( vsProblem )
+  const sTextClaims = project.sReadOrNull( sFileClaims )
+  const aClaims = sTextClaims === null ? {} : aParsedOrNull( sTextClaims )
+  if( !fbObject( aClaims )) return aResult( 1, "", sFileClaims + ": not a JSON object\n" )
+  const sKey = sKind + ":" + sItemId
+  const aExisting = aClaims[ sKey ]
+  if( bRelease ){
+    if( !aExisting ) return aResult( 0 )
+    if( aExisting.sessionId !== sSessionId ){
+      return aResult( 1, "", "work item is claimed by " + aExisting.sessionId + "\n" )
+    }
+    delete aClaims[ sKey ]
+  } else {
+    if( aExisting ){
+      if( aExisting.sessionId === sSessionId ) return aResult( 0 )
+      return aResult( 1, "", "work item is claimed by " + aExisting.sessionId + "\n" )
+    }
+    const aAvailableIds = sKind === "answer"
+      ? faQuestionOfId( project.sReadOrNull( sFileQuestion ), project.sReadOrNull( sFileHistory ))
+      : aArrayIds( project.sReadOrNull( sKind === "thought" ? sFileThoughts : sFileConflict ))
+    if( !( sItemId in aAvailableIds ) && !aAvailableIds.has?.( sItemId )){
+      return aResult( 2, "", "item id is not present in its source file\n" )
+    }
+    aClaims[ sKey ] = { sessionId: sSessionId, claimedAt: new Date().toISOString() }
+  }
+  project.writeJson( sFileClaims, aClaims )
+  return aResult( 0 )
+}
+
+function aArrayIds( sText ){
+  try {
+    const vaData = JSON.parse( sText || "[]" )
+    return new Set( Array.isArray( vaData ) ? vaData.map(( a ) => a && a.id ) : [] )
+  } catch( xError ){ return new Set() }
+}
+
+function aClaim( project, vsArg ){
+  return aWorkClaim( project, vsArg, false )
+}
+
+function aRelease( project, vsArg ){
+  return aWorkClaim( project, vsArg, true )
+}
+
 function aCount( project, vsArg ){
   let bNoSync = false
   let sType = null
@@ -802,6 +861,8 @@ const aSpec = {
   "answer": { cArg: 1, fa: aAnswer, bNeedsPage: true, bWrites: true },
   "clear-pending": { cArg: 2, fa: aClearPending, bNeedsPage: true, bWrites: true },
   "status": { cArg: 2, fa: aStatus, bNeedsPage: true, bWrites: true },
+  "claim": { cArg: 3, fa: aClaim, bNeedsPage: true, bWrites: true },
+  "release": { cArg: 3, fa: aRelease, bNeedsPage: true, bWrites: true },
 }
 
 function aRun( sRoot, vsArg, fsStdin = () => "" ){

package/specs/build.md

@@ -11,10 +11,14 @@ invokes; no fixer runs `node`, `jest` or an ad-hoc pipeline outside these.
 
 * {#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.
+  command and server. The browser client uses Preact and is bundled into
+  same-origin static assets.
 * {#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.
+* {#s-0bt8j8 <arch} The browser client is rendered with Preact and emitted as a
+  same-origin static asset by `npm run build:web`; `npm test` and
+  `npm run deploy` build that asset before use.
 * {#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
@@ -67,6 +71,10 @@ invokes; no fixer runs `node`, `jest` or an ad-hoc pipeline outside these.
   `@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-vk03sm <arch for=main,architect,fixer via=prompt} The hosted service
+  uses Firestore for per-GitHub-user theme preferences as well as MCP event
+  subscriptions; user theme records use a separate collection and do not store
+  access tokens or answer data.
 * {#g-u68buh <arch for=main,architect,fixer via=prompt} Keep
   `@google-cloud/firestore` and `standardwebhooks` in the hosted workspace's
   runtime dependencies and
@@ -118,6 +126,23 @@ invokes; no fixer runs `node`, `jest` or an ad-hoc pipeline outside these.
   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`.
+> {#m-r4balx} RULING (CEO), 2026-11-12: “yes, let's do that.” This approves
+> GitHub Actions trusted publishing so package releases do not require the
+> maintainer to supply a one-time code for each release.
+* {#s-jm0nq3 <m-r4balx@e53a626} The root package metadata names `https://github.com/debonet/idd`
+  as its repository, matching the source repository used by npm trusted
+  publishing.
+* {#s-k9c49i <m-r4balx@e53a626} `.github/workflows/publish.yml` publishes only version tags. It
+  checks out the source, installs the supported Node and npm versions, runs the
+  full test suite, and publishes `@debonet/idd` with `id-token: write` and
+  `contents: read`; it stores no npm token.
+* {#s-r6qcwv <m-r4balx@e53a626} Configure npm's trusted publisher for `debonet/idd` and the
+  `publish.yml` workflow, allowing direct package publishing. A release tag's
+  version matches `package.json`; the workflow uses npm OIDC and publishes
+  provenance without an npm access token.
+* {#i-re3pab <s-r6qcwv@8f29404} **Do:** Run `npm trust list @debonet/idd`.
+  **Look for:** GitHub Actions trusted publishing for `debonet/idd` with
+  `publish.yml` and direct publishing allowed.
 * {#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.

package/specs/guidance/codex.md

@@ -76,6 +76,14 @@ incorporated. Each `[o-…]` citation names an entry of
   thing preventing progress; use `working` as soon as work can proceed, and
   `clear` before ending the session. Commit and push each status change so
   the viewer can show it.
+* {#g-bd17rs <s-7ppa6w@305659d for=main via=prompt} **Listen for hosted changes.**
+  Configure the IDD MCP server once with
+  `codex mcp add idd --url https://interrogation.dev/mcp`, then restart Codex.
+  While waiting on a hosted answer, keep both the MCP
+  `idd_wait_for_change` tool and `npm exec -- idd wait <question-id>` active.
+  When either reports a change, sync the matching IDD branch and inspect its
+  latest answers, thoughts and conflicts. Treat a second signal for the same
+  branch update as a duplicate; incorporate an answer only once.
 
 ## Dependencies
 

package/specs/guidance/session.md

@@ -57,6 +57,12 @@ answers are pending. Each `[o-…]` citation names an entry of
 > C) The session names q201 and asks whether to act on it now." His answer:
 > A.
 
+> {#m-kh7vgm} THOUGHT (CEO), 2026-11-13: “We need to make sure that
+> when a question is answered (or observation given or conflict resolved.)
+> that only one active agent picks up on that work. Which means that when
+> agents pull a new chunk of work, they need to write back to the Jason file
+> and check it in indicating that they are doing that work.”
+
 ## Starting a session
 
 * {#g-3ncq2t <m-vmsvl8@415d9d6 for=main via=prompt} **Find the matching IDD branch first.** At
@@ -92,6 +98,15 @@ answers are pending. Each `[o-…]` citation names an entry of
   answer. Work on it when it applies and is not already reflected in the
   project; if it needs a decision, ask a follow-up through the normal IDD
   question flow. Do not rewrite or remove submitted thoughts.
+* {#g-mfqz8n <m-kh7vgm@5b68e68 for=main via=prompt} **Claim shared work before acting.**
+  Before incorporating a pending answer or acting on a submitted thought or
+  answer conflict, claim that item's stable id for this session with
+  `npm exec -- idd claim <kind> <item-id> <session-id>`. Commit and push
+  `idd/claims.json` to the matching IDD branch before starting the work. If a
+  push is rejected, sync the branch and inspect the claim; do not start work
+  unless this session owns the claim. After the work is incorporated, release
+  the claim with `npm exec -- idd release <kind> <item-id> <session-id>`, then
+  commit and push the release.
 
 ## Every decision goes through the tool's questionnaire
 

package/specs/hosted-questionnaire.md

@@ -87,6 +87,28 @@ projects in one viewer.
 > access to more repositories. I think I may have only approved the one
 > project (idd) at this point.”
 
+> {#m-babliv} BUG REPORT (CEO), 2026-11-13: “OMG. Sometimes the text
+> field gets erased while I'm typing in it. What is happening? Is the page
+> refreshing and wiping out my in-progress work?”
+
+> {#m-zqh3c0} BUG REPORT (CEO), 2026-11-13: “Importantly also: the page
+> scroll should not change when being updated. It is quite jarring.”
+
+> {#m-6nlxee} BUG REPORT (CEO), 2026-11-13: “Better, but the text I was
+> editing scrolled when the page updated (unsure if my caret moved, but the
+> scroll of the textbox went back to 0 and I could not see the bottom/most
+> recent part of the entry)”
+
+> {#m-mwyvc9} RULING (CEO), 2026-11-13: “Yes. Do it. Each item already has a
+> stable id, so use that for the root of the element key”
+
+> {#m-sv3g4i} BUG REPORT (CEO), 2026-11-13: “when you sign in using
+> the menu, the menu should go away. Today it remains open.”
+
+> {#m-3qt6qa} “I'm still seeing
+> submitted observations in the observations box. They should be moved to the
+> answered section.”
+
 > {#m-h21kou} RULING (CEO), 2026-11-10: “Also, don't show the branch in the
 > special case where it is \"main\"
 >
@@ -387,6 +409,19 @@ projects in one viewer.
   automatically detects changes to IDD branches and refreshes their displayed
   questionnaire data without requiring a page reload. It preserves unsent
   answer drafts and the current dashboard or questionnaire view.
+* {#s-o1emm0 <m-babliv@56a9a30} A background questionnaire refresh preserves the
+  unsent text in the Thoughts and observations field, as well as unsent answer
+  drafts and the current page view.
+* {#s-nedtaj <m-zqh3c0@ebc8c99} When a background data refresh redraws the dashboard or
+  questionnaire, the page retains its scroll position.
+* {#s-b7mfmz <m-6nlxee@8de6a06} When a background questionnaire refresh redraws a text
+  field, it restores that field's internal scroll position, selection and
+  focus, so the person can continue editing where they left off.
+* {#s-0ez7w1 <m-mwyvc9@7e88d5d} A questionnaire item that remains present across a background refresh or
+  reorder retains its rendered root and any in-progress editing state; stable
+  item ids distinguish questions, thoughts, answers and conflicts.
+* {#s-np9p6t <m-sv3g4i@5b705c0} After GitHub sign-in succeeds, the navigation menu
+  closes.
 * {#s-1v9p2k <m-c37rfq@5dbe195} The GitHub App's push webhook is validated with
   its configured HMAC secret. Only pushes to refs beginning
   `refs/heads/idd-` trigger a viewer notification; webhook payloads are not
@@ -415,6 +450,10 @@ projects in one viewer.
 * {#s-jzlic8 <arch} The `/mcp` endpoint exposes the standard MCP tool
   `idd_wait_for_change`; an active call waits up to 240 seconds for an IDD
   branch push and returns only whether a change occurred.
+* {#s-7ppa6w <arch} A Codex session may wait for changes through both the IDD
+  MCP `idd_wait_for_change` tool and `idd wait <question-id>` at once. Either
+  can signal a change; the session synchronizes and inspects the latest IDD
+  branch, treating duplicate signals idempotently.
 * {#s-udvxd8 <arch} The hosted service stores MCP event subscriptions durably,
   including their callback URL, signing secret, event name, and expiration,
   and retains them across Cloud Run restarts.
@@ -472,9 +511,10 @@ projects in one viewer.
   idea or observation. Submitting non-empty text appends a thought to that
   project's current IDD branch; the form remains available for another
   submission.
-* {#s-zexwsh <arch} The section displays submitted thoughts with their stable ids,
-  submission times, and text as plain text. It does not display thought text
-  as HTML or treat thoughts as questions requiring an answer.
+* {#s-zexwsh <m-yxktyi@b0efeab,m-3qt6qa@4b64c8f} Immediately after a thought is submitted successfully, its card appears in the Answered section with its
+  stable id, submission time and text as plain text. The Thoughts and
+  observations section holds only the submission form. Thought text is never
+  displayed as HTML or treated as a question requiring an answer.
 * {#s-pla1x4 <arch} Submitting a thought writes directly from the browser to the
   repository's `idd/thoughts.json` on its IDD branch using GitHub access
   already granted to the signed-in user. A user without repository write
@@ -524,6 +564,15 @@ projects in one viewer.
   `https://interrogation.dev`, install `@debonet/idd`, resolve the installed
   package's `INSTRUCTIONS.md` path with `require.resolve`, and follow those
   instructions to set up IDD in the current project.
+> {#m-2kt5yx} FEATURE REQUEST (CEO), 2026-11-12: “The installation instructions are not
+> visible on interrogation.dev Are they there? (actually, hiding them in an
+> agent-readable comoment early in the file might be a great idea, e.g.:
+> <!-- if you're an agent that wants to install Interrogation Driven Development
+> (IDD), use npm install @debonet/idd --> )”
+* {#s-iy7nbz <m-2kt5yx@1aed464} The public landing page's HTML starts with a plain HTML comment
+  telling agents to install `@debonet/idd`, read its installed
+  `INSTRUCTIONS.md`, and use `https://interrogation.dev`; the comment is not
+  displayed as page text.
 * {#s-nq82ty <arch} The viewer signs users in through the IDD
   GitHub App's user authorization flow and requests only the app's repository
   contents permission.
@@ -657,6 +706,12 @@ projects in one viewer.
 * {#s-omsgq8 <arch} `idd/status.json` is an object keyed by active agent session
   id; each value has exactly a boolean `blocked` field and an ISO 8601
   `updatedAt` field.
+* {#s-0u0b06 <arch} If `idd/claims.json` exists, it is an object keyed by
+  `<kind>:<item-id>` where kind is `answer`, `thought` or `conflict` and the
+  item id is a lowercase 64-character hexadecimal id. Each value has exactly
+  a valid `sessionId` and an ISO 8601 `claimedAt` field. A claim may name only
+  an answer's question id, a submitted thought id, or a conflict id present in
+  the corresponding IDD file.
 * {#s-w9knti <arch} An agent session updates its entry on the
   matching IDD branch when its blocked state changes, sets `blocked` true
   only when it cannot continue without a human answer, refreshes `updatedAt`

package/specs/idd-page.md

@@ -9,7 +9,8 @@ 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.
+claims work items between agent sessions, prints a hosted viewer link, and
+counts questions on an IDD branch.
 
 ## His words
 
@@ -43,6 +44,14 @@ prints a hosted viewer link, and counts questions on an IDD branch.
   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.
+> {#m-umjnwb} BUG REPORT (CEO), 2026-11-13: “Somehow the new agent got this for a
+> login page: https://idd-service-778162731919.us-east4.run.app/?repo=AblifyAI%2Fablify&branch=main
+> It should be using interrogation.dev everywhere (that does not work with
+> github sign in!)”
+* {#s-q3kge1 <m-umjnwb@4a707e9} When `IDD_VIEWER_URL` is unset, both `viewer-url` and `wait` use
+  `https://interrogation.dev` as their origin. They never use the Cloud Run
+  `run.app` address as a viewer link or event endpoint, so GitHub sign-in stays
+  on the registered custom domain.
 * {#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
@@ -84,6 +93,24 @@ prints a hosted viewer link, and counts questions on an IDD branch.
   every entry by `specs/hosted-questionnaire.md`. Clearing an absent entry
   succeeds without writing the file.
 
+## Work claims
+
+* {#s-2jdc1d} **`claim <kind> <item-id> <session-id>`** records that one active
+  session owns an answer, thought or conflict work item in `idd/claims.json`.
+  It refuses to replace a claim held by another session and reports the
+  current owner; repeating a claim by its owner succeeds without changing its
+  timestamp.
+* {#s-ky6iv4} **`release <kind> <item-id> <session-id>`** removes a claim only
+  when the named session owns it. Releasing an absent claim succeeds; a
+  different owner is reported and the file is unchanged.
+* {#s-7pdsig} A claim kind is `answer`, `thought` or `conflict`; an
+  item id is a lowercase 64-character hexadecimal id; and a session id follows
+  the status command's validation rule. Invalid arguments exit 2. Malformed
+  claim data is refused without changing the file and exits 1.
+* {#s-7uz5pq} Claiming authorizes work only after the claim has been
+  committed and pushed to the matching IDD branch. A rejected push means the
+  session must sync and inspect the remote claim before it starts work.
+
 ## count
 
 * {#s-vwase3 <m-xoqfn9@0df3826} **`count`** reports the counts of conflicting, unanswered,

package/specs/project-files.md

@@ -5,9 +5,9 @@ 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.
+questions, answers, pending answers and work claims, so sessions of any agent
+tool work from the same question list and recorded results, while each tool
+presents its own questionnaire.
 
 ## His words
 
@@ -161,6 +161,16 @@ its own questionnaire.
 * {#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.
 
+## Work claims
+
+* {#s-8ffele <arch} `idd/claims.json` holds one JSON object keyed by
+  `<kind>:<item-id>`. Each value has exactly `sessionId`, the owning agent
+  session id, and `claimedAt`, an ISO 8601 time. Kinds are `answer`, `thought`
+  and `conflict`; the item id is the stable 64-character id from its source
+  file.
+* {#s-upxu0m <arch} If `idd/claims.json` is absent, no work item is claimed;
+  the first claim creates it.
+
 ## Thoughts and observations
 
 * {#s-61lmfb <arch} `idd/thoughts.json` holds one JSON array of thoughts in append

package/specs/themes.md

@@ -31,6 +31,11 @@ per-project theme preference.
 > or should match the splash page. Either way, the splash page theme should be
 > a theming option.”
 
+> {#m-rakcji} THOUGHT (CEO), 2026-11-13: “Theme choice should be shared
+> across browsers, but not across users. Perhaps we should maintain a list of
+> <user>,<theme> in the idd-<branch> directory on github, unless there is
+> another way (e.g. is there github-user storage offered?)”
+
 ## Built-in themes
 
 * {#s-ncz9te <m-qqilfo@d782597} The viewer offers the light, dark, retro, silk, and editorial
@@ -64,9 +69,24 @@ per-project theme preference.
 ## Theme choice and content hooks
 
 * {#s-6bc09d <m-qqilfo@d782597} The questionnaire page lets the user choose a theme for
-  that project and code branch. The viewer saves the choice in that browser
-  under the repository and branch identity, and keeps that preference when
-  the user returns to the questionnaire.
+  that project and code branch. The viewer saves the choice under the
+  authenticated GitHub user, repository and branch identity, and keeps that
+  preference when the user returns to the questionnaire in another browser.
+* {#s-jl9nzo <m-rakcji@fd6be8a} A project theme preference is keyed to the
+  authenticated GitHub user's immutable account id and the repository and
+  branch identity; two users may choose different themes for the same project.
+  The splash, dashboard and project theme choices are stored in Firestore and
+  shared across browsers for that user. The hosted service does not expose one
+  user's preferences to another user.
+* {#s-wmmbpw <m-rakcji@fd6be8a} The browser reads and writes the signed-in user's
+  theme choices through `/api/theme-preferences`, authenticating with its
+  in-memory GitHub access token. The service verifies the token's GitHub user
+  id before reading or writing that user's preference record. Theme preference
+  data contains only theme ids and project/repository branch keys;
+  it contains no access tokens or answers.
+* {#s-6io4k8 <arch} Before sign-in, the splash page uses a browser-local
+  theme choice. After sign-in, the user's saved splash theme replaces that
+  browser-local choice.
 * {#s-eydwk6 <m-fjqj3t@17d6d3e} The splash page and dashboard each have an independent built-in theme
   selector in the content area directly below the site header; changing either
   site theme leaves the other surface's theme and each project's questionnaire