PR7: boulder-native-preview profile and docs integration

.github/workflows/ci.yml

@@ -27,5 +27,15 @@ jobs:
       - name: Show Bun version
         run: bun --version
 
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes bubblewrap
+          sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+          bwrap --unshare-net --ro-bind / / -- /bin/true
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
       - name: Run CI gate
         run: bun run ci

Boulder_Native_Planner_v0.2_USER_ACTION_REQUEST.ko.md

@@ -0,0 +1,54 @@
+# 사용자 조치 요청서 — Boulder Native Planner v0.2
+
+> **승인 기록 (2026-07-18):** 사용자가 `HOLD` 결과 승인, 8개 PR 단위 게시, 신규 prospective 36-run 연구를 승인했다.
+
+## 1. 현재 상태
+
+- 구현 및 검증: 완료
+- PR8B 판정: **HOLD**
+- 필수 기술 수정: 없음
+- 뒤늦게 도착한 malformed score receipt 및 trust-root TOCTOU 지적은 G017에서 이미 보완·검증됨
+- External Handoff bridge: v0.2 범위 밖의 후속 RFC
+
+## 2. 지금 필요한 결정
+
+### A. 이번 결과를 `HOLD`로 확정
+
+- [ ] 현재 PR8B 결과를 v0.2의 공식 결론으로 승인
+
+의미: 기능과 검증 도구는 준비됐지만, Boulder Native Planner를 fallback 또는 preferred 경로로 승격하지 않는다.
+
+**권장안:** `HOLD` 승인
+
+### B. 변경사항 게시 방식 결정
+
+- [ ] 현재 작업 트리 변경을 계획된 PR1~PR8A 단위로 나눠 커밋 및 PR 게시
+- [ ] PR8B 운영 증거는 구현 PR과 분리된 결과물로 유지
+- [ ] 기존 사용자 변경과 이번 프로그램 변경을 커밋 단계에서 분리
+
+현재 에이전트는 저장소 안전 정책에 따라 커밋, 푸시 또는 PR 생성을 수행하지 않았다.
+
+## 3. 향후 승격을 위한 승인 사항
+
+현재 `HOLD`를 해소하려면 기존 결과를 수정하는 대신 새로운 prospective PR8B 연구를 수행해야 한다.
+
+- [ ] 신규 36회 실행 비용과 외부 호출 승인
+- [ ] 점수 평가 전에 블라인드 배정과 score-lock을 완료하는 방식 승인
+- [ ] 실패한 실행 7건의 원인 수정 및 신규 실행 승인
+- [ ] critical cap 3건을 해소한 새 계획 결과 생성 승인
+- [ ] 최소 적격 실행 수 충족을 위한 재실행 승인
+- [ ] 독립적인 인간 또는 외부 maintainer 검토자 지정
+
+새 연구도 비교 가능성을 유지하기 위해 `openai-codex/gpt-5.6-sol`을 고정 모델로 사용한다.
+
+## 4. 별도 후속 결정
+
+- [ ] External Handoff bridge RFC 착수 여부 결정
+
+이는 v0.2 범위 밖이며 현재 구현에는 포함되지 않았다.
+
+## 5. 요청 요약
+
+현재 필요한 최소 승인 문구는 다음과 같다.
+
+> v0.2의 HOLD 결과를 승인하고, 변경사항을 8개 PR 단위로 게시한다.

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.1.17
+
+- Published npm metadata linking back to the public repository (`repository`, `homepage`, `bugs`) so the package page reaches its source.
+- Sharpened the README opening with a one-line value proposition and a 90-second start path; rewrote the quickstart routing paragraph so every internal term is defined inline.
+- Added stale-lock recovery to the plan store: cooperative locks older than a configurable TTL are recovered instead of blocking forever, while fresh foreign locks still fail closed.
+- Added a persisted-schema migration scaffold with a typed unsupported-version error (`plan.schema.unsupported`).
+- Published the `boulder-evidence-format` draft spec and JSON schemas under `spec/evidence-format/`.
+- Added `scripts/adoption-ledger.sh` as dev-only tooling (outside the published package) for monthly download observations.
+- Kept the release boundary explicit: zero runtime dependencies, local-first execution, and approval-gated external providers are unchanged.
+
 ## 0.1.16
 
 - Added `boulder routine capture` for repo-local repeated-work metadata.

README.md

@@ -1,11 +1,21 @@
 # boulder
 
