@jstn-sdk/rcs 0.1.0

package/docs/codex-native-hooks.md

@@ -0,0 +1,153 @@
+# Codex native hook mapping
+
+This page is the canonical answer to:
+
+> Which OMC/RCS hooks run on native Codex hooks already, which stay on runtime fallbacks, and which are not supported yet?
+
+## Install surface
+
+`rcs setup` now owns both of these native Codex artifacts:
+
+- `.codex/config.toml` → enables `[features].codex_hooks = true`
+- `.codex/hooks.json` → registers the RCS-managed native hook command while preserving non-RCS hook entries already in the file
+
+For project scope, `.gitignore` keeps generated `.codex/hooks.json` out of source control.
+`rcs uninstall` removes only the RCS-managed wrapper entries from `.codex/hooks.json`; if user hooks remain, the file stays in place.
+
+`rcs doctor` can confirm that these files exist and are shaped correctly. It does not prove that the same shell/profile can complete an authenticated Codex request; use `codex login status` plus a real `rcs exec --skip-git-repo-check -C . "Reply with exactly RCS-EXEC-OK"` smoke test for that boundary.
+
+## Ownership split
+
+- **Native Codex hooks**: `.codex/hooks.json`
+- **RCS plugin hooks**: `.rcs/hooks/*.mjs`
+- **tmux/runtime fallbacks**: `rcs tmux-hook`, notify-hook, derived watcher, idle/session-end reporters
+
+RCS only owns the wrapper entries that invoke `dist/scripts/codex-native-hook.js`. User-managed hook entries in the same `.codex/hooks.json` file are preserved across `rcs setup` refreshes and `rcs uninstall`.
+
+## Mapping matrix
+
+| OMC / RCS surface | Native Codex source | RCS runtime target | Status | Notes |
+| --- | --- | --- | --- | --- |
+| `session-start` | `SessionStart` | `session-start` | native | Native adapter refreshes leader session bookkeeping, preserves the canonical leader scope when a native subagent `SessionStart` is detected from rollout `session_meta`, restores startup developer context, and ensures `.rcs/` is gitignored at the repo root |
+| wiki startup context | `SessionStart` | `session-start` | native | Wiki session-start context can append a compact `.rcs/wiki/` summary when wiki pages exist; startup writes stay config-gated |
+| `keyword-detector` | `UserPromptSubmit` | `keyword-detector` | native | Persists skill activation state and can add prompt-side developer context; `$ralph` prompt routing seeds workflow state only and does not launch `rcs ralph --prd ...` |
+| `pre-tool-use` | `PreToolUse` (`Bash`) | `pre-tool-use` | native-partial | Current native scope is Bash-only; built-in native behavior cautions on `rm -rf dist`, blocks inspectable inline `git commit` commands until Lore-format structure + the required `Co-authored-by: RCS <rcs@roblox-ai-os.dev>` trailer are present, and emits non-blocking document-refresh warnings for mapped staged commit changes that lack rule-scoped docs/spec refresh evidence |
+| `post-tool-use` | `PostToolUse` (`Bash`) | `post-tool-use` | native-partial | Current native scope is Bash-only; built-in native behavior covers command-not-found / permission-denied / missing-path guidance only from stderr or non-zero Bash results, ignores failure-looking strings from successful source/log reads, and keeps MCP transport-death guidance scoped to MCP-like tool calls; document-refresh commit warnings use PreToolUse advisory output, with PostToolUse reserved as a future fallback if Codex advisory semantics change |
+| Ralph/persistence stop handling | `Stop` | `stop` | native-partial | Native adapter uses the documented native Stop continuation contract (`decision: "block"` + `reason`) for active Ralph runs, emits a single JSON object on Stop stdout even for no-op Stop decisions, and emits deterministic JSON continuation output if Stop dispatch fails before normal handling |
+| Autopilot continuation | `Stop` | `stop` | native-partial | Native adapter continues non-terminal autopilot sessions from active session/root mode state |
+| Ultrawork continuation | `Stop` | `stop` | native-partial | Native adapter continues non-terminal ultrawork sessions from active session/root mode state |
+| UltraQA continuation | `Stop` | `stop` | native-partial | Native adapter continues non-terminal ultraqa sessions from active session/root mode state |
+| Team-phase continuation | `Stop` | `stop` | native-partial | Native adapter treats per-team `phase.json` as canonical when deciding whether a current-session team run is still non-terminal and can re-block on later fresh Stop replies while keeping leader guidance explicit about rewriting system-generated worker auto-checkpoint commits into Lore-format final history |
+| `ralplan` skill-state continuation | `Stop` | `stop` | native-partial | Native adapter can block on active `skill-active-state.json` for `ralplan`, unless active subagents are already the real in-flight owners |
+| `deep-interview` skill-state continuation | `Stop` | `stop` | native-partial | Native adapter can block on active `skill-active-state.json` for `deep-interview`, unless active subagents are already the real in-flight owners |
+| auto-nudge continuation | `Stop` | `stop` | native-partial | Native adapter continues turns that end in a permission/stall prompt, can re-fire for later fresh replies, and suppresses auto-nudge while interview / deep-interview state is active; explicit terminal lifecycle metadata should be authoritative when present, legacy `blocked_on_user` remains a suppress-continuation compatibility signal, and `cancelled` stays internal legacy-only for user-facing lifecycle summaries |
+| `ask-user-question` | none | runtime-only | runtime-fallback | No distinct Codex native hook today |
+| `PostToolUseFailure` | none | runtime-only | runtime-fallback | Fold into runtime/fallback handling until native support exists |
+| non-Bash tool interception | none | runtime-only | runtime-fallback | Current Codex native tool hooks expose Bash only |
+| code simplifier stop follow-up | none | runtime-only | runtime-fallback | Cleanup follow-up stays on runtime/fallback surfaces, not native Stop |
+| `SubagentStop` | none | runtime-only | not-supported-yet | OMC-specific lifecycle extension |
+| `session-end` | none | `session-end` | runtime-fallback | Still emitted from runtime/notify path, not native Codex hooks |
+| wiki session capture | none | `session-end` | runtime-fallback | Wiki session-log capture runs from the existing runtime session-end cleanup path, not from a native Codex hook |
+| `session-idle` | none | `session-idle` | runtime-fallback | Still emitted from runtime/notify path, not native Codex hooks |
+
+
+## Document-refresh warning MVP
+
+The native hook adapter includes an agent-only document-refresh warning MVP for
+spec-driven development hygiene. It does **not** install a generic CI gate, does
+**not** add a repo-wide pre-commit framework, and must not hard-block `git
+commit` for document-refresh reasons. Existing Lore commit blocking remains
+separate and still wins when an inline commit message is not Lore-compliant.
+
+Warning scope is intentionally narrow and rule-scoped:
+
+- **Commit path:** `PreToolUse` is Bash-only in this MVP and evaluates only
+  inspectable `git commit` commands. It reads `git diff --cached --name-status`,
+  so only staged changes count. Staged product docs such as
+  `docs/codex-native-hooks.md` can suppress a native-hook rule warning.
+  Rule-owned `.rcs/plans/**` and `.rcs/specs/**` targets suppress commit-path
+  warnings only when they are tracked or force-staged despite `.rcs/` being
+  gitignored. Local-only ignored planning files do not suppress commit warnings.
+- **Final handoff path:** `Stop` evaluates only terminal-looking final handoff
+  attempts, after active-mode blockers and auto-nudge recovery. It reads staged
+  plus unstaged diffs and can count fresh local rule-owned `.rcs/plans/**` or
+  `.rcs/specs/**` files when their mtimes are newer than the mapped source
+  change. This is an agent-local heuristic freshness check for final handoff,
+  not commit evidence or proof of semantic refresh.
+- **Mappings:** rules live in `src/document-refresh/config.ts`; unrelated doc
+  or `.rcs` edits do not suppress warnings for another rule. Initial rules cover
+  native hook behavior, document-refresh enforcer behavior, CLI/operator
+  behavior, and prompt-guidance behavior only.
+- **Exclusions:** tooling-only changes, release collateral, rename-only changes,
+  and explicitly ignored non-user-facing internal tests are ignored
+  conservatively. Ambiguous refactors should use the explicit exemption if no
+  product/spec refresh is needed.
+
+To acknowledge a legitimate no-refresh case, include this exact line in the
+commit message or final handoff text with a concrete reason:
+
+```text
+Document-refresh: not-needed | <reason>
+```
+
+The warning output names the mapped triggering path(s) and expected refresh
+target group(s), so agents can refresh the right product docs or planning specs
+instead of using an unrelated docs edit as a blanket suppression.
+
+## Project wiki addendum (approved v1 backport)
+
+The approved RCS-native wiki backport keeps lifecycle ownership intentionally narrow:
+
+- **Storage** lives under `.rcs/wiki/`, not `.omc/wiki/`.
+- **SessionStart** may surface bounded wiki context from `.rcs/wiki/` when the wiki already exists, but it should stay read-mostly and must not block the native hook path on expensive writes or index rebuilds.
+- **SessionEnd** remains a runtime/notify-path responsibility for best-effort, non-blocking session capture into `.rcs/wiki/`.
+- **PreCompact parity is intentionally deferred** in v1 unless a clearly RCS-native compaction seam exists.
+- **Routing should stay explicit**: prefer `$wiki` or task verbs like `wiki query` / `wiki add`, and avoid implicit bare `wiki` noun activation.
+
+## Explicit terminal stop model note
+
+The approved explicit terminal stop model adds a canonical lifecycle layer for active workflow handoffs:
+
+- `finished`
+- `blocked`
+- `failed`
+- `userinterlude`
+- `askuserQuestion`
+
+Hook readers should prefer explicit lifecycle metadata over assistant-text heuristics when those signals are available.
+During migration, legacy `blocked_on_user` still suppresses continuation, but `cancelled` should be treated as internal legacy/admin compatibility rather than a canonical user-facing outcome.
+
+There is still no distinct native Codex `ask-user-question` hook today. That means `askuserQuestion` classification remains a runtime/fallback responsibility unless a future native hook surface exposes first-class question-stop metadata.
+
+## Combined workflow note
+
+Stop/continuation readers must interpret approved combined workflow state from
+the shared active-set contract rather than from a single legacy `skill` owner.
+For the first-pass multi-state rollout, the approved overlaps are:
+
+- `team + ralph`
+- `team + ultrawork`
+
+Unsupported overlaps should preserve the current state unchanged and direct the
+operator to clear incompatible state explicitly via `rcs state ...` or the
+`rcs_state.*` MCP tools before retrying. See
+`docs/contracts/multi-state-transition-contract.md`.
+
+## UserPromptSubmit: triage advisory context
+
+`UserPromptSubmit` can now emit triage advisory context alongside keyword context. When no keyword matches, the triage layer classifies the prompt and may inject an advisory prompt-routing context string — this is advisory prompt-routing context that does not activate a skill or workflow by itself; it adds a developer-context hint the model may follow. Light advisory destinations include repo-local `explore`, narrow-edit `executor`, visual `designer`, and external documentation/reference `researcher`; researcher routing is for official-doc, version-compatibility, source-backed, or external lookup requests, does not override local anchors or implementation-shaped prompts, and still writes only prompt-routing state. Keywords remain the deterministic control surface: a matched keyword always takes precedence over triage output, and users can suppress triage injection per prompt with phrases such as `no workflow`, `just chat`, or `plain answer`.
+
+## Verification guidance
+
+When validating hooks, keep the proof boundary explicit:
+
+1. **Native Codex hook proof**
+   - `rcs setup` wrote `.codex/hooks.json`
+   - native Codex event invoked `dist/scripts/codex-native-hook.js`
+2. **RCS plugin proof**
+   - plugin dispatch/log evidence exists under `.rcs/logs/hooks-*.jsonl`
+3. **Fallback proof**
+   - behavior came from notify-hook / derived watcher / tmux runtime, not native Codex hooks
+
+Do not claim “native hooks work” when only tmux or synthetic notify fallback paths were exercised.
+Likewise, do not claim real execution readiness from hook/install evidence alone; validate an actual Codex execution in the active runtime profile when diagnosing auth or provider issues.

