[codex] Add portfolio demo positioning

README.md

@@ -10,6 +10,17 @@ Patchrail keeps coding-agent supervision in a local CLI instead of hiding plans,
 
 Japanese usage notes live in [README.ja.md](README.ja.md).
 
+## What This Demonstrates
+
+Patchrail is intended to be read as a serious engineering portfolio project, not only as a CLI prototype. It demonstrates:
+
+- Product judgment: narrowing the problem from generic agent orchestration to verification and approval packets for AI-coded changes.
+- Systems design: explicit lifecycle records, role separation, approval boundaries, local persistence, and resumable state.
+- Practical CLI execution: commands that create tasks, capture Delivery Contracts, run executors, record verification, and export review-ready packets.
+- Engineering discipline: focused tests, smoke tests, package metadata, release checks, and a local-first storage model that can be inspected from disk.
+
+For interview-oriented material, see the [3-minute demo guide](docs/three-minute-demo.md) and [resume positioning notes](docs/resume-positioning.md).
+
 ## Development Purpose
 
 Patchrail is being developed to make AI-coded changes auditable before, during, and after implementation. Modern coding agents can move from a vague instruction to repository changes very quickly; the hard part is proving what the operator meant, what changed, which checks ran, and why a human approved or rejected the result.
@@ -43,19 +54,17 @@ The result is not an autonomous-agent launcher. It is a supervision rail: a loca
 
 ## What You Can Show In 3 Minutes
 
-Patchrail demonstrates a practical safety boundary for coding agents in customer or client repositories:
+Patchrail demonstrates a practical safety boundary for AI coding work:
 
-1. Create a task that describes the supervised work.
-2. Attach future, ontology, and product briefs before implementation begins.
-3. Store a canonical plan that references those briefs.
-4. Run an executor behind an explicit runner assignment.
-5. Run operator-specified verification commands against the completed work.
-6. Export a review-ready approval packet before any final approval.
-7. Record the human approval decision and ledgers locally.
+1. Run an AI coding workflow behind an explicit Patchrail task and plan.
+2. Record the executor run and artifact bundle in local storage.
+3. Run `patchrail verify --run-id <run_id> --command "pytest -q"` to capture verification evidence.
+4. Use `patchrail list review-queue` to separate missing verification, failed verification, ready-for-review, awaiting-approval, and approved tasks.
+5. Export `patchrail packet show --task-id <task_id>` as the review-ready artifact.
 
 The point is not to make an agent autonomous by default. The point is to make the handoff between human intent, agent execution, review evidence, and final approval inspectable from disk.
 
-For a public-facing walkthrough, see [Supervised Agent Rollout](docs/case-studies/supervised-agent-rollout.md).
+For a public-facing walkthrough, see the [3-minute demo guide](docs/three-minute-demo.md) and [Supervised Agent Rollout](docs/case-studies/supervised-agent-rollout.md).
 
 ## Why Patchrail
 
@@ -273,6 +282,8 @@ patchrail --json status --task-id <task_id>
 
 - [Architecture](docs/architecture.md)
 - [MVP](docs/mvp.md)
+- [3-Minute Demo](docs/three-minute-demo.md)
+- [Resume Positioning](docs/resume-positioning.md)
 - [Local Testing](docs/local-testing.md)
 - [Backlog](docs/backlog.md)
 - [Changelog](CHANGELOG.md)

docs/case-studies/supervised-agent-rollout.md

@@ -4,7 +4,7 @@
 Patchrail is framed for enterprise engineering teams that want to introduce AI coding agents inside customer environments without losing supervision, approval boundaries, or local audit evidence.
 
 ## Problem
-AI coding agents can move from vague intent to repository changes quickly, but client work often needs stronger controls before execution starts. Operators need to define what finished means, which concepts are real, where ownership and approval boundaries sit, and what scope is explicitly out of bounds. They also need the resulting plan, run, review, approval, logs, artifacts, and decision traces to remain inspectable from disk.
+AI coding agents can move from vague intent to repository changes quickly, but client work often needs stronger controls before and after execution. Operators need to define what finished means, which concepts are real, where ownership and approval boundaries sit, what scope is explicitly out of bounds, which verification commands ran, and what evidence a human reviewed. They also need the resulting plan, run, verification, review, approval, logs, artifacts, and decision traces to remain inspectable from disk.
 
 ## Constraints
 - CLI-first and headless-core-first operation.
