riskrails 4.0.1 → 4.2.0

package/skills/rr-setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: rr-setup
-description: Set up and maintain the .ai/ layer of an existing production codebase. With no flag, scaffold docs/sdlc/, the runtime directory and .ai/, survey the code into .ai/project/ (light or full), write the Verification commands, the weight table's project entries and the constitution — read-only towards application code. --update regenerates a project's files from the installed plugin (a copy that is a shipped version is replaced, an edited one waits for the human, the project's own files are kept); run it right after installing a new riskrails; --audit scores the repository against the twelve plays and writes docs/ai-sdlc-adoption-plan.md. Use on "/rr-setup", "set up this project", "analyse this project for AI work", "update the rules", "обнови правилата", "audit our AI setup", or when /rr-status says the project is behind.
-argument-hint: [--survey light|full] | --update [--apply] | --audit [context]
+description: Set up and maintain the .ai/ layer of an existing production codebase. With no flag, scaffold docs/sdlc/, the runtime directory and .ai/, ask the open options (memory, runtimes, survey depth, verify command) in one dialog, survey the code into .ai/project/ (light or full), write the Verification commands, the weight table's project entries and the constitution — read-only towards application code. --options asks them all again; --update regenerates a project's files from the installed plugin (a copy that is a shipped version is replaced, an edited one waits for the human, the project's own files are kept); run it right after installing a new riskrails; --audit scores the repository against the twelve plays and writes docs/ai-sdlc-adoption-plan.md. Use on "/rr-setup", "set up this project", "analyse this project for AI work", "update the rules", "обнови правилата", "audit our AI setup", or when /rr-status says the project is behind.
+argument-hint: [--survey light|full] | --options | --update [--apply] | --audit [context]
 ---
 
 # /rr-setup $ARGUMENTS
@@ -17,29 +17,74 @@ UPDATE="python3 $AI_HOME/skills/project-update/update.py $PWD"
 SETUP="python3 $AI_HOME/skills/rr-setup/setup.py"
 ```
 
-`--update` and `--audit` go to their sections below; anything else
+`--options`, `--update` and `--audit` go to their sections below; anything else
 is **Setup**. In every mode: no application code changes — not a rename, not a
 formatting fix. Problems you find are written down, never fixed. Never read
 `.env`, secrets, dumps or production logs. Do not commit; suggest the `git add`.
 
 ## Setup
 
+0. **Options.** Project memory, the runtimes, the survey depth and `verify_command`
+   are asked once, in one dialog, before any work; the picks feed steps 1, 3 and 5.
+
+   ```bash
+   "$AI_HOME/skills/ai-init/scaffold-ai.sh" "$PWD" --runtime none   # 0a
+   $SETUP options --open    # 0b; --options adds --all, a given --survey adds --skip survey
+   ```
+
+   **0a** makes `.ai/` (so `.ai/policies/dialog.json`) and its `.gitignore` lines, with no
+   instruction file and no runtime directory; only this script takes `none`
+   (`project-scaffold.sh` refuses it). If its output does **not** list
+   `.ai/project/overview.md`, the project was set up before.
+
+   **0b** prints one of three first lines:
+   - `OPTIONS_DIALOG D<n> …`, then state.py's `DIALOG_PENDING` line and a JSON: send that
+     JSON exactly as printed with the dialog tool the line names (AskUserQuestion; Codex:
+     request_user_input).
+   - `OPTIONS_FALLBACK <why>`: nothing was opened. Ask the numbered questions after it in
+     chat as printed, the answers being the picks; show its `memory is the human's` line
+     as printed and never run it.
+   - `OPTIONS_NONE`: nothing to ask.
+
+   Exit 6 (no first line, the reason on stderr): `DECISION_LIMIT` or `DECISION_DUPLICATE`
+   means a decision is already open — settle every one first (`$STATE decision show` and
+   send it, or `$STATE decision fallback --id <Dn> --why "<why>"`), then run 0b once more.
+   Any other refusal, or a second one: ask the questions of steps 1, 3 and 5 in prose and,
+   in a git work tree, give the human for their own terminal, with `$AI_HOME` and `$PWD`
+   substituted: `python3 "<home>/skills/ai-task/state.py" --root "<project>" memory enable
+   --period quarter [--index sqlite]`.
+
+   **0c** — the human answers. After a dialog, a memory command they picked is run first,
+   at once, verbatim and alone; it prints `memory: via dialog (consent C<n>, decision D<n>)`
+   and its pick settles its decision. Then `$STATE decision settle --id <Dn>` for each other
+   decision: it prints `D<n> settled: <label> (set)` and `SETUP_PICK <key>=<value>`, after
+   a decline `SETUP_PICK <key>=`. Apply each pick where its step needs it:
+   - `runtime=<v>` → step 1's two scaffolds with `--runtime <v>`;
+   - `verify=<cmd>` → `$SETUP verify --set "<cmd>"` after step 2; `keep` and `edit` → nothing;
+   - `survey=light` or `full` → step 3's depth; `keep` → no new survey;
+   - `memory=off` or `keep` → nothing: a picked command already ran.
+
+   An empty value (`verify=` is "Not now"; any key after a decline) or `other` → the step
+   as it was without the dialog: step 1 passes `auto`, step 3 surveys `light`, step 5 asks
+   in chat.
 1. **Scaffold.** Both scripts are idempotent, never overwrite, and print what
-   they created; note it. They take `--runtime auto|claude|codex|both` (`auto`
-   follows `CLAUDE.md`/`.claude/` and `AGENTS.md`/`.codex/`); pass `both` when
-   the repository is worked on from both runtimes.
+   they created; note it, 0a's too. They take `--runtime auto|claude|codex|both`
+   (`auto` follows `CLAUDE.md`/`.claude/` and `AGENTS.md`/`.codex/`); pass the
+   `runtime` pick, else `auto` — `both` when the repository is worked on from
+   both runtimes.
 
    ```bash
-   "$AI_HOME/hooks/project-scaffold.sh" "$PWD"       # docs/sdlc/, the runtime dir, .gitignore
-   "$AI_HOME/skills/ai-init/scaffold-ai.sh" "$PWD"   # .ai/
+   "$AI_HOME/hooks/project-scaffold.sh" "$PWD" --runtime <pick>      # docs/sdlc/, the runtime dir, .gitignore
+   "$AI_HOME/skills/ai-init/scaffold-ai.sh" "$PWD" --runtime <pick>  # the instruction file; .ai/ is 0a's
    ```
 
-   If `.ai/project/overview.md` was **not** created, the project was set up
+   If 0a did **not** create `.ai/project/overview.md`, the project was set up
    before: run **--update** below, then ask whether the survey should be
    refreshed; a refresh never overwrites a `.ai/project/` file a human edited
-   without saying so first. If only an instruction file was created (no `.ai/`
-   wanted), fill its Commands / Conventions / Architecture from the manifests —
-   one line per command, five sentences of architecture — and stop.
+   without saying so first. If 0a and this step together created only an
+   instruction file (no `.ai/` wanted), fill its Commands / Conventions /
+   Architecture from the manifests — one line per command, five sentences of
+   architecture — and stop.
 2. **Stack.** `$SETUP survey` first: the project's own toolbox
    (`.claude/{skills,commands,rules,agents,hooks}`, `.codex/*`, `bin/*.sh`,
    Makefile targets) with each item's purpose, the guards a project hook
@@ -51,13 +96,15 @@ formatting fix. Problems you find are written down, never fixed. Never read
    (`phpunit.xml*`, `phpstan.neon*`, `playwright.config.*` …). For Symfony or
    Sylius also: bundles, entities, state machines, Messenger, event
    subscribers, payment, shipping, tax, promotions, ERP or fiscal integrations.
-3. **Survey.** `--survey light` is the default, for a developer who knows the
-   project: ask for a ten-minute brain dump (entry points, modules that matter,
-   integrations, unwritten business rules, areas nobody dares touch), confirm
+   Then write the `verify=<cmd>` pick, if any (0c).
+3. **Survey.** The depth is the `survey` pick or `--survey light|full`. `light`,
+   the default, is for a developer who knows the project: ask for a ten-minute
+   brain dump (entry points, modules that matter, integrations,
+   unwritten business rules, areas nobody dares touch), confirm
    each claim with `grep -n`, then fan out exactly **two** `ai-discovery` agents
    in one message: (1) legacy, risks and code that looks unused; (2) tests,
    CI/CD, data and configuration — how secrets are supplied, never their
-   values. `--survey full`, for a codebase new to you: one `Explore` for the
+   values. `full`, for a codebase new to you: one `Explore` for the
    inventory, then six `ai-discovery` agents in one message — entry points;
    domain modules; integrations and their failure handling; business rules and
    legacy; tests and CI/CD; data and configuration. Hand each the slice of the
@@ -68,14 +115,15 @@ formatting fix. Problems you find are written down, never fixed. Never read
    write `Documented behaviour / Observed behaviour / Evidence / Risk` and do
    not resolve it.
 5. **Policies.** Fill the project sections of `.ai/policies/coding.md` and
-   `testing.md` only if step 1 created them. The **Verification** block of
+   `testing.md` only if 0a created them. The **Verification** block of
    `testing.md` is the feedback loop every task runs:
    - `verify_command` — the fast suite to the end, the e2e group **excluded**;
    - `step_test_command` — the same runner on given paths (`{files}`);
    - `e2e_command` — the end-to-end suite, or `none` when there is none;
    - two or three lines of what healthy output looks like.
 
-   `verify_command` comes from the human: show the one `$SETUP survey`
+   `verify_command` comes from the human: the `verify=<cmd>` pick is their yes,
+   written at the end of step 2; without one, show the one `$SETUP survey`
    proposed, ask, and only after a yes in chat write it with
    `$SETUP verify --set "<command>"` (exit 3: one is already set — the human
    edits it). `$SETUP check` then exits 0; `VERIFY_COMMAND_MISSING` (exit 1)
@@ -109,14 +157,24 @@ formatting fix. Problems you find are written down, never fixed. Never read
    casually, the weight-table entries you chose, recommended next improvements —
    recommendations only, none implemented. When the survey found a toolbox,
    name each toolbox item the project keeps using; they stay where they are.
-9. **Report.** Files created (a tree from the scaffold output), surprising
+9. **Report.** Files created (a tree from the scaffold output, 0a's too), surprising
    findings, the modes and what puts a change in each, the safety restrictions
    in force (hooks versus policy), the tooling the workflows reuse, assumptions,
    unresolved questions and who can answer them, the survey's superpowers
    line as printed (the `enabledPlugins` line is the human's to add — never
    write it), and the suggested first task:
    `/rr-plan <it>`. Claim nothing was validated that was not run. Suggest
-   `git add .ai .gitignore docs/sdlc` plus the instruction files created.
+   `git add .ai .gitignore docs/sdlc` plus the instruction files created
+   (`.ai/memory/` and `.ai/reports/` are git-ignored; memory stays local unless the human runs
+   `memory enable --share git`).
+
+## --options
+
+Reopens every option on a set-up project: 0a, then `$SETUP options --open --all`, then
+send, settle and apply as in step 0 — a `survey` pick runs steps 3–4 at that depth, as a
+refresh (step 1), and a `verify` command is written at once. Say what changed and stop;
+no other step reruns. A project 0a just scaffolded (it listed
+`.ai/project/overview.md`) continues as the plain **Setup**.
 
 ## --update
 
@@ -187,7 +245,7 @@ riskrails is installed: until then the project's old shapes are not read.
    second machine runs the same before its next pull, else a modify/delete
    conflict); never run it yourself.
 7. `$UPDATE --check` and `git diff --stat`; say what changed, what you merged
-   and what is the human's. Suggest `git add -A .ai docs/sdlc .gitignore` plus
+   and what is the human's. Suggest `git add -A .ai docs/sdlc .gitignore` (the record and task logs are git-ignored) plus
    the runtime directories and instruction files.
 
 ## --audit

package/skills/rr-setup/scaffold_ai.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """Idempotent .ai/ scaffold for RiskRails.
-  scaffold_ai.py [project-dir] [--runtime auto|claude|codex|both]   (default: $PWD, auto)
+  scaffold_ai.py [project-dir] [--runtime auto|claude|codex|both|none]   (default: $PWD, auto)
 skills/ai-init/scaffold-ai.sh execs it; the templates stay in skills/ai-init/.
 
 Never overwrites an existing file. Run it as often as you like: it creates what
@@ -14,6 +14,10 @@ that points at it differs — CLAUDE.md for Claude Code, AGENTS.md for Codex.
 A port of the shell script it replaced, kept to its bytes: the same files and
 modes, the same listing in the same order, the same messages and exit codes
 (tests/test_scaffold_differential.py runs the frozen shell beside it).
+
+One value is new, and the shell refuses it: `--runtime none` (or AI_RUNTIMES=none) scaffolds .ai/ and its
+.gitignore lines and no instruction file, so /rr-setup can open .ai/ before the project's runtimes are chosen.
+Like `both` and `auto` it is a whole value: inside a list it is an unknown runtime, as in the shell.
 """
 import errno
 import json
@@ -143,7 +147,9 @@ def logical_cd(root):
 
 
 def runtimes(runtime, root):
-    """The runtimes in scope: what the project declares (auto), or the list given."""
+    """The runtimes in scope: what the project declares (auto), the list given, or none at all."""
+    if runtime == "none":
+        return set()
     if runtime == "both":
         runtime = "claude,codex"
     if runtime == "auto":

package/skills/rr-setup/setup.py

@@ -5,21 +5,33 @@ and whether superpowers is on (spec R9, R28, SQ5, SQ12 variant B).
   setup.py survey [--root DIR]              the toolbox, the proposed verify_command, the superpowers line
   setup.py check  [--root DIR]              exit 1 VERIFY_COMMAND_MISSING unless verification.md names one
   setup.py verify [--root DIR] --set CMD    write verify_command into verification.md (after the human confirmed)
-
-survey and check write nothing. The toolbox is production behaviour (C1): it is
+  setup.py options [--root DIR] [--all] [--skip KEY]… --json
+                                            what each of the four setup options is now, as one JSON object
+  setup.py options [--root DIR] [--all] [--skip KEY]… --open
+                                            the unset ones as one dialog. First line: OPTIONS_DIALOG D<n> …
+                                            (then state.py's two lines), OPTIONS_FALLBACK <why> (the questions
+                                            as prose) or OPTIONS_NONE
+
+--skip KEY (memory|runtime|survey|verify, repeatable) leaves that option out of what is asked, for both outputs and
+with --all; its entry in the --json facts stays. survey, check and options --json write nothing; options --open
+writes only the decisions state.py opens, none in the fallback. The toolbox is production behaviour (C1): it is
 inventoried in place, never copied or moved; what to inventory is the constants
 FOREIGN_ROOTS and OWN_* below.
 The enabledPlugins line is printed, never written: .claude/settings.json is the
 human's.
 
 Exit codes: 0 done; 1 VERIFY_COMMAND_MISSING; 2 usage;
-3 refused (the line is already set).
+3 refused (the line is already set); 6 state.py refused to open the dialog (its message is passed through).
 """
 import argparse
+import hashlib
+import importlib
 import json
 import os
 import re
+import shlex
 import shutil
+import subprocess
 import sys
 
 HERE = os.path.dirname(os.path.abspath(__file__))
@@ -31,6 +43,20 @@ UNKNOWN = "UNKNOWN — no description and no leading comment"
 VERIFY_RE = re.compile(r"(?m)^verify_command:[ \t]*(.*)$")
 MAKE_TARGET_RE = re.compile(r"^([A-Za-z0-9][A-Za-z0-9_. \t-]*?)\s*:(?![=:])(.*)$")
 BLOCK_SCALAR_RE = re.compile(r"^[|>][-+]?$")
+PENDING_RE = re.compile(r"DIALOG_PENDING ((?:D\d+ )*D\d+) — ")   # state.py's first line: the decisions it opened
+# `options`: the sibling skills, the state.py of this install (the one the dialog's commands name), the files the
+# survey signal compares, and the signals that scaffold_ai.runtimes() reads for `--runtime auto` as (instruction
+# file, runtime directory).
+SKILLS = os.path.dirname(HERE)
+AI_TASK = os.path.join(SKILLS, "ai-task")
+STATE_PY = os.path.join(AI_TASK, "state.py")
+OPTION_KEYS = ("memory", "runtime", "survey", "verify")      # the four options, in the order they are asked
+OVERVIEW = os.path.join(".ai", "project", "overview.md")
+OVERVIEW_TEMPLATE = os.path.join(SKILLS, "ai-init", "templates", OVERVIEW)
+HISTORY_INDEX = os.path.join(SKILLS, "project-update", "history", "index.json")
+HISTORY_KEY = "ai-init/.ai/project/overview.md"
+RUNTIME_SIGNALS = {"claude": ("CLAUDE.md", ".claude"), "codex": ("AGENTS.md", ".codex"),
+                   "gemini": ("GEMINI.md", ".gemini"), "junie": (None, ".junie")}
 # Paths a foreign AI tool owns (Spec Kit, Kiro, AI-DLC, Cursor, Copilot): no part of the project's own toolbox.
 FOREIGN_ROOTS = [
     ".specify/",
@@ -113,6 +139,14 @@ def read_text(path):
         return None
 
 
+def read_bytes(path):
+    try:
+        with open(path, "rb") as fh:
+            return fh.read()
+    except OSError:
+        return None
+
+
 def is_crlf(path):
     try:
         with open(path, "rb") as fh:
@@ -402,6 +436,305 @@ def write(path, text):
             os.remove(tmp)
 
 
+# ------------------------------------------------------------------ options
+
+def sibling(directory, name):
+    """A module of this skill or of another, imported once its directory leads sys.path: `python3 -I` puts none
+    there, and the module's own imports are by name (memory_export reaches memory_compact that way). Skills are
+    installed independently, so a missing module is an ImportError for the caller to answer."""
+    if directory not in sys.path:
+        sys.path.insert(0, directory)
+    sys.dont_write_bytecode = True  # a read-only verb leaves no __pycache__ in the install
+    return importlib.import_module(name)
+
+
+def digest(data):
+    """sha256 with LF line ends, as update.py's History.shipped reads a file a CRLF checkout changed."""
+    return hashlib.sha256(data.replace(b"\r\n", b"\n")).hexdigest()
+
+
+def in_git_tree(root):
+    try:
+        done = subprocess.run(["git", "-C", root, "rev-parse", "--is-inside-work-tree"],
+                              capture_output=True, text=True, check=False)
+    except OSError:  # no git binary
+        return False
+    return done.returncode == 0 and done.stdout.strip() == "true"
+
+
+def dialog_on(root):
+    """state.py's own answer (`consent --json`): the project's dialog.json on, the runtime's dialog tool verified and
+    a session id in this environment. False without dialog.json and when state.py cannot answer."""
+    if not os.path.isfile(os.path.join(root, ".ai", "policies", "dialog.json")):
+        return False
+    try:
+        done = subprocess.run([sys.executable, "-I", "-B", os.path.join(AI_TASK, "state.py"), "--root", root,
+                               "consent", "--json"], capture_output=True, text=True, check=False)
+        data = json.loads(done.stdout) if done.returncode == 0 else None
+    except (OSError, ValueError):
+        return False
+    return isinstance(data, dict) and data.get("dialog") is True
+
+
+def author_source(cfg):
+    """Where `cfg.author` comes from, in the order memory_config.MemoryConfig.author tries them."""
+    if cfg.local.get("author"):
+        return "local config"
+    return next(("$" + name for name in ("USER", "USERNAME") if os.environ.get(name)), "default")
+
+
+def fts5():
+    """FTS5 in this Python's sqlite3, by memory_store's own probe (AI_MEMORY_NO_FTS=1 turns it off);
+    False without the sqlite3 module."""
+    try:
+        return sibling(AI_TASK, "memory_store").fts5_available()
+    except ImportError:
+        return False
+
+
+def memory_option(root, git):
+    """Packages-mode project memory: set once memory.json exists, its mode being `current`. `author` is what
+    `memory enable` writes without --author (the local config, else $USER): memory_config's own answer, never git's."""
+    def unavailable(why):
+        return {"key": "memory", "state": "unavailable", "why": why}
+    if not git:
+        return unavailable("not a git work tree")
+    try:
+        memory_config = sibling(AI_TASK, "memory_config")
+        memory_io = sibling(AI_TASK, "memory_io")
+    except ImportError as exc:
+        return unavailable("the memory modules are not installed beside state.py (%s)" % exc)
+    try:
+        cfg = memory_config.load_config(root)
+    except memory_io.MemoryError_ as exc:
+        return unavailable(str(exc))
+    return {"key": "memory", "state": "set" if cfg.present else "unset", "current": cfg.mode if cfg.present else None,
+            "author": cfg.author, "author_from": author_source(cfg),
+            "period": None if cfg.present else memory_config.DEFAULTS["period"], "fts5": fts5()}
+
+
+def runtime_option(root):
+    """`declared`: the runtimes the repository already names, by the signals scaffold_ai.runtimes() reads.
+    `auto`: what `--runtime auto` would scaffold now, as that function resolves it, in the spelling --runtime takes."""
+    declared = [name for name, (instruction, directory) in RUNTIME_SIGNALS.items()
+                if (instruction and os.path.exists(os.path.join(root, instruction)))
+                or os.path.isdir(os.path.join(root, directory))]
+    scaffold = sibling(HERE, "scaffold_ai")
+    chosen = scaffold.runtimes("auto", root)
+    return {"key": "runtime", "state": "set" if declared else "unset", "declared": declared,
+            "auto": ",".join(name for name in scaffold.RUNTIMES if name in chosen)}
+
+
+def surveyed(root):
+    """No depth is recorded anywhere. A survey fills .ai/project/overview.md, so a copy that is none of the files
+    the plugin shipped for it (today's template, or a version in project-update's history index: update.py's
+    own test for an unedited file) has been written into."""
+    mine = read_bytes(os.path.join(root, OVERVIEW))
+    if mine is None:
+        return False
+    shipped = set()
+    template = read_bytes(OVERVIEW_TEMPLATE)
+    if template is not None:
+        shipped.add(digest(template))
+    try:
+        shipped.update(json.loads(read_text(HISTORY_INDEX) or "{}")[HISTORY_KEY])
+    except (ValueError, KeyError, TypeError):
+        pass
+    return digest(mine) not in shipped
+
+
+def verify_option(root):
+    """Set by check's own rule (a value that is not `none`); else the proposal `survey` makes, and the others."""
+    current = verify_value(root)
+    if current and current.lower() != "none":
+        return {"key": "verify", "state": "set", "current": current}
+    found = [{"command": command, "from": source} for command, source in verify_candidates(root)]
+    return {"key": "verify", "state": "unset", "proposal": found[0] if found else None, "also": found[1:]}
+
+
+def option_facts(root, show_all=False, skip=()):
+    """What each of the four setup options is now, read-only (spec interactive-setup-options R9, R16). `ask` lists
+    the unset ones in the order memory, runtime, survey, verify; `show_all` lists every one not unavailable; `skip`
+    leaves keys out of it that the caller has answered another way (/rr-setup --survey). The facts of a skipped
+    option stay as computed: they are still true, and only what is asked changes."""
+    git = in_git_tree(root)
+    options = [memory_option(root, git), runtime_option(root),
+               {"key": "survey", "state": "set" if surveyed(root) else "unset"}, verify_option(root)]
+    return {"schema": 1, "root": root, "git": git, "dialog": dialog_on(root),
+            "ask": [o["key"] for o in options if o["key"] not in skip
+                    and (o["state"] == "unset" or (show_all and o["state"] == "set"))],
+            "options": options}
+
+
+# ------------------------------------------------------------ options --open
+
+def state_label(root, *words):
+    """The command that runs this install's state.py with `words` on this project, absolute and quoted as
+    rr_state.labels.state_label writes it: a pick and the call the agent makes are then one string. A copy, not an
+    import: rr_state.fs.ENTRY is only set by state.py's own entry."""
+    return "python3 %s %s" % (shlex.quote(STATE_PY), shlex.join(["--root", root, *words]))
+
+
+def choice_option(label, value):
+    return {"kind": "choice", "label": label, "value": value}
+
+
+def command_option(label, description):
+    return {"kind": "command", "label": label, "description": description}
+
+
+def shown(text):
+    """`text` inside backticks, as a label shows a command, or None when the opener would refuse it: a backtick of its
+    own ends the span early, and a choice value is at most 200 printable characters (dialog_cmd.SETUP_VALUE_MAX), so
+    that "Use `…`" stays inside the labels' 400."""
+    return "`%s`" % text if text and "`" not in text and len(text) <= 200 and text.isprintable() else None
+
+
+def decision(key, question, options):
+    return {"key": key, "header": key.capitalize(), "question": question, "options": options}
+
+
+def memory_decision(option, root, name):
+    """Memory is asked first, so that its pick is the earliest the gate passes (spec B3). Its commands are `memory
+    enable` of this install's state.py: --period only while memory.json is absent (`period` is then set), never
+    --author, because enable writes the author the question names (D1): the local config's, else $USER's."""
+    period = ["--period", option["period"]] if option["period"] else []
+    who = "Author %s (from %s)" % (option["author"], option["author_from"])
+    if option["state"] == "set":
+        first = choice_option("Keep — %s mode" % option["current"], "keep")
+        question = ("Project memory for %s is in %s mode: off keeps closed tasks only in .ai/reports/. packages also writes "
+                    "one compact file per developer per period under .ai/memory/; both stay local (git-ignored) unless you "
+                    "run 'state.py memory enable --share git' in your own terminal. %s. Keep it, or run memory enable?" % (name, option["current"], who))
+    else:
+        first = choice_option("Off — keep files mode", "off")
+        question = ("Project memory for %s: off keeps closed tasks only in .ai/reports/. packages also writes one compact "
+                    "file per developer per %s under .ai/memory/; both stay local (git-ignored) unless you run "
+                    "'state.py memory enable --share git' in your own terminal. %s, period %s. Turn it on?" % (name, option["period"], who, option["period"]))
+    return decision("memory", question, [
+        first,
+        command_option(state_label(root, "memory", "enable", *period),
+                       "packages; local, git-ignored record under .ai/memory/"),
+        command_option(state_label(root, "memory", "enable", *period, "--index", "sqlite"),
+                       "plus a local, git-ignored SQLite index; FTS5 %s — without it search scans: same results, slower"
+                       % ("yes" if option["fts5"] else "no"))])
+
+
+def runtime_decision(option, name):
+    """No "Not now": the four runtimes use all the options a question has. `auto` names what it resolves to: the
+    runtime this copy is installed for while the repository declares none, else what it declares."""
+    auto = "Auto — what the repository declares"
+    auto += " (%s)" % option["auto"] if option["declared"] else ", else %s" % option["auto"]
+    return decision("runtime", "Which agent runtimes work on %s? The scaffold adds their instruction files and directories "
+                               "and never removes one." % name,
+                    [choice_option(auto, "auto"), choice_option("Claude Code only", "claude"),
+                     choice_option("Codex only", "codex"), choice_option("Claude Code and Codex", "both")])
+
+
+def survey_decision(option, name):
+    options = [choice_option("Light — your 10-minute brain dump + 2 discovery agents", "light"),
+               choice_option("Full — inventory + 6 discovery agents", "full")]
+    if option["state"] == "set":
+        options.append(choice_option("Keep the current survey", "keep"))
+    return decision("survey", "How deep should the first survey of %s go?" % name, options)
+
+
+def verify_decision(option):
+    """Unset: not now, the proposal, at most one other candidate, or typed in chat (a free-text answer is a decline,
+    so a command of the human's own is typed after the dialog: spec A3). A command the opener would refuse is not
+    offered. Set (--all): keep it, or edit it by hand — verify_command is the human's once written."""
+    intro = "verify_command — the fast suite every task runs, e2e excluded."
+    if option["state"] == "set":
+        current = shown(option["current"])
+        return decision("verify", "%s Current: %s." % (intro, current or "set in .ai/policies/verification.md"),
+                        [choice_option("Keep %s" % current if current else "Keep the current command", "keep"),
+                         choice_option("Change — I edit it myself", "edit")])
+    proposal = [option["proposal"]] if option["proposal"] and shown(option["proposal"]["command"]) else []
+    also = [c for c in option["also"] if shown(c["command"])][:1]
+    found = proposal + also
+    options = [choice_option("Not now — ask me in chat", "")]
+    options += [choice_option("Use %s" % shown(c["command"]), c["command"]) for c in found]
+    options.append(choice_option("Another — I type it in chat", "other"))
+    proposed = ("Proposed: %s (from %s)." % (shown(found[0]["command"]), found[0]["from"]) if found
+                else "No proposal: nothing found in the project's files.")
+    return decision("verify", "%s %s" % (intro, proposed), options)
+
+
+def decision_for(option, root, name):
+    if option["key"] == "memory":
+        return memory_decision(option, root, name)
+    if option["key"] == "runtime":
+        return runtime_decision(option, name)
+    if option["key"] == "survey":
+        return survey_decision(option, name)
+    return verify_decision(option)
+
+
+def dialog_off_why(root):
+    """Why state.py's switch is off here, as the first cause found in the order it tests them: the project's
+    dialog.json, an unattended run or session, then the two it cannot be told apart by from here (the runtime's dialog
+    tool the installer verified, a session id)."""
+    try:
+        with open(os.path.join(root, ".ai", "policies", "dialog.json"), encoding="utf-8") as fh:
+            enabled = (json.load(fh) or {}).get("enabled") is True
+    except (OSError, ValueError, AttributeError):
+        enabled = False
+    if not enabled:
+        return "no enabled .ai/policies/dialog.json"
+    if os.environ.get("AI_UNATTENDED", "").strip().lower() not in ("", "0", "false", "no"):
+        return "AI_UNATTENDED is set (an unattended run)"
+    if os.environ.get("CLAUDE_CODE_SESSION_ATTENDED") == "0":
+        return "CLAUDE_CODE_SESSION_ATTENDED=0 (an unattended session)"
+    return "the runtime's dialog tool is not verified (riskrails/profile.json dialog.tool) or this session has no id"
+
+
+def open_dialog(root, decisions):
+    """The decisions piped to this install's state.py, which opens all of them or none. Returns (exit code, None) once
+    it answered: 0 with OPTIONS_DIALOG and its two lines unchanged, 6 with its refusal passed through (the skill
+    settles what is open first, or falls back); (None, why) when it found the dialog off after all, for the fallback."""
+    spec = json.dumps({"schema": 1, "decisions": decisions})           # ASCII only: no locale decides how it is read
+    try:
+        done = subprocess.run([sys.executable, "-I", "-B", "-X", "utf8", STATE_PY, "--root", root, "decision", "open",
+                               "--kind", "setup", "--spec", "-"],
+                              input=spec, capture_output=True, encoding="utf-8", errors="replace", check=False)
+    except OSError as exc:
+        sys.stderr.write("setup.py: cannot run %s (%s)\n" % (STATE_PY, exc))
+        return 6, None
+    if done.returncode == 1:              # its die() default: the dialog off after all, or a decision.json it cannot read
+        last = ([line for line in done.stderr.splitlines() if line.strip()] or ["no message"])[-1]
+        text = " ".join(last.replace(root + os.sep, "").replace("state.py: ", "", 1).split())
+        return None, "state.py could not open the dialog: %s" % (text if len(text) <= 200 else text[:199] + "…")
+    if done.returncode != 0:
+        sys.stderr.write(done.stderr or "setup.py: state.py exited %d without a message\n" % done.returncode)
+        return 6, None
+    ids = PENDING_RE.match(done.stdout.split("\n", 1)[0])
+    if not ids:
+        sys.stderr.write("setup.py: state.py answered with no DIALOG_PENDING line; 'state.py decision show' lists "
+                         "what it opened\n")
+        return 6, None
+    sys.stderr.write(done.stderr)
+    print("OPTIONS_DIALOG %s" % ids.group(1))
+    sys.stdout.write(done.stdout)
+    return 0, None
+
+
+def fallback_lines(root, why, decisions):
+    """The questions as numbered prose, in the dialog's words (a command is its arguments after the project's root, and
+    its description), then, when memory is asked, the command the human runs: nothing is enabled from here, and
+    nothing is written."""
+    prefix = state_label(root) + " "
+    lines = ["OPTIONS_FALLBACK %s" % why]
+    for number, item in enumerate(decisions, 1):
+        lines.append("%d. %s: %s" % (number, item["header"], item["question"]))
+        lines += ["   %s) %s" % (letter, o["label"] if o["kind"] == "choice"
+                                  else "%s — %s" % (o["label"][len(prefix):], o["description"]))
+                  for letter, o in zip("abcd", item["options"])]
+    memory = next((d for d in decisions if d["key"] == "memory"), None)
+    if memory:
+        enable = next(o["label"] for o in memory["options"] if o["kind"] == "command")
+        lines.append("memory is the human's, in their own terminal: %s [--index sqlite]" % enable)
+    return lines
+
+
 # ----------------------------------------------------------------- commands
 
 def cmd_survey(root):
@@ -456,14 +789,45 @@ def cmd_verify(root, command):
     return 0
 
 
+def cmd_options(root, show_all, skip):
+    print(json.dumps(option_facts(root, show_all, skip), ensure_ascii=False))
+    return 0
+
+
+def cmd_options_open(root, show_all, skip):
+    """R10, R17: nothing to ask → OPTIONS_NONE; the dialog on → the questions opened through state.py; else the
+    questions as prose. Memory is only ever in `ask` inside a git work tree (R16)."""
+    facts = option_facts(root, show_all, skip)
+    if not facts["ask"]:
+        print("OPTIONS_NONE")
+        return 0
+    name = os.path.basename(root) or root
+    by_key = {o["key"]: o for o in facts["options"]}
+    decisions = [decision_for(by_key[key], root, name) for key in facts["ask"]]
+    if facts["dialog"]:
+        code, why = open_dialog(root, decisions)
+        if code is not None:
+            return code
+    else:
+        why = dialog_off_why(root)
+    print("\n".join(fallback_lines(root, why, decisions)))
+    return 0
+
+
 def main(argv=None):
     parser = argparse.ArgumentParser(prog="setup.py", description=__doc__.split("\n\n", 1)[0])
     sub = parser.add_subparsers(dest="cmd", required=True)
-    for name in ("survey", "check", "verify"):
+    for name in ("survey", "check", "verify", "options"):
         p = sub.add_parser(name)
         p.add_argument("--root", default=".")
         if name == "verify":
             p.add_argument("--set", dest="command", required=True)
+        if name == "options":
+            p.add_argument("--all", action="store_true")
+            p.add_argument("--skip", action="append", default=[], choices=OPTION_KEYS)
+            output = p.add_mutually_exclusive_group(required=True)
+            output.add_argument("--json", action="store_true")
+            output.add_argument("--open", action="store_true")
     args = parser.parse_args(argv)
     root = os.path.abspath(args.root)
     if not os.path.isdir(root):
@@ -472,6 +836,9 @@ def main(argv=None):
         return cmd_survey(root)
     if args.cmd == "check":
         return cmd_check(root)
+    if args.cmd == "options":
+        run = cmd_options if args.json else cmd_options_open
+        return run(root, args.all, args.skip)
     return cmd_verify(root, args.command)