package/docs/contracts/autoresearch-command-contract.md

@@ -0,0 +1,106 @@
+# `rcs autoresearch` parity contract
+
+`rcs autoresearch` is a thin supervisor that drives one Codex experiment session per iteration while RCS owns the durable keep/discard/reset loop.
+
+## CLI
+
+```bash
+rcs autoresearch <mission-dir> [codex-args...]
+rcs autoresearch --resume <run-id> [codex-args...]
+rcs autoresearch --help
+```
+
+- Fresh launch always creates a new run-tagged lane.
+- `--resume <run-id>` loads `.rcs/logs/autoresearch/<run-id>/manifest.json`.
+- A second launch is rejected while repo-root `.rcs/state/autoresearch-state.json` points at an active run.
+
+## Mission / sandbox contract
+
+`<mission-dir>` must be inside a git repo and contain `mission.md` plus `sandbox.md`.
+
+`sandbox.md` YAML frontmatter must define:
+- `evaluator.command`
+- `evaluator.format: json`
+- optional `evaluator.keep_policy: score_improvement | pass_only`
+
+Evaluator stdout must be JSON with required boolean `pass` and optional numeric `score`.
+
+## Runtime model
+
+Fresh launch creates:
+- branch `autoresearch/<mission-slug>/<run-tag>`
+- worktree `<repo>.rcs-worktrees/autoresearch-<mission-slug>-<run-tag>`
+- repo-root run artifacts under `.rcs/logs/autoresearch/<run-id>/`
+
+Repo-root state responsibilities:
+- `.rcs/state/autoresearch-state.json` = active-run pointer/lock only
+- `.rcs/logs/autoresearch/<run-id>/manifest.json` = authoritative per-run state
+- `.rcs/logs/autoresearch/<run-id>/candidate.json` = candidate handoff from the just-finished Codex session
+- `.rcs/logs/autoresearch/<run-id>/iteration-ledger.json` = durable iteration history
+- `.rcs/logs/autoresearch/<run-id>/latest-evaluator-result.json` = latest evaluator output
+
+Worktree-local state responsibilities:
+- `results.tsv`
+- optional evaluator logs such as `run.log`
+- these runtime-generated files must be excluded via worktree-local `.git/info/exclude`
+
+## Candidate artifact
+
+The launched session must write repo-root `candidate.json` with:
+- `status`: `candidate | noop | abort | interrupted`
+- `candidate_commit`: string or `null`
+- `base_commit`: string
+- `description`: string
+- `notes`: string[]
+- `created_at`: ISO timestamp
+
+Integrity rules:
+- `status=candidate` requires a non-null `candidate_commit`
+- `candidate_commit` must resolve in git and match the worktree `HEAD` commit on exit
+- `base_commit` must resolve in git and match the supervisor-provided `last_kept_commit`
+
+Supervisor behavior:
+- `candidate` → run evaluator, classify keep/discard/ambiguous/error, update manifest/ledger/results, reset if discarded
+- `noop` → log noop iteration and continue by default
+- `abort` → stop run without reset
+- `interrupted` → if dirty, stop for operator intervention; if clean, log interrupted/noop style outcome
+
+## Decision policy
+
+- Baseline row is always recorded.
+- `pass=false` => discard.
+- evaluator error/crash => discard.
+- `keep_policy=score_improvement` => keep only when `pass=true` and score improves over last kept score; pass without comparable score is `ambiguous` and discarded.
+- `keep_policy=pass_only` => any `pass=true` candidate is kept.
+- Discard / ambiguous / error paths must reset to the last kept commit.
+
+## Resume
+
+`--resume <run-id>` must fail with actionable errors when:
+- manifest is missing
+- referenced worktree is missing
+- worktree is dirty outside allowlisted runtime artifacts
+- manifest is terminal
+
+Successful resume continues from the last kept commit and existing results history.
+
+## Iteration handoff context
+
+Each launched worker session receives a supervisor-written instruction snapshot including:
+- current iteration number
+- baseline commit
+- last kept commit
+- last kept score when known
+- previous iteration outcome
+- bounded recent ledger summary
+- keep policy
+
+## Verification targets
+
+Parity-aligned implementation should prove:
+1. fresh launches create distinct run-tagged lanes
+2. repo-root active-run lock rejects concurrent launches
+3. candidate handoff artifact drives keep/discard/reset decisions
+4. discarded candidates reset to `last_kept_commit`
+5. `--resume <run-id>` reloads authoritative manifest/worktree state
+6. README/help/contracts describe the thin-supervisor parity loop