-A min9lin9 operator kit for turning OSS repositories into evidence-backed Codex workflows.
+Turn any OSS repository into a workspace where AI coding agents plan, execute, and verify under your control - with signed evidence you can audit.
 
-Boulder makes an OSS repo agent-ready without giving up maintainer control. It creates repo briefs, operator contracts, workflow boundaries, release checks, replay fixtures, and exportable Codex notes.
+Boulder makes an OSS repo agent-ready without giving up maintainer control. It creates repo briefs, operator contracts, workflow boundaries, release checks, replay fixtures, and exportable Codex notes. Nothing executes without your approval.
 
-Current published package: `boulder-oss-cli@0.1.16`.
-Current release candidate: `v0.1.16`.
+**Start in 90 seconds:** `bunx boulder-oss-cli@latest init && bunx boulder-oss-cli@latest quickstart` - `quickstart` verifies your local installation and prints your next commands.
+
+## How Boulder works
+
+1. **Intake** - `init` reads the repository shape and writes the operator contract.
+2. **Plan** - `bootstrap interview` and `profile resolve` map the task onto the right workflow profile.
+3. **Execute** - approved packets run through gated adapters (`v2 execute`, `handoff packet`).
+4. **Verify** - `doctor`, `release-check`, and `replay-check` prove the result before anyone trusts it.
+5. **Record** - signed receipts, run events, and `export` leave an audit trail behind.
+
+Current published package: `boulder-oss-cli@0.1.17`.
+Current release candidate: `v0.1.17`.
 
 ## 3-minute route for non-developers
 
@@ -125,9 +135,9 @@ The designer chooses one of the built-in bootstrap profiles: `programming-heavy`
 For recurring work outside interviews, use the learning loop docs directly:
 
 ```bash
-boulder routine capture --task "weekly release note draft"
+boulder routine capture --task "weekly release note draft" --dry-run
 boulder retro weekly --dry-run
-boulder skill propose --from-routine <routine-id>
+boulder skill propose --from-routine <routine-id> --dry-run
 ```
 
 Recommended order:
@@ -155,6 +165,17 @@ gjc setup hermes --root . --smoke
 Live planning delegation through `gjc_delegate_plan` is suggested only after packet review and explicit approval.
 
 See [`docs/BOULDER_CODEX_SKILL_USAGE.ko.md`](docs/BOULDER_CODEX_SKILL_USAGE.ko.md).
+## Explicit boulder-native Preview
+
+`boulder-native-preview` is an opt-in local planning preview; it does not replace `programming-default`. Select it explicitly with `boulder profile use boulder-native-preview`, then use `plan analyze`, `plan show`, and `plan validate` only to inspect local inputs and plan artifacts:
+
+```bash
+boulder plan analyze --task "review the release workflow" --friction focused --json
+boulder plan show --run-id <run-id> --json
+boulder plan validate --input <packet-path> --artifact packet --json
+```
+
+These commands are read-only: they do not install software, contact providers, invoke external agents, mutate product files, or execute a plan. Preview planning approval and execution approval are separate explicit decisions. Any preview event evidence is local-only and remains in `.boulder/`; an external bridge from this preview to Handoff is a follow-up RFC, not a shipped feature. Boulder Handoff v1 remains the existing sanitized packet and review flow.
 
 ## Core Commands
 
@@ -179,9 +200,9 @@ boulder replay-run --dry-run
 boulder release-check
 boulder product-readiness
 boulder service-readiness
-boulder routine capture --task "<text>"
+boulder routine capture --task "<text>" --dry-run
 boulder retro weekly --dry-run