@@ -26,7 +26,7 @@ The Phase 1 planning layer adds three companion artifacts before execution:
 | Reality boundary | `Ontology Brief` | Define what exists, who owns it, and where approval/artifact boundaries sit. |
 | Post-implementation acceptance | `Product Brief` | Define what must be true after implementation for users and operators. |
 
-The harness then acts as the post-implementation evidence layer. It does not own canonical state; it captures execution summary, diff summary, stdout/stderr, invocation metadata, runner trace, and artifact metadata after the executor runs and before review.
+The verification layer then acts as the post-implementation evidence layer. It does not own canonical state; it captures operator-specified command results, stdout/stderr output paths, exit codes, elapsed time, runner trace, and artifact metadata after the executor runs and before review.
 
 These briefs are stored as local JSON companion artifacts under `.patchrail/briefs/`. When `patchrail plan` creates the canonical plan, it records stable `planning_briefs` references containing the brief id, kind, source path, storage path, digest, and creation timestamp. The plan remains the canonical planning record; briefs are supporting artifacts.
 
@@ -42,27 +42,32 @@ These briefs are stored as local JSON companion artifacts under `.patchrail/brie
 The current implementation adds:
 
 - `patchrail setup` for first-run runtime bootstrap and preflight-oriented next steps.
-- `patchrail setup project --title ... --description ...` for task creation plus editable local planning brief scaffolds.
+- `patchrail setup project --guided --title ... --description ...` for task creation plus editable local Delivery Contract scaffolds.
 - `patchrail brief create --task-id ... --kind future|ontology|product --file ...` after replacing scaffold placeholders with concrete planning content.
 - `patchrail brief list --task-id ...`
 - `patchrail brief show --brief-id ...`
 - Plan serialization with `planning_briefs`.
+- `patchrail verify --run-id ... --command ...` for command, cwd, exit code, elapsed time, status, and stdout/stderr output paths.
+- `patchrail list verifications` and `patchrail list review-queue` for local review triage.
+- `patchrail packet show|export` for Markdown and JSON approval packets.
 - Auto planner prompt context that can include the stored planning briefs.
-- Local JSON storage for brief companion artifacts.
-- Tests covering creation, list/show, invalid kind rejection, missing task rejection, plan reference behavior, status, run, and logs.
+- Local JSON storage for brief companion artifacts and verification records.
+- Tests covering brief creation, list/show, plan reference behavior, verification persistence, command failure handling, review queue grouping, packet export, status, run, and logs.
 
 ## Operations
 A local operator can run the controlled path as:
 
 ```bash
 patchrail setup
-patchrail setup project --title "Client agent rollout" --description "Introduce supervised coding agents"
+patchrail setup project --guided --title "Client agent rollout" --description "Introduce supervised coding agents"
 # edit generated future/ontology/product source files, then persist them
 patchrail brief create --task-id <task_id> --kind future --file <future_brief_file>
 patchrail brief create --task-id <task_id> --kind ontology --file <ontology_brief_file>
 patchrail brief create --task-id <task_id> --kind product --file <product_brief_file>
 patchrail plan --task-id <task_id> --summary "Execute within explicit planning boundaries" --step "Read briefs" --step "Run bounded implementation"
 patchrail run --task-id <task_id> --runner claude_code
+patchrail verify --run-id <run_id> --command "pytest -q"
+patchrail packet show --task-id <task_id>
 patchrail review --run-id <run_id> --verdict pass --summary "Reviewed persisted artifacts"
 patchrail approve --task-id <task_id> --rationale "Meets the agreed completion boundary"
 ```
@@ -73,6 +78,9 @@ Read-side inspection stays local:
 patchrail brief list --task-id <task_id>
 patchrail brief show --brief-id <brief_id>
 patchrail status --task-id <task_id>
+patchrail list verifications --task-id <task_id>
+patchrail list review-queue
+patchrail packet show --task-id <task_id>
 patchrail logs --run-id <run_id>
 patchrail artifacts --run-id <run_id>
 ```