package/docs/contracts/autoresearch-command-review.md

@@ -0,0 +1,97 @@
+# `rcs autoresearch` Full-Parity Review Notes
+
+Date: 2026-03-14  
+Reviewer lane: worker-3
+
+## Scope reviewed
+
+Compared the implementation and operator-facing docs against:
+
+- `.rcs/plans/prd-autoresearch-full-parity.md`
+- `.rcs/plans/test-spec-autoresearch-full-parity.md`
+
+Reviewed code and docs:
+
+- `src/cli/autoresearch.ts`
+- `src/autoresearch/contracts.ts`
+- `src/autoresearch/runtime.ts`
+- `src/team/worktree.ts`
+- `src/modes/base.ts`
+- `README.md`
+- `docs/contracts/autoresearch-command-contract.md`
+- focused autoresearch tests under `src/**/__tests__`
+
+## Current status
+
+**Status:** parity-critical behavior appears implemented and the previously noted shared help/test wording mismatch is now resolved.
+
+The branch now matches the PRD/test-spec shape much more closely than the earlier scaffold review:
+
+- `rcs autoresearch` exposes both fresh launch and `--resume <run-id>` flows.
+- the runtime owns a thin-supervisor loop boundary via repo-root candidate handoff + post-session evaluator decisions.
+- repo-root active-run locking and authoritative per-run manifests are present.
+- fresh launches create run-tagged autoresearch lanes instead of silently reusing one long-lived lane.
+- docs/help/contracts describe keep/discard/reset semantics instead of the earlier v1 scaffold.
+
+## Verified evidence
+
+### Build
+- `npm run build` → PASS
+
+### Focused tests
+- `node --test dist/autoresearch/__tests__/runtime.test.js dist/cli/__tests__/autoresearch.test.js dist/cli/__tests__/index.test.js dist/cli/__tests__/nested-help-routing.test.js dist/team/__tests__/worktree.test.js dist/modes/__tests__/base-autoresearch-contract.test.js` → PASS
+- `node --test dist/cli/__tests__/session-search-help.test.js` → PASS
+
+### Code/doc alignment observed
+- CLI help documents fresh launch + `--resume <run-id>`: `src/cli/autoresearch.ts`
+- top-level help advertises thin-supervisor parity semantics: `src/cli/index.ts`, `src/compat/fixtures/help.stdout.txt`
+- README now explains baseline seeding, repo-root per-run artifacts, candidate handoff, keep/discard/reset, relaunch loop, and resume behavior: `README.md`
+- contract doc now defines run-tagged lanes, repo-root authority split, candidate artifact schema, decision policy, and resume failure conditions: `docs/contracts/autoresearch-command-contract.md`
+- runtime implements active-run lock, per-run manifest files, allowlisted runtime excludes, candidate parsing, evaluator-backed decisions, reset-to-last-kept behavior, and resume validation: `src/autoresearch/runtime.ts`
+- worktree planning test locks run-tagged autoresearch branch/path naming: `src/team/__tests__/worktree.test.ts`
+
+## Parity checklist
+
+### 1. Thin-supervisor iteration model
+**Pass.**
+- `buildAutoresearchInstructions()` tells the launched Codex session to perform exactly one experiment cycle and write the candidate artifact before exit.
+- `runAutoresearchLoop()` relaunches Codex after `processAutoresearchCandidate()` unless the run aborts/errors.
+
+### 2. Repo-root state authority
+**Pass.**
+- repo-root active-run lock lives at `.rcs/state/autoresearch-state.json`.
+- per-run manifest, candidate, ledger, and latest evaluator files live under `.rcs/logs/autoresearch/<run-id>/`.
+- worktree-local runtime artifacts are limited to `results.tsv` and allowlisted logs.
+
+### 3. Fresh-run semantics
+**Pass.**
+- fresh launches compute a run tag and plan `autoresearch/<mission-slug>/<run-tag>` plus `autoresearch-<mission-slug>-<run-tag>`.
+- focused worktree coverage now asserts run-tagged branch/path naming.
+
+### 4. Resume contract
+**Pass.**
+- CLI parses `--resume <run-id>`.
+- runtime rejects missing manifest, missing worktree, dirty worktree, and terminal runs.
+
+### 5. Keep/discard/reset decision policy
+**Pass.**
+- baseline row is seeded.
+- evaluator failure/error discards.
+- `pass_only` keeps any pass.
+- `score_improvement` requires comparable numeric scores and improvement; otherwise ambiguous/discard.
+- discard paths reset to `last_kept_commit`.
+
+### 6. Docs/help/contracts alignment
+**Pass.**
+- README, command help, top-level help, fixture help text, and the contract doc now describe the parity loop rather than a one-shot bootstrap scaffold.
+- Shared help/test wording now matches the thin-supervisor parity wording.
+
+## Remaining review notes / risks
+
+1. `runAutoresearchLoop()` currently reads the run id back from the manifest file via `execFileSync('cat', ...)` + `JSON.parse(...)` on each iteration. That works, but it is a slightly awkward implementation detail and could be simplified to avoid shelling out to `cat`.
+2. Focused tests cover the main parity surfaces, but there is still room for broader runtime coverage around `noop`, `abort`, `interrupted`, and explicit `pass_only` policy branches if the lead wants even tighter semantic locking.
+3. I verified focused parity coverage and build status, not the entire repository-wide test suite/lint suite.
+
+## Reviewer conclusion
+
+This lane no longer looks like the earlier v1 scaffold. The reviewed implementation and docs now appear largely consistent with the requested thin-supervisor autoresearch parity model; the previously noted shared top-level help/test wording mismatch is resolved; remaining follow-ups are optional cleanup/coverage improvements.