-boulder skill propose --from-routine <routine-id>
+boulder skill propose --from-routine <routine-id> --dry-run
 boulder export
 ```
 

docs/AGENTS.md

@@ -14,7 +14,8 @@ Documentation is product surface. Keep it aligned with actual CLI behavior and e
 | Bootstrap profiles/interview | `BOOTSTRAP_PROFILE_RESEARCH.md`, `BOOTSTRAP_INTERVIEW_RESEARCH.md`, `BOULDER_CODEX_SKILL_USAGE.ko.md` |
 | Capability source/doctor | `CAPABILITY_DOCTOR.md`, `GJC_LAZYCODEX_HANDOFF.md` |
 | Architecture | `WORKFLOW_ARCHITECTURE.md`, `OPERATOR_WORKFLOW_STACK.md` |
-| Product gates | `PRODUCT_READINESS.md`, `SERVICE_READINESS.md`, `RELEASE_WORKFLOW.md` |
+| Product gates | `PRODUCT_READINESS.md`, `SERVICE_READINESS.md`, `RELEASE_WORKFLOW.md`, `RELEASE_PLAN.md`, `VERIFICATION_GATES.md` |
+| Policy/process | `contributing/`, `adr/`, `branch-protection.md`, `labels-and-milestones.md` |
 | Evidence | `CASE_STUDIES/`, `APPLICATION_EVIDENCE.md`, `CODEX_OSS_FINAL_AUDIT.md` |
 
 ## CONVENTIONS
@@ -23,6 +24,8 @@ Documentation is product surface. Keep it aligned with actual CLI behavior and e
 - Separate recommendation, dry-run, doctor verification, and approval-gated use.
 - For Korean docs, keep the user path short and concrete.
 - Do not claim external tools are installed just because a profile recommends them.
+- Contract-first (ADR 0002): command names, flags, stdout/stderr, exit codes, `boulder.yaml`, pipeline JSON, provider policy, and protected paths change together — code, tests, docs, fixtures, and evidence in one change.
+- Docs-only changes still state why no behavior test was needed (see `contributing/review-policy.md`).
 
 ## ANTI-PATTERNS
 

docs/BENCHMARK_PLAN.md

@@ -1,46 +1,42 @@
 # Benchmark Plan
 
-Boulder benchmark work is deliberately fixture-first.
+## Scope and evidence boundary
 
-It does not claim:
+PR8A provides local, deterministic **tooling contracts** for preregistration and evidence verification. It does not perform, report, or imply a field study. In particular, the checked-in planner-benchmark study-root fixture contains no operational run outcomes, scores, comparisons, or promotion result; other planning-contract fixtures may contain clearly structural schema examples.
 
-- runtime speed leadership
-- model quality comparison
-- benchmark leaderboard placement
+PR8B is a separate external operation. Operators may conduct it under their own approvals and policies; this repository neither contacts providers nor executes the 36 runs, and external operational outcomes are not checked into the package fixtures.
 
-It does measure whether benchmark fixtures specify repeatable maintainer-harness expectations:
+## 36-run preregistration matrix
 
-- expected generated files
-- expected verification commands
-- provider and secret-handling boundaries
-- disallowed claims
+The study-root contract freezes the intended matrix before evidence is accepted:
 
-Current fixtures:
+- planners: `gjc`, `boulder-native`, `lazycodex-ulw-plan`
+- task classes: `small-bug`, `medium-feature`, `high-risk-change`
+- repository shapes: `small-ts-cli`, `medium-multi-module`
+- repeats per planner/task/repository cell: `2`
 
-- `fixtures/benchmarks/typescript-library.json`
-- `fixtures/benchmarks/python-package.json`
-- `fixtures/benchmarks/mcp-server.json`
+That is `3 × 3 × 2 × 2 = 36` required runs. The checked-in metadata preregisters the matrix but is not proof that any run occurred; externally retained operational evidence must be verified separately.
 
-Run:
+`fixtures/planner-benchmarks/study-root.json` is a deterministic, fixture-only study-root envelope with the preregistered protocol, manifest, and empty evidence bundle. It deliberately carries no trust root. `fixtures/planner-benchmarks/invalid-study-root.json` is a negative contract fixture whose matrix count is not 36.
 
-```bash
-boulder benchmark
-```
+## Trust, invocation, and HOLD
 
-Automation output:
+An operator must supply the Ed25519 trust root separately from the study root. Trust material is never accepted from the bundle being verified:
 
 ```bash