@@ -84,15 +92,18 @@ The local store contains:
 - `.patchrail/briefs/<brief_id>.json`
 - `.patchrail/plans/<plan_id>.json`
 - `.patchrail/runs/<run_id>.json`
+- `.patchrail/verifications/<verification_id>.json`
+- `.patchrail/verification_outputs/<verification_id>/stdout.log`
+- `.patchrail/verification_outputs/<verification_id>/stderr.log`
 - `.patchrail/reviews/<review_id>.json`
 - `.patchrail/approvals/<approval_id>.json`
 - `.patchrail/artifacts/<run_id>/bundle.json`
 - `.patchrail/ledgers/decision-trace.jsonl`
 - `.patchrail/ledgers/approval-ledger.jsonl`
 
-The test suite verifies the new brief layer and the existing major CLI flow. The first brief-layer test creates a brief, lists and shows it, creates a plan that references it, runs the local harness, and reads logs from the persisted run.
+The test suite verifies the brief layer, verification layer, packet generation, review queue grouping, and the existing major CLI flow. The smoke flow creates a task, plans, runs the local harness, records verification, reviews, approves, and exports an approval packet.
 
 ## Outcome
-Patchrail can now be described as a local-first, approval-gated, evidence-preserving CLI control plane for introducing AI coding agents at customer sites. It helps a customer-facing technical operator show how completion definition, ontology boundaries, and product scope become explicit before execution, then remain connected to the plan, run, review, approval, ledgers, and artifacts on disk.
+Patchrail can now be described as a local-first, approval-gated, evidence-preserving CLI control plane for introducing AI coding agents at customer sites. It helps a customer-facing technical operator show how completion definition, ontology boundaries, product scope, verification commands, and approval rationale remain connected to the plan, run, review, approval, ledgers, and artifacts on disk.
 
-Current limits are deliberate: there is no dashboard, no autonomous approval, and no Codex/Claude/Grok triangulated planning path yet. The first delivered layer is the deterministic local planning brief path that the later triangulation layer can consume.
+Current limits are deliberate: there is no dashboard, no autonomous approval, and no autonomous command selection. The delivered v0.2 path is a deterministic local verification and approval-packet workflow that later provider-specific runners and richer diff evidence can feed.

docs/resume-positioning.md

@@ -0,0 +1,33 @@
+# Patchrail Resume Positioning
+
+## 30秒説明
+
+Patchrail は、Claude / Codex / Cursor などの AI コーディングワークフローの出力に対して、「何を依頼し、何が実行され、どの検証を通し、人間が何を根拠に承認したか」をローカルに記録する CLI ツールです。単なるエージェント実行基盤ではなく、AI が書いたコードをレビュー・承認できる状態にするための verification / approval packet に焦点を当てています。
+
+## 職務経歴書向け要約
+
+AI コーディングエージェントの実行結果を監査可能にする local-first CLI「Patchrail」を個人開発。タスク、計画、実行、検証、レビュー、承認を明示的なローカルレコードとして保存し、`patchrail verify` による検証コマンド実行結果と `patchrail packet` による承認用 Markdown / JSON パケット生成を実装。CLI 設計、状態遷移、ファイル永続化、テスト、PyPI 配布準備まで一貫して担当。
+
+## 技術的に話すポイント
+
+- CLI-first / headless-core-first の設計により、ダッシュボードより先に再現可能なローカル状態管理を優先。
+- `Task -> Plan -> Run -> ReviewResult -> ApprovalRecord` の canonical lifecycle を維持し、verification は証跡として追加することでスコープを膨らませすぎない設計にした。
+- `.patchrail/` 以下に JSON / JSONL / stdout / stderr を保存し、将来のセッションがディスクだけから安全に再開できるようにした。
+- provider を汎用 model wrapper に潰さず、planner / reviewer / executor として役割分離した。
+- `pytest`、smoke test、release check、wheel install 確認まで含め、ポートフォリオとして動作証明できる状態にした。
+
+## 面接での補足
+
+Patchrail で一番重視したのは、「AI にもっとコードを書かせること」ではなく、「AI が書いたコードを人間が責任を持って承認できる状態にすること」です。AI コーディングでは生成速度よりも、レビュー待ち、検証不足、権限境界、複数エージェント出力の管理が実務上のボトルネックになります。そこで v0.2 では generic orchestration ではなく、verification と approval packet に絞りました。
+
+## 代表作として見せる順番
+
+1. README の冒頭で product thesis を説明する。
+2. 3分デモで `verify -> review-queue -> packet` の流れを見せる。
+3. PR で設計意図、テスト、release check が残っていることを見せる。
+4. 面接では「なぜ dashboard ではなく CLI / local-first から始めたか」を説明する。
+5. 最後に、今後の改善として verification preset、diff evidence、approval packet の品質向上を話す。
+
+## 短い職務経歴書用文面
+
+AI コーディングエージェントの実行結果を検証・承認可能にする local-first CLI「Patchrail」を設計・実装。`patchrail verify` で検証コマンドの stdout / stderr / exit code / elapsed time を保存し、`patchrail packet` でタスク、計画、実行、成果物、検証、レビュー、承認をまとめた approval packet を生成。状態遷移設計、ファイル永続化、CLI UX、テスト、PyPI 配布準備まで担当。