package/docs/contracts/autoresearch-ux-deep-interview-review.md

@@ -0,0 +1,114 @@
+# `rcs autoresearch` deep-interview UX review notes
+
+Date: 2026-03-17  
+Reviewer lane: worker-3
+
+## Scope reviewed
+
+Compared the current implementation and operator-facing docs against:
+
+- `.rcs/plans/prd-autoresearch-ux-deep-interview.md`
+- `.rcs/plans/test-spec-autoresearch-ux-deep-interview.md`
+
+Reviewed files:
+
+- `src/cli/autoresearch.ts`
+- `src/cli/autoresearch-guided.ts`
+- `src/cli/__tests__/autoresearch-guided.test.ts`
+- `src/cli/__tests__/autoresearch.test.ts`
+- `skills/deep-interview/SKILL.md`
+- `README.md`
+- `docs/contracts/autoresearch-command-contract.md`
+- in-progress contract-test delta from worker-2: `src/hooks/__tests__/deep-interview-contract.test.ts`
+
+## Current status
+
+**Status:** the PRD/test-spec behavior is not implemented on the reviewed branch yet.
+
+Current code still reflects the older guided-init flow:
+
+- `rcs autoresearch` with no args enters `guidedAutoresearchSetup()` and immediately asks for a raw evaluator command.
+- bare `init` still routes into that same guided path instead of an explicit novice compatibility bridge.
+- there is no autoresearch-specific intake module, no canonical `.rcs/specs/deep-interview-autoresearch-{slug}.md` artifact, and no confirm/refine launch gate.
+- launch still happens immediately after guided setup returns.
+- README/help/contract docs still describe the thin-supervisor runtime, but not the new novice deep-interview intake surface from this PRD.
+
+## Evidence observed
+
+### Code-path findings
+- `src/cli/autoresearch.ts`
+  - `parseAutoresearchArgs()` only recognizes no-arg guided mode, `init`, `--resume`, and `<mission-dir>`.
+  - top-level `--topic/--evaluator/--keep-policy/--slug` seeded novice flags are not routed.
+  - guided/init flows still call `spawnAutoresearchTmux()` immediately after mission creation.
+- `src/cli/autoresearch-guided.ts`
+  - `guidedAutoresearchSetup()` still prompts directly for `Evaluator command`.
+  - no placeholder/readiness rejection exists beyond `parseSandboxContract()`.
+  - no draft artifact is written under `.rcs/specs/`.
+- `skills/deep-interview/SKILL.md`
+  - the generic execution bridge exists, but the autoresearch specialization section required by the PRD is absent on this branch.
+
+### Test/doc alignment findings
+- `src/cli/__tests__/autoresearch-guided.test.ts`
+  - covers mission/scaffold creation and flag parsing for the older init/guided flow only.
+- `src/cli/__tests__/autoresearch.test.ts`
+  - still asserts the older `rcs autoresearch init [--topic ...]` help surface and non-interactive `mission-dir is required` failure.
+- worker-2 has an in-progress test addition that correctly starts locking the expected deep-interview specialization text in `src/hooks/__tests__/deep-interview-contract.test.ts`.
+
+## PRD checklist assessment
+
+### 1. Vague-goal novice intake without raw evaluator knowledge
+**Fail on current branch.**
+The first guided prompt still asks for a concrete evaluator shell command.
+
+### 2. Autoresearch-specific deep-interview/refinement bridge
+**Fail on current branch.**
+No autoresearch-specific refinement loop or seeded novice bridge exists.
+
+### 3. Canonical draft artifact at `.rcs/specs/deep-interview-autoresearch-{slug}.md`
+**Fail on current branch.**
+No `.rcs/specs/` draft artifact is generated.
+
+### 4. Explicit `refine further` vs `launch` confirmation boundary
+**Fail on current branch.**
+Guided setup returns launch-ready mission data and tmux launch happens immediately.
+
+### 5. Placeholder evaluator rejection before launch
+**Fail on current branch.**
+There is no blocked-pattern gate for placeholder evaluator commands.
+
+### 6. Top-level seeded novice flags (`--topic`, `--evaluator`, `--keep-policy`, `--slug`)
+**Fail on current branch.**
+Those flags are not accepted at top level; only `init` parses them today.
+
+### 7. Expert flows preserved (`<mission-dir>`, `init --flags`, `--resume`)
+**Pass on current branch.**
+Existing expert/runtime flows remain intact.
+
+### 8. Bare `rcs autoresearch init` documented as novice alias
+**Fail on current branch.**
+Bare `init` is routed into guided mode, but help/docs do not explain the compatibility semantics required by the PRD.
+
+### 9. Non-interactive no-arg failure preserved
+**Pass on current branch.**
+The TTY guard still rejects no-arg non-interactive invocation.
+
+### 10. Regression coverage for interview/draft/confirm path
+**Fail on current branch.**
+Those tests are not present yet.
+
+## Documentation follow-ups once implementation lands
+
+1. Update `README.md` with the new novice entry surfaces:
+   - `rcs autoresearch` as a deep-interview-style refinement flow
+   - top-level seeded novice flags
+   - explicit confirm-before-launch behavior
+2. Update `docs/contracts/autoresearch-command-contract.md` to add:
+   - canonical draft artifact path
+   - launch-readiness placeholder rejection rules
+   - confirm/refine bridge semantics
+3. Extend `skills/deep-interview/SKILL.md` with the PRD-required `Autoresearch specialization` section and required artifact headings.
+4. Keep help text explicit about the split between novice refinement mode and expert `init --flags` / `<mission-dir>` / `--resume` flows.
+
+## Reviewer conclusion
+
+This review lane can confirm the current branch preserves existing autoresearch runtime behavior, but it does **not** yet satisfy the deep-interview UX enhancement PRD. The most useful near-term review output is therefore this baseline gap assessment plus the documentation checklist above; once worker-1 lands the implementation, this file should be refreshed with a final pass/fail review and verification evidence.