-boulder benchmark --json
+boulder plan benchmark \
+  --trust-root /secure/operator/trust-root.json \
+  --study-root /secure/operator/study-root.json
 ```
 
-M1 does not claim benchmark leadership.
+The trust root authorizes the protocol signer and delegated manifest, bundle, and execution-receipt signers. For a performed study, the verifier requires a signed artifact index and loads every indexed file as bytes from the study-root directory. It rejects byte sets that are missing or extra relative to that signed index, as well as duplicate, traversal, symlink, non-file, and digest-mismatched evidence; signed auxiliary artifacts are allowed only when indexed and byte-verified. A compact envelope remains valid for the shipped `NOT_PERFORMED` fixture; a performed envelope must carry the equivalent indexed evidence bytes or it fails closed.
+
+Eligibility is derived rather than declared. Every one of the 36 scored cell/repeat rows must join to a byte-verified raw-run record, normalization artifact, trusted-source catalog, blinded score lock/reveal mapping, and indexed `boulder.planner-execution-receipt.v1` wrapper Ed25519-signed by a key delegated for the `executor` role. That wrapper must bind an indexed `boulder.common-executor-receipt.v1` whose `executorModel` is exactly `openai-codex/gpt-5.6-sol`. Passed receipts must bind zero executor/test/typecheck exit codes, a patch digest, and indexed patch/test/typecheck output bytes. The verifier recomputes score caps, AC traceability, scored execution status, exclusions, replacement edges, RFC task-class weighting, target minimum, and repeat variance. Any scored execution failure, critical cap, incomplete traceability, invalid replacement, retrospective lock attestation, or insufficient eligible matrix produces an explicit `HOLD` reason. A malformed pre-score attempt may be replaced only through the signed immediate same-cell/repeat exclusion edge. A high average cannot compensate for a safety failure.
+
+The checked-in signatures and key identifiers are explicitly fixture-only placeholders for structural tests. They are not operational credentials, field-study evidence, or signatures that an operator may trust. Real PR8B evidence requires operator-controlled Ed25519 keys and verifiable signatures.
 
-Future evaluation should measure:
+## Immutable evidence rules
 
-- harness generation completeness
-- verification command accuracy
-- maintainer workflow coverage
-- export usefulness for Codex
-- failure-mode clarity
+PR8B evidence is append-only by identity: raw-run artifacts retain safe relative paths and content digests; normalized records bind to their raw-run digest; exclusions require adjudication evidence. A replacement run carries `replacesRunId`, immediately follows the excluded run for the same cell and repeat, and is joined to the corresponding exclusion edge. Do not overwrite an accepted evidence artifact. Publish a new signed bundle/report that references the prior immutable evidence instead.
 
-Claims should be backed by repeatable fixtures and saved reports.
+A valid contract or a `HOLD` report demonstrates only tooling behavior. Automated blinded review is exploratory evidence, not external maintainer evidence or proof of planner superiority. Tooling readiness and a signed HOLD report do not authorize fallback/preferred promotion.

docs/CAPABILITY_DOCTOR.md

@@ -10,6 +10,11 @@ The doctor answers three questions before Boulder hands work to GJC, LazyCodex,
 - which workflow lane each capability should serve
 - what official documentation or runtime compatibility issue must be handled before use
 
+## Explicit boulder-native Preview
+
+`boulder-native-preview` is an explicit local planning profile, not a replacement for `programming-default`. Its `plan analyze`, `plan show`, and `plan validate` commands are read-only: they inspect local inputs or artifacts and do not install software, contact providers, invoke external agents, mutate product files, or execute a plan.
+
+Preview planning approval and execution approval are separate explicit decisions. Preview event evidence is local-only in `.boulder/`. An external bridge from preview output to Handoff is follow-up RFC work and is not implemented; it is not current doctor behavior.
 ## Inventory
 
 Default inventory path:

docs/CASE_STUDIES/AGENTS.md

@@ -0,0 +1,49 @@
+# CASE STUDIES KNOWLEDGE BASE
+
+Status: active
+Scope: `docs/CASE_STUDIES/`
+
+## OVERVIEW
+
+Case studies are public-facing proof docs backed by checked-in evidence artifacts. They must read as reproducible product evidence, not narrative claims alone.
+
+## STRUCTURE
+
+| Path | Purpose |
+| --- | --- |
+| `README.md` | Case study index and navigation |
+| `*.md` | Scenario narratives tied to concrete Boulder workflows |
+| `evidence/` | Raw or summarized command outputs, manifests, and replay artifacts |
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+| --- | --- | --- |
+| Add a new case study | `README.md`, then a peer `*.md` file | Keep titles and scenario names consistent |
+| Release workflow evidence | `release-workflow.md`, `evidence/release-workflow/` | Include manifest and dry-run/package proof |
+| PR/review evidence | `pr-review.md`, `evidence/pr-review/` | Preserve command outputs that back the claim |
+| External replay evidence | `external-replay.md`, `evidence/external-replay/` | Keep replay constraints explicit and dry-run scoped |
+| Core implementation evidence | `core-implementation.md`, `evidence/core-implementation/` | Tie behavior claims to tests or CLI output |
+
+## CONVENTIONS
+
+- Every claim about Boulder behavior needs a nearby evidence file or a command that can regenerate it.
+- Evidence paths should be stable and scenario-named; do not bury release evidence in generic scratch directories.
+- Keep commands copy-pasteable from the repo root unless the text explicitly says otherwise.
+- Separate observed output from interpretation. Markdown narrative explains; evidence files prove.
+- Prefer compact excerpts over pasted full terminal sessions when the full output adds no new contract.
+
+## ANTI-PATTERNS
+
+- No aspirational success language without a referenced artifact.
+- No evidence that depends on local private paths, secrets, or uncommitted workspace state.
+- No framing `capability import --dry-run` as installation.
+- No suggesting `doctor` installs, updates, or enables tools.
+- No hiding failed gates behind prose caveats; update the product or mark the case study incomplete.
+
+## CHECKS
+
+```bash
+bun test test/product-readiness.test.ts test/readiness-reports.test.ts
+bun bin/boulder.ts release-check --cwd . --json
+```

docs/CASE_STUDIES/evidence/release-workflow/github-actions.txt

@@ -1,4 +1,4 @@
 CI
 Result: success
 Run: https://github.com/min9lin9/boulder/actions/runs/28885567998
-Commit: 6671bcaceb4b35180a5756d6a340798ccdf3c206
+Commit: a0bb9107a602c3529dc8ab484ce86c9fba2ad906

docs/CASE_STUDIES/evidence/release-workflow/install-smoke.txt

@@ -1,8 +1,20 @@
-bunx boulder-oss-cli@0.1.16 --version
+bunx boulder-oss-cli@0.1.17 --version
+0.1.17
 Published help smoke:
 bunx boulder-oss-cli --help
+boulder
+
+A min9lin9 operator kit for turning OSS repositories into evidence-backed Codex workflows.
+
 Usage:
-Published version: 0.1.16
+
+Versioned help smoke:
+bunx boulder-oss-cli@0.1.17 --help
+boulder
+
+A min9lin9 operator kit for turning OSS repositories into evidence-backed Codex workflows.
+
+Published version: 0.1.17
 Result: success
-Generated at: 2026-07-07
+Generated at: 2026-08-26
 exit: 0

docs/CASE_STUDIES/evidence/release-workflow/pack-dry-run.txt

@@ -1,3 +1,3 @@
 boulder-oss-cli
 Package version: 0.1.16
-Total files: 210
+Total files: 222

docs/CASE_STUDIES/evidence/release-workflow/release-evidence-plan.json

@@ -15,7 +15,7 @@
     {
       "id": "pack-dry-run-evidence",
       "status": "pass",
-      "evidence": "210 files"
+      "evidence": "222 files"
     },
     {
       "id": "release-evidence-manifest",

docs/CASE_STUDIES/evidence/release-workflow/release-manifest.json

@@ -1,23 +1,25 @@
 {
   "schemaVersion": 1,
   "packageName": "boulder-oss-cli",
-  "packageJsonVersion": "0.1.16",
-  "cliVersion": "0.1.16",
-  "tag": "v0.1.16",
-  "tagCommit": "df3538c7ed0dd7f1b50d4644c6e47204ede45ea7",
-  "releaseCommit": "6671bcaceb4b35180a5756d6a340798ccdf3c206",
-  "publishedVersion": "0.1.16",
+  "packageJsonVersion": "0.1.17",
+  "cliVersion": "0.1.17",
+  "tag": "v0.1.17",
+  "tagCommit": "a0bb9107a602c3529dc8ab484ce86c9fba2ad906",
+  "releaseCommit": "a0bb9107a602c3529dc8ab484ce86c9fba2ad906",
+  "publishedVersion": "0.1.17",
   "installSmoke": {
-    "command": "bunx boulder-oss-cli@0.1.16 --version",
+    "command": "bunx boulder-oss-cli@0.1.17 --version",
     "exitCode": 0,
-    "generatedAt": "2026-07-07"
+    "generatedAt": "2026-08-26"
   },
   "githubActions": {
     "runUrl": "https://github.com/min9lin9/boulder/actions/runs/28885567998"
   },
   "packDryRun": {
-    "fileCount": 210,
-    "packageVersion": "0.1.16"
+    "fileCount": 268,
+    "packageVersion": "0.1.17"
   },
-  "limitations": []
+  "limitations": [
+    "GitHub Actions run evidence pending push of v0.1.17 release commit"
+  ]
 }