docs/three-minute-demo.md

@@ -0,0 +1,73 @@
+# Patchrail 3-Minute Demo
+
+## Demo Goal
+
+Show that Patchrail is not another code-generation agent. It is a local verification and approval layer for AI-coded changes: it records what was planned, what ran, which verification command was executed, and what evidence is ready for human review.
+
+## Talk Track
+
+Opening, 20 seconds:
+
+> AI coding agents can generate changes quickly, but senior developers still need evidence. Patchrail is a local-first CLI that turns an agent run into an auditable approval packet.
+
+Core workflow, 90 seconds:
+
+1. A task anchors the supervised work.
+2. A Delivery Contract captures future state, ontology boundaries, and product acceptance before execution.
+3. A run records the executor assignment, workspace, logs, and artifact bundle.
+4. `patchrail verify` runs an operator-chosen command such as `pytest -q` and stores stdout, stderr, exit code, elapsed time, and status.
+5. `patchrail packet show` produces the Markdown evidence a human reviewer can inspect.
+
+Close, 30 seconds:
+
+> The design choice is deliberate: Patchrail does not approve automatically, does not hide state in a dashboard, and does not flatten providers into a generic model wrapper. It gives a serious user a local record they can inspect, resume, and defend.
+
+## Fast Local Demo
+
+From a source checkout:
+
+```bash
+export PATCHRAIL_HOME="$(mktemp -d)"
+sh scripts/local_smoke_test.sh
+```
+
+The smoke output prints a task id, run id, verification id, final state, and packet path. Use those ids for the follow-up inspection commands:
+
+```bash
+patchrail list verifications --task-id <task_id>
+patchrail list review-queue
+patchrail packet show --task-id <task_id>
+```
+
+Expected proof points:
+
+- The verification record is `passed`.
+- The review queue shows the completed task under `approved`.
+- The approval packet contains task, plan, run, artifacts, verification, review, approval, and unresolved gaps.
+
+## Manual Demo Variant
+
+Use this when you want to show the public command surface rather than the smoke script:
+
+```bash
+patchrail setup
+patchrail setup project --guided --title "Demo task" --description "Verify an AI-coded change"
+patchrail plan --task-id <task_id> --summary "Run and verify agent output" --step "Execute supervised run" --step "Verify output"
+patchrail run --task-id <task_id> --runner auto
+patchrail verify --run-id <run_id> --command "pytest -q"
+patchrail packet show --task-id <task_id>
+```
+
+If the demo environment does not have the full test suite available, replace `pytest -q` with a deterministic command:
+
+```bash
+patchrail verify --run-id <run_id> --command "python -c 'print(\"verification ok\")'"
+```
+
+## Interview Emphasis
+
+- Product focus: the project pivoted from broad orchestration to a sharper verification need.
+- State discipline: verification is intentionally stored as evidence without changing the canonical lifecycle yet.
+- Local-first architecture: every record is readable under `.patchrail/`.
+- Safety boundary: human approval remains explicit even when an agent and verification both succeed.
+- Distribution readiness: package metadata, `pipx install patchrail` docs, smoke tests, and release checks are part of the project.