package/docs/contracts/explicit-terminal-stop-model.md

@@ -0,0 +1,96 @@
+# Explicit Terminal Stop Model Contract
+
+Status: approved migration contract for runtime, hooks, MCP state, and prompt/documentation surfaces.
+
+## Purpose
+
+This document locks the canonical terminal stop vocabulary for active RCS workflows.
+It exists so runtime code, native/fallback Stop handlers, MCP state, and user-facing handoff guidance all describe the same end-of-turn semantics.
+
+## Canonical terminal lifecycle outcomes
+
+These are the only canonical user-facing terminal lifecycle outcomes for the explicit stop model:
+
+| Outcome | Meaning | Continuation rule | User-facing expectation |
+| --- | --- | --- | --- |
+| `finished` | The workflow completed successfully. | Do not auto-continue. | Report completion evidence and resulting artifacts. |
+| `blocked` | Progress cannot continue because a non-user prerequisite is missing. | Do not auto-continue until the blocker changes. | Report the blocker, why it matters, and the required handoff. |
+| `failed` | The workflow or verification failed. | Do not auto-continue until the failure is addressed. | Report failure evidence, impact, and recommended recovery. |
+| `userinterlude` | The user intentionally interrupted or paused the run. | Do not auto-continue unless the user explicitly restarts it. | Report that the stop was user-originated, not model-originated. |
+| `askuserQuestion` | RCS must ask the user a blocking question before safe progress can continue. | Do not auto-continue until the question is answered. | Ask one concrete blocking question and record the question metadata. |
+
+`askuserQuestion` and `userinterlude` are intentionally distinct:
+
+- `askuserQuestion` is model-originated and should normally be backed by `rcs question` or equivalent machine-readable question metadata.
+- `userinterlude` is user-originated interruption/stop intent.
+
+## Legacy compatibility rules
+
+Legacy values may still appear in persisted state during migration, but they are compatibility inputs, not the public canonical vocabulary.
+
+| Legacy value | Canonical interpretation |
+| --- | --- |
+| `finish`, `complete`, `completed`, `done` | normalize to `finished` |
+| `blocked_on_user` | compatibility-only user-wait signal; map to `askuserQuestion` when question metadata proves RCS asked a blocking question, otherwise map to `userinterlude`/user-wait compatibility according to the surrounding context |
+| `cancelled`, `canceled`, `abort`, `aborted` | internal legacy/admin stop compatibility only; do **not** present as a canonical user-facing lifecycle outcome |
+
+### `cancelled` policy
+
+`cancelled` remains valid for legacy administrative state, teardown, or backward-compatible reads.
+It is **not** a canonical user-facing terminal lifecycle outcome in the explicit stop model.
+Docs, prompts, and runtime summaries should prefer one of:
+
+- `finished`
+- `blocked`
+- `failed`
+- `userinterlude`
+- `askuserQuestion`
+
+## State / MCP precedence
+
+Terminal lifecycle metadata should be interpreted in this order:
+
+1. a dedicated canonical lifecycle field such as `lifecycle_outcome`
+2. legacy `run_outcome` compatibility data
+3. fallback inference from `current_phase`, question metadata, and other persisted context
+
+Notes:
+
+- `current_phase` and lifecycle outcome are related but not identical. A workflow can keep legacy phase names while still exposing canonical lifecycle metadata.
+- If both canonical lifecycle metadata and legacy `run_outcome` are present, the canonical lifecycle field wins.
+- `run_outcome` should be treated as a compatibility read/write surface during migration, not as the long-term public contract.
+
+## Stop / watcher interpretation rules
+
+Stop readers, native hooks, and fallback watchers should prefer explicit lifecycle metadata over assistant prose heuristics.
+During migration they should:
+
+- honor canonical `finished`, `blocked`, `failed`, `userinterlude`, and `askuserQuestion` metadata first
+- keep honoring legacy `blocked_on_user` as a suppress-continuation compatibility signal
+- avoid treating optional assistant prose as the semantic owner of lifecycle state
+- keep `cancelled` internal legacy-only when translating to user-facing lifecycle summaries
+
+## Active workflow terminal handoff contract
+
+When an active workflow produces a terminal user-facing message, the handoff should be explicit and structured.
+The terminal summary should include:
+
+1. **Outcome** — one explicit lifecycle label
+2. **Evidence** — concrete verification output, failure evidence, or the missing dependency/question
+3. **Artifacts / state** — changed files, saved artifacts, or recorded question identifiers when relevant
+4. **Handoff** — the exact next owner or required answer, without optional permission-seeking phrasing
+
+### Forbidden terminal pattern
+
+Do **not** end active workflow terminal handoffs with optional follow-up softeners such as:
+
+- `If you want, I can ...`
+- `If you'd like, I can ...`
+- `Would you like me to continue?`
+
+Those phrases make the lifecycle state ambiguous. The terminal outcome should already explain whether the run finished, failed, blocked, entered user interlude, or is waiting on a required user question.
+
+## Non-goals
+
+This contract does **not** require every legacy internal phase name to be renamed immediately.
+It does require every migrated surface to expose and prefer the canonical terminal lifecycle concepts above.