@debonet/idd 0.0.0-stage → 0.1.1

package/specs/hosted-questionnaire.md

@@ -0,0 +1,793 @@
+# Hosted questionnaire
+
+## Purpose
+
+The hosted IDD page lets a person review and answer questionnaires stored in
+GitHub projects, and lets that person see questionnaires from several
+projects in one viewer.
+
+## His words
+
+> {#m-3jzy1x} RULING (CEO) 2026-11-05: “Seems like CloudRun is the way to go.”
+
+> {#m-7wyw60} RULING (CEO) 2026-11-05: “can the comms go directly
+> from the browser? so the form generates json in the browser, and the
+> browser submits the change directly to github?”
+
+> {#m-ol5xyr} RULING (CEO) 2026-11-05: “Prior answers need to always
+> be presented as text and never as HTML.”
+
+> {#m-4as0w8} RULING (CEO) 2026-11-05: “But if it's a separate
+> repository we can't leverage github code repository permissions for
+> access control.”
+
+> {#m-3jz9c9} RULING (CEO), 2026-11-08, IDD question
+> `3e4177d4bd9b9d93457d3c254374b354d1874ed32b17391f3b4433bd92db78be`:
+> “Which projects should appear first on the IDD page? After you sign in to
+> the IDD page, it lists project questionnaires you can read. A project can
+> have open questions, rejected answers, or only answered questions. If
+> several projects need your attention, which project should the page put at
+> the top? A) Projects with unanswered questions first, sorted by the oldest
+> question. B) Projects where the agent is marked blocked first, then other
+> unanswered questions by age. C) All projects in alphabetical order, with
+> open and conflict counts shown.” His answer: “B — Projects where the agent
+> is marked blocked first, then other unanswered questions by age.”
+
+> {#m-2wp6gd} BUG REPORT (CEO), 2026-11-08: “This does not count as a
+> conflict: [the same question's accepted answer and a rejected submission
+> with identical choice B and an empty note].”
+
+> {#m-65v6r2} BUG REPORT (CEO), 2026-11-08: “Returning to ‘all projects’
+> effectively unsubmits my prior answers.”
+
+> {#m-c37rfq} RULING (CEO), 2026-11-08: “The web page is alreay open. It
+> should somehow know to reload.”
+
+> {#m-umb15o} RULING (CEO), 2026-11-08, IDD question
+> `de91a974a87d89a88e487cbe7650fbdb743f7259ce32fe59fc6f3818d708c658`:
+> “How should a project writer resolve a conflicting answer? A question has
+> an accepted answer and a different later answer was rejected. What should
+> the IDD page let a project writer do to resolve this conflict? A) Keep
+> accepted answer and mark rejected submission resolved. B) Accept rejected
+> submission instead, preserving both answers in history. C) Ask a new
+> clarifying question and keep both submissions until answered.” His answer:
+> “A”. His note: “Huh? What is a ‘project writer’? What do you mean by
+> ‘accepted’ and ‘rejected’ (Do you mean one was first and the other was a
+> conflict?)
+>
+> Look, here's what should happen:
+>
+> if a question is answered and then re-answered later (either by another
+> session, or someone revisits an already answered question and changes their
+> answer) the response should be a follow on questions to clarify what to do.
+> Something like: ‘on date X answer Y was chosen, but on date Z, answer A was
+> chosen. Given that Y has already been implemented and subsequent decisions
+> made based on that, should we now switch to A?”
+
+> {#m-j48adi} RULING (CEO), 2026-11-08: “previously answered questions
+> should be ‘re-visitable’. i.e. I should be able to change prior answers
+> (causing a conflict, which triggers a clarification sequence)”
+
+> {#m-1nrz2d} RULING (CEO), 2026-11-09: “So you need to figure out how to send a
+> notification from webpage to the codex (or claude code, chatgpt.com,
+> claude.ai) session”
+
+> {#m-g75yf0} RULING (CEO), 2026-11-09: “So let's fix it. `idd-page` should just be
+> `idd`. For ChatGPT.com or Claude.ai, an idle chat can’t currently be
+> addressed through this page: it would need a supported integration in that
+> host. Such things exist. Find the mechanism and use it.”
+
+> {#m-551a7e} RULING (CEO), 2026-11-09: “answers should get letters so they can
+> be referenced in the note, e.g. A, B, C, etc.”
+
+> {#m-t4tzrb} RULING (CEO), 2026-11-09: “Also, make it so that the IDD page gets a
+> cookie, so that when I open it again I don't need to re-login every time.”
+
+> {#m-zgomvq} RULING (CEO), 2026-11-10: “We may need a button to give the app
+> 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\"
+>
+> Design issues:
+> * the \"Give IDD access to repositories\" button is huge and in the wrong
+>   spot. It should live at the top of the \"Your questionnaires\" dashboard.
+> * make the order on the dashboard: conflicts, unanswered, answered. Make
+>   the conflict and unanswered numbers much bigger than the text. Color them
+>   red, and blue (or some theme-appropriate colorization indicating
+>   very-important, important), unanswered remains small and default colored.
+> * what does \"no active agent status\" mean? It is way to prominent. If
+>   needed, put on the right side and use short phrases (e.g. \"none active\")
+>   and hover can show more info.
+> * when in a project the title should be \"Project: <project>, Branch:
+>   <branch> Questions\", this stuff should go away:
+>
+>   Questionnaire data updated from GitHub.
+>
+>   ← All projects
+>   debonet/aios · main
+>   Questionnaire data is on idd-main
+>
+> * the return arrow should be above the title and should read \"<-- dashboard\"
+>   (with a real arrow)
+> * \"Questionnaires are stored in their GitHub project repositories.\" should
+>   be removed
+> * add a hamburger menu that includes:
+>   either:
+>   * sign out
+>   * signed in as <username>
+>   or:
+>   * sign in
+>
+>   and:
+>   * add repositories
+>   * top repositories (top 10 sorted by date of conflicts, then unanswered)
+>   * <repo 1>
+>   * <repo 2>
+>   * FAQ
+>   * About
+>
+> * make the About page basically be a digest of the README that answers: why?
+>   what? how?
+> * make the FAQ include questions about security and access (where are keys
+>   kept? questions and answers kept)
+> * make the IDD in the upper left bigger, and use the logo (Logo version),
+>   which I will put in the docs/ directory
+> * make a favicon from the \"Icon\" version of the logo”
+
+> {#m-2cjvpr} BUG REPORT (CEO), 2026-11-10: “Fix questions so that all the text is
+> to the right of the radio button on wrapped lines. I.e. the text should be
+> left justified to the right of the radio button”
+
+> {#m-w1kbnf} BUG REPORT (CEO), 2026-11-10: “When you click
+> \"submit answer\" the question box should roll-up and disappear immediatley
+> and the networking should happen in the background.”
+
+> {#m-5saq28} BUG REPORT (CEO), 2026-11-10: “The rollup on submit is not working.
+> It should take a second or two. Currently the question immediately
+> disappears, which is jarring and confusing because it is immediately
+> replaced with the question below. Instead it should roll-up (shrink
+> vertically, as in the jquery-style animation) and the question below rising
+> with it so that it is clear what is happening.”
+
+> {#m-loh9m9} BUG REPORT (CEO), 2026-11-10: “doing back to the dashboard still
+> yields and empty screen?”
+
+> {#m-4fn63n} “Can we cache/store the projects in a cookie so that there's no delay
+> when you reload or go back to the dashboard? When the fetch completes it can
+> update the display and cookie.”
+
+> {#m-65brxv} “It would be useful if the \"<-- dashboard\" could also indicate how
+> many projects have conflicts and/or questions pending. Some number that tells
+> how mnay projects need your attention.”
+
+> {#m-3xcl02} BUG REPORT (CEO), 2026-11-11: “The count after "<-- dashboard" should
+> not include the current project!”
+
+> {#m-n9dd7y} “Drop the \"Project: \" in the header”
+
+> {#m-i0grng} BUG REPORT (CEO), 2026-11-10: “The logo and favicon are not
+> working”
+
+> {#m-j5r1fg} “I moved the old logos out of the way and replaced them with a single
+> cleaner logo. Use that for both the page and the favicon. It no longer
+> contains text, so for the logo at the top of the page add in html "IDD
+> Interrogation-Driven Development" in some attrative way”
+
+> {#m-rhr8be} “That should be a standard part of your unit test suite.”
+
+> {#m-v12ugx} “Use the new docs/Question*png image as the favicon”
+
+> {#m-zanwxq} “So \"Question Histor\" should instead be
+> \"depricated questions\" or \"revisited questions\" or something like that.”
+
+> {#m-3fsbff} “The theme selector is too prominent. Move it to the
+> right side, on the same line as the \"<-- dashboard\"”
+
+> {#m-8drgj4} RULING (CEO), 2026-11-10: “We should also have a
+> splash/informational page that shows up when you're not logged in. And
+> when you're logged in, you go directly to your dashboard.”
+>
+> {#m-cba3po} RULING (CEO), 2026-11-10: “On the splash page, show some
+> screenshots with fake questions and answers, using the various themes.
+> Put them in drop-shadow'd rounded rectangle gradient-alpha (fade at top)
+> image containers.”
+
+> {#m-1um0ef} RULING (CEO), 2026-11-11: “blurb below is too wordy. TL;DR.
+> Make it short punchy sentences. something like: ‘You provide initial
+> spec, agent starts coding, posts async questions, you answer to guide the
+> development’ but even punchier”
+
+> {#m-jp4via} RULING (CEO), 2026-11-11: “the key motivator here is:
+> human intelligence is the limited resource. Don't waste it reading walls
+> of text. Critical issues surfaced. Compactly, clearly, and decisively.
+> Human judgement is captured efficiently. --> Use it in why and elsewhere”
+
+> {#m-yj5thl} RULING (CEO), 2026-11-11: “themes is not the big
+> feature. The big features are:
+> * secure
+> * access to questions matches developer's access to the code
+> * works on any github project public or private
+> * works from anywhere -- laptops, tablets, phones
+> * you dont need to set up a server
+> * supports branches, question merging, conflict resolution
+> --> make each of the example images demonstrate/visualize a different
+> one of those things, and do it with different themes (so theming isn't
+> the feature being promoted). Your goal is to show examples how the
+> system can be used”
+
+> {#m-cpqj0v} RULING (CEO), 2026-11-11: “add a teaser at the bottom
+> that IDD optionally integrates with the ConcordSTC agentic engineerign
+> approach.”
+
+> {#m-hfp7kb} RULING (CEO), 2026-11-11: “The why, what, how boxes were good.
+> Drop the \"Why IDD\". Keep the Human judgement text, then below it add back
+> Why, How, What boxes, with very short sentences:
+> Why: Efficient capture of human judgement
+> What: No walls of text. Just crisp questions
+> How: Agent asks when it needs, you answer when you can.”
+
+> {#m-nnxwab} RULING (CEO), 2026-11-11: “The examples need to be examples.
+> You've mixed examples of the product with key features. For the features,
+> list them in attractive boxes (not images of that kind of look like the
+> product). Again the list from above, but make crisper:
+> * secure
+> * access to questions matches developer's access to the code
+> * works on any github project public or private
+> * work from anywhere -- laptops, tablets, phones
+> * you dont need to set up a server
+> * supports branches, question merging, conflict resolution
+>
+> Then show examples of semi-real things:
+> * the \"when should reminders arrive?\" question is a good one
+> * another one about using one package over another
+> * another one showing a conflict resolution (you said X, bob said Y, which
+>   is correct?)”
+
+> {#m-3sqckb} “Can you pick a theme that is somewhat more attractive and interesting?
+> Perhaps the colors you use for the silk theme, but with a sans serif font.
+> Also, have greater size variations in the fonts”
+
+> {#m-ikc4ps} “No that is too \"brown\", look at the openai.com/about page, and use a
+> theme closer to that”
+
+> {#m-ry1hp7} BUG REPORT (CEO), 2026-11-12: “BUG: conflict
+> resolution is not working. I'm clicking submit changed answer, and another
+> conflict shows up. Also, the rejected submissions are showing up in the
+> conflicts area.”
+
+> {#m-4w4679} FEATURE (CEO), 2026-11-12: “reverse the order
+> of the answered questions, so the most recent is at the top.”
+
+> {#m-o26kii} BUG REPORT (CEO), 2026-11-12: “the
+> \"<-- dashboard\" is still showing a needs attention count that includes
+> the current project.”
+
+> {#m-awh12l} BUG REPORT (CEO), 2026-11-12: “take a look at the idd file in
+> ~/@aois. It seems to contain a conflict which keeps reoccurring every time I
+> \"resolve\" it.”
+
+> {#m-hvgu3e} RULING (CEO), 2026-11-12: “Ohh. So there's two different things:
+> * conflicts to be resolved
+> * conflicts that have been resolved but have not yet been addressed
+> The latter seems like it should just go into the answered section. Answered
+> questions also may not yet have been addressed, but they leave the open
+> questions section.”
+
+> {#m-yxktyi} RULING (CEO), 2026-11-12: “Can we add a ‘thoughts and
+> observations’ section, which is essentially a perpetually open question
+> of what do you have in mind? and just provides a text box. When you write
+> in it, it generates a new question-id (with essentially an empty question,
+> maybe the date) and the statement you've made? That way you can remotely
+> send ideas and any active agent can pick them up and work on them (and
+> presumably ask followup questions about them if needed)”
+
+> {#m-2cwth4} RULING (CEO), 2026-11-12: “That information should somehow be
+> embedded in the splash page so that I can tell a model ‘go look at
+> interrogation.dev and let's use it’.”
+
+## Hosted page
+
+* {#s-71l9ho <m-3jzy1x@623b849} The IDD viewer and project questionnaires are
+  served from an IDD web application deployed on Google Cloud Run.
+* {#s-1lggg7 <arch} The viewer lists the projects the signed-in GitHub
+  user can read that have an IDD questionnaire, and links each project to
+  its questionnaire.
+* {#s-7f2p1j <arch} A project questionnaire page identifies its GitHub
+  repository and code branch; the page shows that branch's IDD questionnaire.
+* {#s-6k70cj <arch} The dashboard shows each project's unanswered, conflicting, and
+  answered questions, and the time unanswered questions have been waiting.
+* {#s-0kqa6m <arch,m-h21kou@7fe10b2} Dashboard question counts appear in this order:
+  conflicts, unanswered, answered. Conflict and unanswered numbers are larger
+  than their labels; conflicts use the theme's alert color and unanswered
+  counts use the theme's accent color. Answered counts stay small and use the
+  default subdued color.
+* {#s-c128mc <arch,m-h21kou@7fe10b2} Agent status is aligned at the right of each
+  project row and uses a short label such as `none active`, `working`, or
+  `blocked`; its title tooltip provides the detailed session status.
+* {#s-nf173i <arch,m-h21kou@7fe10b2} Project and questionnaire headings omit the
+  branch label when the code branch is `main`; other branches remain visible.
+* {#s-eeqrcf <arch,m-h21kou@7fe10b2,m-n9dd7y@66937d7} A questionnaire heading reads
+  `<repository>, Branch: <branch> Questions`, omitting `, Branch:
+  <branch>` for `main`. Above it, one back link returns to the dashboard.
+  The questionnaire view does not show the success notice, the IDD data
+  branch name, or another project/branch line.
+* {#s-pgrj98 <m-65brxv@d2a98c2,m-o26kii@87c1cd6} The questionnaire's
+  dashboard return link reads `← dashboard · <n> need attention`, where `<n>`
+  counts each other repository and IDD branch with at least one unanswered
+  question or unresolved answer conflict once, excluding the current
+  repository and IDD branch by their stable identities.
+* {#s-ajo3ld <m-3fsbff@a314ab9} The theme selector shares a row with the dashboard
+  back link and is aligned at the right side of that row.
+* {#s-kmiped <m-zgomvq@a9d3d33,m-h21kou@7fe10b2} The signed-in dashboard places a
+  compact `Add repositories` link at the top of `Your questionnaires`; the
+  hamburger menu also contains that link.
+* {#s-prsnbh <arch,m-h21kou@7fe10b2} A hamburger menu opens and closes an accessible
+  navigation panel. It shows either sign-in or the signed-in username and
+  sign-out action, an Add repositories link, the top ten repositories, FAQ,
+  and About. The panel uses the compact spacing, aligned text, and clear
+  hierarchy of a standard graphical application menu; repository links are
+  indented beneath Top repositories with tree lines showing their parentage.
+  The final repository connector ends in an L, without a vertical line
+  continuing below it.
+* {#s-sb8f7i <arch,m-h21kou@7fe10b2} The menu lists at most ten distinct
+  repositories with questionnaires. Repositories with conflicts come first,
+  sorted by their latest conflict time descending; the rest are sorted by
+  unanswered question count descending, then oldest unanswered question
+  first, then repository name. A repository link opens its most urgent
+  questionnaire branch.
+* {#s-ia2mkv <arch,m-h21kou@7fe10b2} The About page presents a concise digest of
+  the README's Why, What and How sections.
+* {#s-kmzltz <arch,m-h21kou@7fe10b2} The FAQ answers who can read and answer,
+  where GitHub credentials and app secrets are kept, and where questions and
+  answers are stored.
+* {#s-vgd6wr <m-j5r1fg@473daea,m-v12ugx@63766d4} The provided Interrogation Flow Decision Icon image is used as
+  the upper-left brand mark beside visible HTML text reading “IDD
+  Interrogation-Driven Development”; the Question Bubble Decision Flow image
+  is used as the favicon.
+* {#s-3htunx <m-i0grng@584ee4f} The logo and favicon URLs referenced by the viewer return
+  their PNG image files with the `image/png` media type.
+* {#s-gj59q3 <m-zanwxq@4e60fc3} The collapsed question history section is labeled
+  `Superseded questions`.
+* {#s-fn4x75 <arch,m-h21kou@7fe10b2} The footer sentence `Questionnaires are stored
+  in their GitHub project repositories.` is not displayed.
+* {#s-hun225 <arch,m-ec324x@c9504b3} Each hosted question displays the reserved X option
+  from `specs/project-files.md` last, using its fixed text. A legacy question
+  without X receives the same displayed option without changing its stored
+  question or id.
+* {#s-qpdk8t <arch,m-ec324x@c9504b3} A question with no saved answer and no unsent
+  draft starts with no option selected. An existing answer or draft remains
+  selected when the form is revisited or refreshed.
+* {#s-li6mcw <m-2cjvpr@8bfc299} Each answer option places its radio button in a left column and
+  all of its label text in a right column; wrapped lines start at the same
+  left edge as the first line of label text.
+* {#s-1ci45n <m-w1kbnf@3fb9f61,m-5saq28@dd97235} Submitting an answer starts a visible vertical
+  collapse of its question box that lasts one to two seconds, with following
+  content rising as the box shrinks, while the network request runs at the
+  same time; a failed request restores the question box and its draft.
+* {#s-ifpl8z <m-3jz9c9@647adb8} **Dashboard order.** Projects with an agent session
+  marked blocked appear first. Other projects with unanswered questions
+  follow, ordered by the creation time of their oldest unanswered question.
+  Projects with no unanswered questions appear last.
+* {#s-yl7soe <arch} Projects with the same ordering priority are sorted by
+  repository full name and then code branch.
+* {#s-3fmok8 <m-65v6r2@23373a9} When a person returns to All projects and
+  reopens a questionnaire during the same page session, the viewer preserves
+  any unsubmitted choice and note for each open question.
+* {#s-vb6pz0 <m-loh9m9@271a655} Returning from a questionnaire to the dashboard displays the
+  available project branches.
+* {#s-lqwhd5 <m-4fn63n@ead29bc} When project summaries saved in browser local storage exist for
+  the signed-in GitHub account, the dashboard displays them before fresh
+  repository data finishes loading, then updates the display and saved
+  summaries with the fetched project data.
+* {#s-qv9ghz <arch} The dashboard cache is scoped to the signed-in GitHub account and
+  contains no access tokens, question text or answers.
+* {#s-8j6gdw <m-c37rfq@5dbe195} While the viewer is open and signed in, it
+  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
+  forwarded to browsers.
+* {#s-jmz4e7 <m-c37rfq@5dbe195} The hosted service sends a generic invalidation
+  event to connected viewers and active command waiters over a same-origin
+  Server-Sent Events stream. The event contains no repository, branch,
+  commit, or answer data.
+* {#s-mj541y <arch} When an agent is waiting for an answer through `idd wait`,
+  the hosted service's invalidation event makes that waiting command check
+  the remote IDD branch immediately; the answer is read from GitHub, not
+  from the event.
+* {#s-9gymp2 <m-1nrz2d@b86ec13,m-g75yf0@44f7e6c} ChatGPT Work chats can
+  subscribe to the hosted `idd.data.changed` MCP event; when a matching
+  IDD-branch push arrives, ChatGPT delivers the event to that subscribed chat
+  and follows the user's instruction for what to do next.
+* {#s-v65h8r <arch} The hosted MCP event contains only a generic change
+  indicator; it carries no repository, branch, commit, question, answer, or
+  user data.
+* {#s-4vnngz <arch} The hosted MCP event is global: every active subscription is
+  notified for every push to any `idd-*` branch.
+* {#s-fda7vp <arch} The `/mcp` endpoint advertises MCP Events during
+  initialization and lists one webhook-delivered `idd.data.changed` event
+  with no subscription arguments and a payload containing only
+  `{"changed":true}`.
+* {#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.
+* {#s-zsz7sy <arch} The hosted service grants MCP event subscriptions a finite
+  expiration and refreshes an existing subscription idempotently when ChatGPT
+  repeats its subscription request.
+* {#s-95yj75 <arch} The MCP event endpoint validates callback destinations as
+  public HTTPS addresses, verifies each callback with a fresh signed
+  challenge before storing a subscription, and signs event deliveries using
+  Standard Webhooks.
+* {#s-mome2c <arch} A user can unsubscribe from an MCP event; repeated
+  unsubscribe requests succeed without changing other subscriptions.
+* {#s-mter3r <arch} A Claude.ai custom connector can use
+  `idd_wait_for_change` to receive the generic change result while a tool call
+  is active; Claude.ai does not support the MCP Events subscription used for
+  unsolicited delivery to an idle chat.
+* {#s-8sk5lv <m-c37rfq@5dbe195} A signed-in browser reloads its project data
+  directly from GitHub when it receives an invalidation event.
+* {#s-6sl6e9 <m-c37rfq@5dbe195} When push notifications are unavailable or the
+  event stream is disconnected, the browser checks IDD branch heads every 30
+  seconds and refreshes when a head changes. A reconnected event stream causes
+  an immediate refresh to recover missed notifications.
+* {#s-u8f4vi <m-umb15o@4ae4e2f,m-j48adi@77b2d25} A person can revisit an answered question in the
+  collapsed Answered section, see its current answer, and submit a changed
+  choice or note; the form starts with the current answer selected and note
+  filled in.
+* {#s-46zdl6 <m-551a7e@e3167a4} Each option in the hosted questionnaire displays its key followed
+  by a period and a space before its text, such as `A. First`, so the person
+  can refer to the key in the answer note.
+* {#s-ax24rw <arch} A project becomes visible in a user's dashboard when an IDD
+  questionnaire branch is pushed to a repository the user can read; no key
+  is copied into the viewer.
+* {#s-foxumh <arch} The viewer places rejected answer submissions that differ from
+  the accepted answer in a Conflicts section, unanswered questions in an
+  Unanswered section, and accepted questions in a collapsed Answered section.
+  An omitted note and an empty note are the same answer for conflict detection.
+* {#s-10icw5 <m-umb15o@4ae4e2f} A changed answer to a previously answered question
+  appears as a conflict while the currently committed answer remains visible
+  as the prior ruling.
+* {#s-68mj1g <arch} A question with an unresolved answer conflict appears in the
+  Conflicts section and cannot be resubmitted from that card. When its
+  clarification answer is recorded, the agent resolves the conflict and the
+  question appears in the Answered section, even while the agent has not yet
+  carried out the ruling.
+* {#s-4p12mq <m-4w4679@821d091} The collapsed Answered
+  section orders questions by accepted-answer timestamp, newest first.
+* {#s-i9eyq7 <arch} Anyone who can read the GitHub repository can read its
+  questionnaire; only a user with repository write permission can submit an
+  answer.
+* {#s-gu4cxa <arch} The project agent adds its questionnaire to
+  the viewer by pushing the `idd-<branch>` branch to the project repository;
+  no user copies a repository key or questionnaire token.
+* {#s-0zk4qi <arch} Each project questionnaire has an always-visible “Thoughts and
+  observations” section with a text box that invites the person to share an
+  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 <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
+  permission cannot submit. Concurrent submissions are retried against the
+  latest file so each distinct thought is retained; no submission silently
+  overwrites another.
+* {#s-x4v7f8 <arch} A successful thought submission gives the person visible
+  confirmation and triggers the same generic questionnaire-change
+  notification as other IDD branch updates.
+
+## Sign-in and project discovery
+
+* {#s-6qd8cg <m-1um0ef@6d0079c} The landing-page introduction uses short sentences to say
+  the user gives the agent a specification, the agent starts coding and asks
+  asynchronously when decisions arise, and the user's answers guide the work.
+* {#s-rle2e6 <m-jp4via@372ebc0} The landing page says human judgment is the scarce resource,
+  promises to surface critical decisions compactly and clearly, and says answers
+  are captured for the work to follow.
+* {#s-ixb261 <m-3sqckb@be4a1af,m-ikc4ps@b94ec3a} The signed-out landing page uses a clean editorial style
+  inspired by OpenAI's About page: near-white surfaces, charcoal text, a
+  restrained cool accent, a sans-serif font, generous spacing, and a clear type
+  scale with a large hero and section headings, and smaller labels and support
+  text.
+* {#s-a9y6kc <m-8drgj4@443e70b} On page load, a signed-in user goes directly to the
+  project dashboard, while a signed-out user sees an informational landing
+  page with a GitHub sign-in action.
+* {#s-lxsmnv <m-hfp7kb@6afb5f9} After the human-judgment statement, the landing page shows
+  three compact boxes labeled Why, What, and How with these respective
+  messages: “Efficient capture of human judgment,” “No walls of text. Just
+  crisp questions,” and “Agent asks when it needs, you answer when you can.”
+* {#s-q6l925 <m-nnxwab@b96d3e8} The landing page lists six capabilities in feature boxes,
+  separate from its questionnaire examples: secure use; question visibility
+  and answering governed by the same repository permissions as code; public
+  and private GitHub projects; use from phones, tablets, and laptops; no
+  server for the project owner to set up; and branch-aware question merging
+  and answer-conflict resolution.
+* {#s-3z7br4 <m-nnxwab@b96d3e8} The landing page shows three fictional questionnaire
+  examples: a reminder-time choice, a package choice, and a follow-up asking
+  which answer to use when the user's earlier answer differs from Bob's.
+* {#s-r6ac5z <m-nnxwab@b96d3e8,m-yj5thl@e055d58} The three questionnaire examples use different
+  built-in theme styles as decoration; the examples show question content
+  rather than mock screenshots of the IDD product.
+* {#s-ry22kb <m-cpqj0v@055fe29} The bottom of the landing page says IDD can optionally be
+  paired with ConcordSTC and briefly describes its agentic engineering role.
+* {#s-yaanwo <m-2cwth4@716df92} The public landing page includes a visible “Use IDD in your
+  project” block with a copyable prompt that tells an agent to visit
+  `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.
+* {#s-7falz6 <arch} The Cloud Run application starts OAuth,
+  validates a short-lived state value at the callback, exchanges the authorization
+  code for a GitHub user access token, and returns that token only to the viewer
+  window that started the matching sign-in attempt, even when the browser severs
+  the popup's opener during GitHub's cross-origin redirects.
+* {#s-1n1bgd <m-rhr8be@e22d43f} The sign-in-start unit test verifies that the authorization URL
+  uses the registered GitHub App client ID and the exact production callback
+  URL `https://interrogation.dev/auth/callback`.
+* {#s-zapq64 <arch} The callback response is not cached; it sends the token to the
+  matching viewer window through a same-origin channel and closes its window
+  after delivery.
+* {#s-gl226e <arch} The viewer accepts a callback token only for its current
+  sign-in attempt; an unrelated or stale callback cannot sign it in.
+* {#s-g9fydo <arch} The browser keeps the active GitHub access token only in
+  memory and uses it to request repositories and questionnaire data directly
+  from GitHub; page scripts cannot read the persistent authentication cookie.
+* {#s-9040av <arch} The dashboard lists repositories visible
+  through the signed-in user's GitHub App access and includes a repository only
+  when its default branch or another discovered code branch has a matching
+  `idd-<branch>` branch.
+* {#s-qxpze6 <m-zgomvq@a9d3d33} While signed in, the dashboard offers a link to the IDD GitHub App's
+  installation page so the user can grant it access to additional repositories.
+* {#s-14uprd <arch,m-zgomvq@a9d3d33} When the viewer regains focus after the user changes the app's
+  repository access, it re-enumerates repositories through GitHub and refreshes
+  the project list while preserving the current questionnaire and unsent answer
+  drafts.
+* {#s-bhzh7h <arch} The viewer requires the GitHub App to be
+  installed on a repository before listing or changing that repository's IDD
+  data; GitHub enforces the user's and installation's repository permissions.
+
+## Browser and server boundary
+
+* {#s-96h8gu <arch} The Cloud Run service serves the static
+  viewer and the OAuth start and callback routes; it does not proxy GitHub
+  repository reads or writes.
+* {#s-xg63my <arch} The GitHub App client secret is supplied
+  to the Cloud Run service through its secret manager binding and is never
+  sent to a browser.
+* {#s-ptm6ns <arch} OAuth state is random, short-lived, bound
+  to the browser by a secure, HttpOnly, SameSite cookie, checked at the
+  callback, and then cleared; the authorization code is exchanged only once.
+* {#s-0ds89f <arch} The viewer uses a restrictive Content
+  Security Policy, disallows framing, and does not load third-party scripts.
+* {#s-xb07h5 <arch} The GitHub access token used by page scripts is held only in
+  JavaScript memory and is discarded on sign-out, page close, or expiration.
+* {#s-hcs0wx <m-t4tzrb@6d2bfbe} After GitHub authorization, the service seals the access token
+  and any refresh token into a Secure, HttpOnly, SameSite cookie scoped to
+  `/auth`; its lifetime does not exceed the refresh-token lifetime, or the
+  access-token lifetime when no refresh token is issued.
+* {#s-s2hz7w <arch} The service encrypts and authenticates the authentication
+  cookie payload with a key derived from `IDD_OAUTH_STATE_SECRET`; it does not
+  store GitHub user tokens in server-side session storage.
+* {#s-1nncya <arch} On page load, the viewer requests its session from the same-origin
+  service, which returns a still-valid access token or refreshes an expired
+  access token with GitHub and rotates the cookie after refresh; an invalid
+  session cookie requires the user to sign in again.
+* {#s-c2kkp3 <arch} Signing out clears the persistent authentication cookie through
+  the same-origin service.
+* {#s-4zoo4x <arch} The viewer requests GitHub's `offline_access` OAuth scope to
+  receive refreshable user tokens; this scope does not grant additional
+  repository permissions.
+
+## Answer file writes
+
+* {#s-ntcb9t <arch} The browser reads an IDD branch's data
+  files with the GitHub Contents API and writes updated files directly through
+  that API using the user's GitHub token.
+* {#s-4exg46 <arch} A submission includes the Git blob SHA
+  that the browser read; GitHub rejects the write if the file changed since
+  that read, and the viewer reloads and reports the accepted answer as a
+  conflict instead of overwriting it.
+* {#s-pc0ev7 <arch} The browser validates that the selected
+  option belongs to the question before attempting a write; the GitHub SHA
+  check remains authoritative when concurrent submissions race.
+* {#s-k4g9ud <m-2wp6gd@585ee48} An answer submission with the same choice and
+  note as the already accepted answer is idempotent: it does not create a
+  conflict, and the accepted answer remains visible as answered. A submission
+  with a different choice or note is rejected and recorded as a conflict.
+* {#s-sjssy5 <arch} A conflicting submission is preserved in
+  `idd/conflicts.json` only when it can be committed without replacing an
+  existing accepted answer; if that conflict file also changed concurrently,
+  the viewer reloads the latest repository state and retries safely.
+* {#s-104mmm <m-umb15o@4ae4e2f,m-j48adi@77b2d25,m-hvgu3e@374ddc6} Revisiting an answered question and submitting a
+  different choice or note preserves the current answer and records the new
+  submission as a conflict. The conflict remains visible until the human
+  answers a clarification question; after that answer is recorded, the agent
+  marks the conflict resolved before carrying out the ruling.
+* {#s-aos2i9 <arch} Every file displayed in the viewer is
+  parsed as JSON and rendered using text nodes; no repository content is
+  inserted as HTML.
+
+## Repository data
+
+* {#s-rkulmb <m-7wyw60@f28d6e5} The GitHub repository is the durable
+  source of questionnaire and answer data; the IDD web application does not
+  keep a second durable copy of either.
+* {#s-34f36d <arch} For a code branch named `<branch>`, its questionnaire
+  data is stored on the Git branch `idd-<branch>`; the target branch's IDD
+  branch is named `idd-<target>`.
+* {#s-z4lb0p <arch} The stable identity of a code branch is the lowercase SHA-256
+  digest of the UTF-8 JSON serialization of `[String(repositoryId),
+  fullGitRef]`, where `fullGitRef` is `refs/heads/<branch>`.
+* {#s-r2o7ne <arch,m-q2caxw@e07030c} The hosted viewer accepts question ids computed
+  either with the reserved X option in the lowercase SHA-256 digest of the UTF-8
+  JSON serialization of `[question.branchHash, title, body, options]`, with each
+  option represented as `[key, text, tag-or-empty-string]`, or by the legacy
+  formula that omits the final reserved X option. It supplies X for display
+  without rewriting legacy question records.
+* {#s-ru06vn <arch} Questions with the same text created on different
+  code branches have different ids.
+* {#s-0399cx <arch} Each IDD branch stores its active questions in
+  `idd/questions.json`, accepted answers in `idd/answers.json`, rejected
+  answer conflicts in `idd/conflicts.json`, question history in
+  `idd/history.json`, and agent status in `idd/status.json`.
+* {#s-30veoz <arch} Each question record in `idd/questions.json` contains `id`,
+  its origin `branchHash`, `title`, `body`, `options`, and ISO 8601
+  `createdAt` fields; inherited questions retain the branch hash where each
+  was first created.
+* {#s-lzuk4v <arch} Each accepted answer in `idd/answers.json` contains `choice`,
+  `note`, and ISO 8601 `time` fields, keyed by question id.
+* {#s-kwn5lt <arch} Each conflict record in `idd/conflicts.json` contains `id`,
+  `questionId`, `choice`, `note`, `time`, and `submittedBy` string fields;
+  `id` uniquely identifies that rejected submission.
+* {#s-hgnnfg <arch} Each history record in `idd/history.json` contains a
+  removed or superseded `questionId`, a full `question` snapshot,
+  its replacement `replacedBy` question id, and an ISO 8601 `time` field.
+  Its accepted answer remains keyed by `questionId` in `idd/answers.json`.
+* {#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`
+  when it reports progress, and removes its entry when the session ends.
+* {#s-d3a5x5 <m-7wyw60@f28d6e5} The browser serializes a submitted answer
+  as JSON and sends it directly to GitHub to be committed on that project's
+  IDD branch.
+* {#s-7xztbp <m-4as0w8@cf65a99} To submit an answer, the browser uses a short-lived
+  GitHub App user access token; it can write only to repositories the app
+  installation and user both have permission to access.
+* {#s-sc65id <arch} An answer is accepted only if no answer has already
+  been committed for that question id; a rejected submission leaves the
+  accepted answer unchanged, records the rejected answer as a conflict, and
+  shows the accepted answer to the submitter.
+* {#s-6hexmx <m-awh12l@a1b5037} Repeating the same rejected answer from the same GitHub user for
+  the same question is idempotent: IDD does not append another conflict entry.
+  The viewer displays only one entry for repeated records with the same
+  question id, submitter, choice, and note.
+* {#s-kemef5 <arch} An accepted answer records its question id,
+  choice, note, and timestamp; the GitHub commit identifies the user who
+  submitted it.
+* {#s-zqz4wj <arch} A rejected answer conflict records the
+  question id, submitted answer, and timestamp; the GitHub commit identifies
+  the user who submitted it.
+* {#s-ewykyi <arch} Agent status records whether the agent is
+  blocked waiting for a human answer and when that status was last updated.
+
+## Text and credentials
+
+* {#s-e8zu22 <m-ol5xyr@2c772e6} Question titles, question bodies, option
+  text, submitted answers, and prior answers are displayed as text; the page
+  never interprets their contents as HTML.
+* {#s-m5duw4 <arch} The page keeps an access token only in memory
+  while the user is signed in; it does not put the token in questionnaire
+  data, answer data, local storage, or a URL.
+* {#s-0js03o <arch} The Cloud Run application holds the GitHub App
+  credential needed to exchange an authorization code, but it does not
+  receive questionnaire submissions or persist user access tokens in
+  server-side session storage.
+* {#s-v5f187 <arch} The user installs the GitHub App on repositories to add them to
+  the viewer; the app's user token can only access repositories the user
+  and the installation can access.
+* {#s-pot7wd <arch} The browser reads and commits questionnaire files through the
+  GitHub REST API, and the IDD application does not proxy those file contents.
+
+## Branch reconciliation
+
+* {#s-3980su <arch} Before completing a code-branch merge, the agent
+  merges the source IDD branch into the target IDD branch and compares their
+  question and answer records to identify duplicate, overlapping, and obsolete
+  questions.
+* {#s-ay10ju <arch} When related questions have answers that do not
+  establish one decision, the agent creates one clarifying question on the
+  target IDD branch, preserves the earlier records in its history, and waits
+  for that answer before implementing the decision and completing the merge.
+* {#s-xsxrgn <arch} When questions are duplicates or an earlier
+  question has been made obsolete, the target IDD branch presents the
+  consolidated or superseding question and retains links to the earlier
+  question and answer records.
+* {#s-8kd709 <arch} When IDD branches merge, the target's
+  `idd/page.json` keeps the target code branch's `branchHash`; each question
+  keeps the `branchHash` from the code branch where it was created unless the
+  agent replaces it with a new clarifying question.
+* {#s-fyoism <arch} A code-branch merge cannot complete until its source IDD history
+  is an ancestor of the target IDD branch and the agent has recorded a review
+  for the current code and IDD commits.
+* {#s-vwyasy <arch} The merge process keeps one active copy of
+  duplicate questions and records which earlier question ids it replaces.
+* {#s-3wklcj <arch} The merge process does not require ConcordSTC.
+
+## Dependencies
+
+* {#p-weocqk >specs/project-files.md} The project's question and answer
+  data.
+* {#p-21xm5l >specs/questions-page.md} The text displayed by the
+  questionnaire.
+* {#p-di8ysg >specs/idd-page.md} How the agent waits for an answer notification.
+* {#p-yjtzny >specs/build.md} How to build and deploy the Cloud Run web application.
+