biotonomy 0.1.0 → 0.2.1

package/README.md

@@ -1,180 +1,207 @@
 # Biotonomy
 
-Biotonomy is a CLI that runs Codex loops (research→implement→review→fix) inside your repo.
-It enforces quality gates (lint/typecheck/test) between stages and records everything as files.
-PR automation is now first-class (`bt pr` / `bt ship`) and keeps deterministic artifacts for every run.
+Biotonomy is a command-line workflow for shipping code changes with Codex.
 
-Biotonomy is intentionally file-based:
-- project config lives in `.bt.env`
-- ephemeral state lives in `.bt/`
-- feature state lives in `specs/<feature>/`
+- What it is: A CLI that runs a repeatable flow: `spec -> research -> implement -> review -> fix -> pr`.
+- Who it is for: Developers who want a structured way to ship small changes fast.
+- What problem it solves: Keeps work organized in files, runs quality checks, and reduces "what do I do next?" during AI-assisted coding.
 
-## The Codex Loop
+## 60-Second Quickstart
 
-For a feature folder `specs/<feature>/`, the loop is:
+Install either way:
 
-1. `bt spec <feature>`: create `SPEC.md` (or `bt spec <issue#>` to pull from GitHub via `gh`)
-2. `bt research <feature>`: Codex writes `RESEARCH.md` (Codex required)
-3. `bt implement <feature>`: Codex applies code changes + Biotonomy runs quality gates
-4. `bt review <feature>`: Codex reviews into `REVIEW.md` (writes a stub if Codex is missing)
-5. `bt fix <feature>`: Codex applies targeted fixes + Biotonomy runs quality gates
-
-Supporting commands:
-- `bt status`: summarize story status from `SPEC.md` plus latest `gates.json` (if present)
-- `bt gates [<feature>]`: run gates and write `gates.json` (feature-local or global)
-- `bt reset`: delete `.bt/` and `specs/**/.lock` (does not modify your git working tree)
+```bash
+npm i -g biotonomy
+# then use: bt ...
+```
 
-## Ship Archie (Walkthrough)
+```bash
+npx biotonomy ...
+```
 
-This is the intended "ship a feature" path. Some steps are still manual; each TODO points at the tracking issue.
+Minimal demo in a fresh repo:
 
 ```bash
-# 0) Install
-npm install -g biotonomy
+mkdir biotonomy-demo && cd biotonomy-demo
+git init
+npm init -y
+
+npx biotonomy bootstrap
+npx biotonomy spec hello-world
+npx biotonomy review hello-world
+npx biotonomy status
+```
 
-# 1) Initialize the repo for Biotonomy (creates .bt.env, specs/, .bt/)
-bt bootstrap
+Expected files after the demo:
 
-# 2) Create a spec (local feature name)
-bt spec archie
+- `.bt.env`
+- `.bt/`
+- `specs/hello-world/SPEC.md`
+- `specs/hello-world/REVIEW.md`
+- `specs/hello-world/progress.txt`
+- `specs/hello-world/history/001-spec.md`
+- `specs/hello-world/history/002-review.md`
+- `specs/hello-world/.artifacts/codex-review.log`
 
-# (Optional) If "Archie" is a GitHub issue:
-# bt spec 123   # pulls issue title/body via `gh` into specs/issue-123/SPEC.md
+Notes:
 
-# 3) Research (requires Codex; see Issue #3 for the end-to-end loop/demo harness)
-bt research archie
+- `review` still creates `REVIEW.md` even if Codex is not installed.
+- `research` requires Codex.
 
-# 4) Implement (runs gates; if Codex is unavailable this records history and still runs gates)
-bt implement archie
+## Ship A Small Change
 
-# 5) Review (writes specs/archie/REVIEW.md; stub output if Codex is unavailable)
-bt review archie
+Use this for a real change from idea to PR.
 
-# 6) Fix until review is clean (gates are re-run)
-bt fix archie
+1. `spec` (define the change)
 
-# 7) Check progress at any time
-bt status
+```bash
+bt spec my-change
+# or from GitHub issue:
+# bt spec 123
 ```
 
-Tracked work (open issues):
-- Core loop expansion (`bt loop` style driver and polish): [Issue #10](https://github.com/archive-dot-com/biotonomy/issues/10), [Issue #3](https://github.com/archive-dot-com/biotonomy/issues/3)
-- Release readiness and publish workflow (`npm i -g biotonomy`): [Issue #7](https://github.com/archive-dot-com/biotonomy/issues/7)
-- Docs refresh for Archie walkthrough and current commands: [Issue #8](https://github.com/archive-dot-com/biotonomy/issues/8), [Issue #1](https://github.com/archive-dot-com/biotonomy/issues/1)
-- Reliability hardening and bugfixes: [Issues #13-#17](https://github.com/archive-dot-com/biotonomy/issues)
+- Automated today: creates `specs/<feature>/SPEC.md`, history, and progress logs.
+- Manual today: fill in/clean up stories and acceptance criteria in `SPEC.md`.
 
-## Artifacts And Layout
+2. `research` (gather context)
 
-Biotonomy is minimal bash plus prompt templates:
-- `bt.sh`: CLI entrypoint and router
-- `commands/*.sh`: command implementations
-- `lib/*.sh`: shared helpers (env loading, state paths, notifications, gates, Codex exec)
-- `prompts/*.md`: prompt templates for Codex stages
-- `hooks/*`: example notification hooks
+```bash
+bt research my-change
+```
 
-On disk, expect:
-- `.bt.env`: project config (parsed as `KEY=VALUE` without `source` / without executing code)
-- `.bt/`: ephemeral state (locks/caches; safe to delete via `bt reset`)
-- `specs/<feature>/SPEC.md`: plan and story statuses (parseable; created by `bt spec`)
-- `specs/<feature>/RESEARCH.md`: research notes (`bt research`)
-- `specs/<feature>/REVIEW.md`: review verdict + findings (`bt review`)
-- `specs/<feature>/gates.json`: latest gate results when running `bt gates <feature>`
-- `specs/<feature>/progress.txt`: timestamped progress log
-- `specs/<feature>/history/*.md`: append-only run history for each stage
-- `specs/<feature>/.artifacts/*`: captured stderr from Codex/gh for debugging/repro
+- Automated today: runs Codex in read-only mode and writes `RESEARCH.md`.
+- Manual today: confirm research quality and adjust plan if needed.
 
-## Quality Gates
+3. `implement` (make the change)
 
-Stages that run gates:
-- `bt implement <feature>`
-- `bt fix <feature>`
-- `bt gates [<feature>]`
+```bash
+bt implement my-change
+```
+
+- Automated today: runs Codex in full-auto and then runs quality gates.
+- Manual today: if Codex is unavailable, this stage is a stub and you implement changes yourself.
 
-Gate configuration:
-- Override per-project in `.bt.env` via `BT_GATE_LINT`, `BT_GATE_TYPECHECK`, `BT_GATE_TEST`
-- If unset, Biotonomy tries simple auto-detection (npm/yarn/pnpm/Makefile)
+4. `review` (check what changed)
+
+```bash
+bt review my-change
+```
 
-## PR Automation (Opt-In Today)
+- Automated today: writes `REVIEW.md` (with a fallback stub if Codex fails).
+- Manual today: decide whether findings are acceptable for your team.
 
-There is currently a safe helper script (defaults to `--dry-run`) that uses `git` and `gh`:
+5. `fix` (address findings)
 
 ```bash
-npm run pr:open -- archie --dry-run
-npm run pr:open -- archie --run
+bt fix my-change
 ```
 
-It determines the branch from `specs/<feature>/SPEC.md` frontmatter (`branch:`) when present, otherwise uses `feat/<feature>`.
-The planned end state is a first-class `bt pr ...` flow. Tracked in [Issue #8](https://github.com/archive-dot-com/biotonomy/issues/8).
+- Automated today: runs Codex fix pass and re-runs quality gates.
+- Manual today: rerun until you are satisfied; no built-in auto-loop to "done" yet.
+
+6. `pr` (open pull request)
+
+```bash
+bt pr my-change --dry-run
+bt pr my-change --run
+```
 
-## Demos
+- Automated today: runs tests/lint, creates branch, optionally commits, pushes, opens PR via `gh`.
+- Manual today: choose reviewers/labels, final PR polish, and merge strategy.
 
-### Issue #3 Real Loop (End-to-End, Deterministic)
+## Current Limitations
 
-This repo includes an end-to-end "real loop" runner that:
-- runs the actual `bt.sh` entrypoint
-- uses a deterministic workspace
-- stubs `gh` and `codex` so it is reproducible offline
-- writes a scrubbed transcript + snapshot under `specs/issue-3-real-loop/`
+- No one-command autonomous loop yet (you run each stage yourself).
+- `research` needs Codex installed and available.
+- `implement`/`fix` can run as stubs without Codex (gates still run, code may not change).
+- PR flow depends on `gh` and repository permissions.
+
+## Troubleshooting
+
+`gh` auth fails (`bt spec 123` or `bt pr ...`):
 
 ```bash
-npm install
-npm run demo
+gh auth status
+gh auth login
+```
+
+Codex missing (`codex required` or `codex not found`):
+
+- Install Codex and make sure `codex` is on your `PATH`.
+- Or set a custom binary in `.bt.env`: `BT_CODEX_BIN=/path/to/codex`.
 
-ls -R specs/issue-3-real-loop
-sed -n '1,120p' specs/issue-3-real-loop/transcript.txt
-sed -n '1,120p' specs/issue-3-real-loop/snapshot.txt
+Quality gate failures on `implement`/`fix`:
+
+```bash
+bt gates my-change
 ```
 
-## Install
+- Fix failing lint/typecheck/test commands.
+- Override gate commands in `.bt.env` if auto-detection is wrong:
+  - `BT_GATE_LINT=...`
+  - `BT_GATE_TYPECHECK=...`
+  - `BT_GATE_TEST=...`
+
+## Release Publish Steps
+
+Use this when preparing an npm release. This workflow validates readiness but does not publish automatically.
+
+1. Confirm clean main branch and pull latest changes.
 
-Global install:
+```bash
+git checkout main
+git pull --ff-only
+```
+
+2. Run release preflight checks (tests, lint, pack verification, and `npm pack --dry-run` summary).
 
 ```bash
-npm install -g biotonomy
-bt --help
+npm run release:ready
 ```
 
-Local (repo) usage:
+3. Ensure npm authentication is ready for publish.
 
 ```bash
-npx biotonomy --help
+npm whoami
+# if needed:
+npm login
 ```
 
-## Targeting A Repo From Anywhere
+4. Bump version and create a tag.
 
-By default, `bt` uses your current working directory as the project root.
+```bash
+npm version patch
+# or: npm version minor / npm version major
+```
 
-To run against a different repo, use `--target <path>` (sets `BT_TARGET_DIR` for that invocation):
+5. Push commit and tag.
 
 ```bash
-bt --target /path/to/repo bootstrap
-bt --target /path/to/repo status
-bt --target /path/to/repo spec archie
+git push --follow-tags
 ```
 
-You can also set `BT_TARGET_DIR` in the environment (same behavior):
+6. Publish manually.
 
 ```bash
-BT_TARGET_DIR=/path/to/repo bt status
+npm publish --access public
 ```
 
-## Status (v0.1.0)
+- If your npm account uses 2FA for publish, npm will require a one-time code during `npm publish`.
 
-Implemented today:
-- File-based loop artifacts: `.bt.env`, `.bt/`, `specs/<feature>/...`
-- `bt bootstrap`, `bt spec <feature>`, `bt status`, `bt gates`, `bt reset`
-- `bt review` produces `REVIEW.md` even without Codex (stub output + required `Verdict:` line)
-- `bt implement` and `bt fix` always run quality gates and record history; if Codex is missing they behave as stubs (no code changes)
-- `bt research` requires Codex (it dies early if `codex` is not available)
-- Opt-in PR helper (`npm run pr:open`) with `--dry-run` by default
+## Commands
 
-In progress (tracked in open issues):
-- [Issue #10](https://github.com/archive-dot-com/biotonomy/issues/10): add a first-class loop driver (implement→review→fix until APPROVE + gates pass)
-- [Issue #3](https://github.com/archive-dot-com/biotonomy/issues/3): complete Codex-native loop ergonomics
-- [Issue #7](https://github.com/archive-dot-com/biotonomy/issues/7): publish workflow + npm readiness
-- [Issue #8](https://github.com/archive-dot-com/biotonomy/issues/8): docs rewrite around Codex loop + Archie walkthrough
-- [Issue #12](https://github.com/archive-dot-com/biotonomy/issues/12): close stale “already done” tracker issues
-- [Issues #13-#17](https://github.com/archive-dot-com/biotonomy/issues): active bugfix queue
+```bash
+bt bootstrap
+bt spec <feature|issue#>
+bt research <feature>
+bt implement <feature>
+bt review <feature>
+bt fix <feature>
+bt gates [feature]
+bt status
+bt pr <feature> [--dry-run|--run]
+bt reset
+```
 
 ## Development
 
@@ -182,5 +209,3 @@ In progress (tracked in open issues):
 npm test
 npm run lint
 ```
-
-Lint uses `shellcheck` if it is installed; otherwise it skips with a warning (CI installs shellcheck and runs strict).

package/bt.sh

@@ -41,7 +41,7 @@ Usage:
   bt [--target <path>] <command> [args]
 
 Commands:
-  bootstrap  spec  research  implement  review  fix  compound  design  status  gates  reset  pr  ship
+  bootstrap  spec  research  implement  review  fix  loop  compound  design  status  gates  reset  pr  ship
 
 Global options:
   -h, --help     Show help
@@ -99,7 +99,7 @@ bt_dispatch() {
   bt_env_load || true
 
   case "$cmd" in
-    bootstrap|spec|research|implement|review|fix|compound|design|status|gates|reset|pr|ship) ;;
+    bootstrap|spec|research|plan-review|implement|review|fix|loop|compound|design|status|gates|reset|pr|ship) ;;
     *)
       bt_err "unknown command: $cmd"
       bt_usage >&2
@@ -119,11 +119,15 @@ bt_dispatch() {
   # shellcheck source=/dev/null
   source "$cmd_file"
 
-  local fn="bt_cmd_$cmd"
+  local safe_cmd="${cmd//-/_}"
+  local fn="bt_cmd_$safe_cmd"
   if [[ "$cmd" == "ship" ]]; then
     fn="bt_cmd_pr"
   fi
 
+  # Log for debugging
+  # bt_info "dispatching to $fn"
+
   if ! declare -F "$fn" >/dev/null 2>&1; then
     bt_die "command function not found: $fn (in $cmd_file)"
   fi

package/commands/bootstrap.sh

@@ -15,6 +15,14 @@ EOF
   # Operate within the effective project root (BT_TARGET_DIR if set).
   local root="${BT_PROJECT_ROOT:-$PWD}"
 
+  local critical_dir
+  for critical_dir in "specs" ".bt" "hooks"; do
+    local critical_path="$root/$critical_dir"
+    if [[ -e "$critical_path" && ! -d "$critical_path" ]]; then
+      bt_die "critical scaffold path exists as a file: $critical_path"
+    fi
+  done
+
   local env_path="$root/.bt.env"
   if [[ -f "$env_path" ]]; then
     bt_info "found existing .bt.env"

package/commands/fix.sh

@@ -35,9 +35,13 @@ EOF
     mkdir -p "$artifacts_dir"
     codex_logf="$artifacts_dir/codex-fix.log"
     : >"$codex_logf"
-    if ! BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_full_auto "$BT_ROOT/prompts/fix.md"; then
+    if BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_full_auto "$BT_ROOT/prompts/fix.md"; then
+      codex_ec=0
+    else
       codex_ec=$?
       bt_warn "codex exited non-zero (fix): $codex_ec"
+      bt_die "codex failed (fix), stopping."
+      return 1
     fi
   else
     codex_ec=127

package/commands/implement.sh

@@ -25,6 +25,18 @@ EOF
   dir="$(bt_feature_dir "$feature")"
   [[ -d "$dir" ]] || bt_die "missing feature dir: $dir (run: bt spec ...)"
 
+  local plan_review="$dir/PLAN_REVIEW.md"
+  if [[ ! -f "$plan_review" ]]; then
+    bt_err "missing $plan_review"
+    bt_err "run: bt plan-review $feature"
+    bt_die "implement hard-fails without approved PLAN_REVIEW verdict"
+  fi
+
+  if ! grep -qiE "Verdict:.*(APPROVE_PLAN|APPROVED_PLAN)" "$plan_review"; then
+    bt_err "PLAN_REVIEW.md exists but is not approved."
+    bt_die "implement hard-fails without approved PLAN_REVIEW verdict"
+  fi
+
   bt_progress_append "$feature" "implement: bt implement $feature (starting)"
 
   local codex_ec=0
@@ -35,9 +47,13 @@ EOF
     mkdir -p "$artifacts_dir"
     codex_logf="$artifacts_dir/codex-implement.log"
     : >"$codex_logf"
-    if ! BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_full_auto "$BT_ROOT/prompts/implement.md"; then
+    if BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_full_auto "$BT_ROOT/prompts/implement.md"; then
+      codex_ec=0
+    else
       codex_ec=$?
       bt_warn "codex exited non-zero (implement): $codex_ec"
+      bt_die "codex failed (implement), stopping."
+      return 1
     fi
   else
     codex_ec=127

package/commands/loop.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# biotonomy loop command
+# Implement -> Review -> Fix loop until review is APPROVED and gates pass
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_loop_usage() {
+  cat <<EOF
+Usage: bt loop <feature> [options]
+
+Repeatedly runs implement/review/fix until review returns Verdict: APPROVED 
+and quality gates pass.
+
+Options:
+  --max-iterations <n>  Maximum number of retry loops (default: 5)
+  -h, --help            Show this help
+EOF
+}
+
+bt_cmd_loop() {
+  local max_iter=5
+  local feature=""
+
+  while [[ $# -gt 0 ]]; do
+    case "${1:-}" in
+      -h|--help) bt_loop_usage; return 0 ;;
+      --max-iterations)
+        if [[ $# -lt 2 || -z "${2:-}" || "${2:-}" == -* ]]; then
+          bt_err "--max-iterations requires a value"
+          return 2
+        fi
+        max_iter="$2"
+        shift 2
+        ;;
+      -*)
+        bt_err "unknown flag: $1"
+        return 2
+        ;;
+      *)
+        feature="$1"
+        shift
+        ;;
+    esac
+  done
+
+  if [[ -z "$feature" ]]; then
+    bt_err "feature name is required"
+    return 2
+  fi
+
+  if ! [[ "$max_iter" =~ ^[1-9][0-9]*$ ]]; then
+    bt_err "--max-iterations must be a positive integer"
+    return 2
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  bt_info "starting loop for: $feature (max iterations: $max_iter)"
+
+  bt_info "running preflight gates..."
+  if ! bt_run_gates; then
+    bt_err "preflight gates failed; aborting before implement/review"
+    return 1
+  fi
+  bt_info "preflight gates: PASS"
+
+  local feat_dir
+  feat_dir="$(bt_feature_dir "$feature")"
+  local plan_review="$feat_dir/PLAN_REVIEW.md"
+  if [[ ! -f "$plan_review" ]] || ! grep -qiE "Verdict:.*(APPROVE_PLAN|APPROVED_PLAN)" "$plan_review"; then
+    bt_err "missing or unapproved $plan_review"
+    bt_err "run: bt plan-review $feature"
+    bt_die "loop hard-fails without approved PLAN_REVIEW verdict before implement/review"
+  fi
+
+  # Source required commands so we can call them directly
+  # shellcheck source=/dev/null
+  source "$BT_ROOT/commands/implement.sh"
+  # shellcheck source=/dev/null
+  source "$BT_ROOT/commands/review.sh"
+  # shellcheck source=/dev/null
+  source "$BT_ROOT/commands/fix.sh"
+
+  local iter=0
+  local review_file
+  local feat_dir
+  feat_dir="$(bt_feature_dir "$feature")"
+  review_file="$feat_dir/REVIEW.md"
+  local history_dir="$feat_dir/history"
+  local progress_file="$feat_dir/loop-progress.json"
+
+  # Initialize progress
+  mkdir -p "$history_dir"
+  cat > "$progress_file" <<EOF
+{
+  "feature": "$feature",
+  "maxIterations": $max_iter,
+  "completedIterations": 0,
+  "result": "in-progress",
+  "iterations": []
+}
+EOF
+
+  # Ensure subcommands return non-zero instead of exiting the entire loop process.
+  export BT_DIE_MODE="return"
+
+  while [[ "$iter" -lt "$max_iter" ]]; do
+    iter=$((iter + 1))
+    bt_info "--- Iteration $iter / $max_iter ---"
+
+    # 1. Run Implement on every iteration
+    # Note: bt_cmd_implement already runs gates internally.
+    bt_info "running implement..."
+    if bt_cmd_implement "$feature"; then
+      :
+    else
+      bt_err "implement failed on iter $iter; aborting loop"
+      python3 - <<PY
+import json
+p = "$progress_file"
+with open(p, 'r') as f:
+    d = json.load(f)
+d['completedIterations'] = $iter
+d['result'] = 'implement-failed'
+d.setdefault('iterations', []).append({
+    "iteration": $iter,
+    "implementStatus": "FAIL",
+    "reviewStatus": "SKIP",
+    "fixStatus": "SKIP",
+    "verdict": "",
+    "gates": "FAIL",
+    "historyFile": ""
+})
+with open(p, 'w') as f:
+    json.dump(d, f, indent=2)
+PY
+      return 1
+    fi
+
+    # 2. Run Review
+    bt_info "running review..."
+    if bt_cmd_review "$feature"; then
+       :
+    else
+       bt_err "review process failed"
+       return 1
+    fi
+
+    # 3. Check Verdict
+    if [[ ! -f "$review_file" ]]; then
+       bt_err "REVIEW.md missing after review command"
+       return 1
+    fi
+
+    local verdict
+    verdict="$(awk '/^Verdict:/{print toupper($2); exit}' "$review_file" | tr -d '\r' || true)"
+    bt_info "verdict: $verdict"
+
+    # 4. Final Gate Check for convergence
+    # We use the gates result from the last command that ran them (implement/fix).
+    # bt_cmd_implement/fix return non-zero if gates fail, but we capture the status.
+    # We call bt_run_gates here just to be sure of the final state post-review.
+    local gates_ok=1
+    if ! bt_run_gates; then
+      gates_ok=0
+      bt_info "gates: FAIL"
+    else
+      bt_info "gates: PASS"
+    fi
+
+    local fix_status="SKIP"
+    if [[ "$verdict" == "NEEDS_CHANGES" ]]; then
+      bt_info "running fix..."
+      # Note: bt_cmd_fix already runs gates internally.
+      if bt_cmd_fix "$feature"; then
+        fix_status="PASS"
+      else
+        fix_status="FAIL"
+        bt_err "fix failed after iter $iter review; aborting loop"
+        return 1
+      fi
+    fi
+
+    # Record iteration
+    local ts
+    ts="$(date +%Y-%m-%dT%H%M%S%z)"
+    local iter_padded
+    iter_padded="$(printf "%03d" "$iter")"
+    local hist_file="$history_dir/$ts-loop-iter-$iter_padded.md"
+    cp "$review_file" "$hist_file"
+
+    # Update progress.json
+    python3 - <<PY
+import json, sys
+p = "$progress_file"
+with open(p, 'r') as f:
+    data = json.load(f)
+data['completedIterations'] = $iter
+data['iterations'].append({
+    "iteration": $iter,
+    "implementStatus": "PASS",
+    "reviewStatus": "PASS",
+    "fixStatus": "$fix_status",
+    "verdict": "$verdict",
+    "gates": "PASS" if "$gates_ok" == "1" else "FAIL",
+    "historyFile": "$hist_file"
+})
+with open(p, 'w') as f:
+    json.dump(data, f, indent=2)
+PY
+
+    if [[ ( "$verdict" == "APPROVE" || "$verdict" == "APPROVED" ) && "$gates_ok" == "1" ]]; then
+      python3 -c "import json; p='$progress_file'; d=json.load(open(p)); d['result']='success'; json.dump(d, open(p, 'w'), indent=2)"
+      bt_info "Loop successful! Verdict $verdict and Gates PASS."
+      return 0
+    fi
+
+    bt_info "Verdict is $verdict (or gates failed); looping..."
+  done
+
+  python3 -c "import json; p='$progress_file'; d=json.load(open(p)); d['result']='max-iterations-exceeded'; json.dump(d, open(p, 'w'), indent=2)"
+  bt_err "Loop reached max iterations ($max_iter) without approval."
+  return 1
+}

package/commands/plan-review.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_plan_review() {
+  # Feature name might start with - (e.g. bt plan-review -h)
+  # but shell parsing might be tricky.
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt plan-review <feature>
+
+Runs Codex in full-auto using prompts/plan-review.md to approve or reject the SPEC/RESEARCH plan.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local feature
+  feature="$(bt_require_feature "${1:-}")"
+
+  local dir
+  dir="$(bt_feature_dir "$feature")"
+  [[ -d "$dir" ]] || bt_die "missing feature dir: $dir (run: bt spec ...)"
+
+  local out="$dir/PLAN_REVIEW.md"
+
+  if bt_codex_available; then
+    bt_info "running codex (full-auto) using prompts/plan-review.md"
+    if BT_FEATURE="$feature" BT_CODEX_LOG_FILE="/tmp/codex.log" bt_codex_exec_full_auto "$BT_ROOT/prompts/plan-review.md"; then
+      :
+    else
+      bt_die "codex failed (plan-review)"
+    fi
+  else
+    # v0.1.0 stub
+    cat <<'EOF' > "$out"
+# Plan Review: Stub Approved
+
+Verdict: APPROVED_PLAN
+EOF
+    bt_info "wrote $out"
+  fi
+
+  if [[ ! -f "$out" ]]; then
+    bt_die "bt_cmd_plan_review failed: $out was not created"
+  fi
+
+  bt_history_write "$feature" "plan-review" "$(cat "$out")"
+  bt_notify "bt plan-review complete for $feature"
+}

package/commands/pr.sh

@@ -129,8 +129,22 @@ bt_cmd_pr() {
       --run) run_mode="run"; shift ;;
       --dry-run) run_mode="dry-run"; shift ;;
       --draft) draft=1; shift ;;
-      --base) base="${2:-}"; shift 2 ;;
-      --remote) remote="${2:-}"; shift 2 ;;
+      --base)
+        if [[ $# -lt 2 || "${2:-}" == -* ]]; then
+          bt_err "--base requires a value"
+          return 2
+        fi
+        base="${2:-}"
+        shift 2
+        ;;
+      --remote)
+        if [[ $# -lt 2 || "${2:-}" == -* ]]; then
+          bt_err "--remote requires a value"
+          return 2
+        fi
+        remote="${2:-}"
+        shift 2
+        ;;
       --no-commit) commit=0; shift ;;
       -*)
         bt_err "unknown flag: $1"
@@ -155,13 +169,7 @@ bt_cmd_pr() {
 
   bt_info "shipping feature: $feature"
 
-  # 1. Run Tests & Lint
-  bt_info "running tests..."
-  npm test
-  bt_info "running lint..."
-  npm run lint
-
-  # 2. Determine branch and metadata from SPEC.md
+  # 1. Determine branch and metadata from SPEC.md
   local specs_dir="${BT_SPECS_DIR:-specs}"
   local spec_file="$specs_dir/$feature/SPEC.md"
   local branch="feat/$feature"
@@ -180,7 +188,62 @@ bt_cmd_pr() {
     [[ -n "${i:-}" ]] && issue="$i"
   fi
 
-  # 3. Create branch if needed
+  # 2. Fail-loud preflight for unstaged expected files (before tests/commit flow).
+  if [[ "$commit" == "1" ]]; then
+    local unstaged=""
+    local check_paths=(tests lib commands scripts specs prompts) # Added specs and prompts
+    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      unstaged="$(git ls-files --others --modified --exclude-standard -- "${check_paths[@]}" 2>/dev/null || true)"
+    else
+      # Outside a git repo, treat present implementation files as unstaged by definition.
+      unstaged="$(find "${check_paths[@]}" -type f 2>/dev/null | LC_ALL=C sort || true)"
+    fi
+    if [[ -n "$unstaged" ]]; then
+      bt_err "Found unstaged files that might be required for this feature:"
+      printf '%s\n' "$unstaged" >&2
+      bt_die "Abort: ship requires all feature files to be staged. Use git add and try again."
+    fi
+  fi
+
+  if [[ "$run_mode" == "dry-run" ]]; then
+    if [[ -z "$base" ]]; then
+      if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        local ref
+        ref="$(git symbolic-ref -q "refs/remotes/$remote/HEAD" 2>/dev/null || true)"
+        if [[ -n "$ref" ]]; then
+          base="${ref##*/}"
+        else
+          base="main"
+        fi
+      else
+        base="main"
+      fi
+    fi
+
+    local title="feat: $feature"
+    local body="Feature: $feature"
+    [[ -n "$repo" && -n "$issue" ]] && body+=$'\n'"Issue: https://github.com/$repo/issues/$issue"
+    [[ -f "$spec_file" ]] && body+=$'\n'"Spec: $spec_file"
+
+    bt_info "[dry-run] git push -u $remote $branch"
+    bt_info "[dry-run] gh pr create --head $branch --base $base --title $title --body $body"
+    local artifacts_preview
+    artifacts_preview="$(mktemp "${TMPDIR:-/tmp}/bt-pr-artifacts-preview.XXXXXX")"
+    bt_pr_write_artifacts_comment "$feature" "$specs_dir" "$artifacts_preview"
+    bt_info "[dry-run] Artifacts comment would contain:"
+    cat "$artifacts_preview"
+    rm -f "$artifacts_preview"
+    bt_info "ship complete for $feature"
+    return 0
+  fi
+
+  # 3. Run tests & lint (run mode only)
+  bt_info "running tests..."
+  npm test
+  bt_info "running lint..."
+  npm run lint
+
+  # 4. Create branch if needed
   if git show-ref --verify --quiet "refs/heads/$branch"; then
     bt_info "branch $branch already exists, checking it out..."
     git checkout "$branch"
@@ -192,17 +255,13 @@ bt_cmd_pr() {
   # 4. Commit changes if requested
   if [[ "$commit" == "1" ]]; then
     bt_info "committing changes..."
-    # Add SPEC.md and any tests/implementations related to this feature
-    # We use explicit paths to avoid staging unrelated items
-    local paths_to_add=()
-    [[ -d "$specs_dir/$feature" ]] && paths_to_add+=("$specs_dir/$feature")
-    [[ -d "tests" ]] && paths_to_add+=("tests")
-    [[ -d "lib" ]] && paths_to_add+=("lib")
-    [[ -d "commands" ]] && paths_to_add+=("commands")
-    [[ -d "scripts" ]] && paths_to_add+=("scripts")
-    
-    if [[ ${#paths_to_add[@]} -gt 0 ]]; then
-       git add "${paths_to_add[@]}"
+    local unstaged
+    local check_paths=(tests lib commands scripts specs prompts)
+    unstaged="$(git status --porcelain -- "${check_paths[@]}" 2>/dev/null || true)"
+    if [[ -n "$unstaged" ]]; then
+      bt_err "Found unstaged files that might be required for this feature:"
+      printf '%s\n' "$unstaged" >&2
+      bt_die "Abort: ship requires all feature files to be staged. Use git add and try again."
     fi
 
     if ! git diff --cached --quiet; then
@@ -259,6 +318,12 @@ bt_cmd_pr() {
     fi
   else
     bt_info "[dry-run] gh ${pr_args[*]}"
+    local artifacts_preview
+    artifacts_preview="$(mktemp "${TMPDIR:-/tmp}/bt-pr-artifacts-preview.XXXXXX")"
+    bt_pr_write_artifacts_comment "$feature" "$specs_dir" "$artifacts_preview"
+    bt_info "[dry-run] Artifacts comment would contain:"
+    cat "$artifacts_preview"
+    rm -f "$artifacts_preview"
   fi
 
   bt_info "ship complete for $feature"

package/commands/review.sh

@@ -32,9 +32,13 @@ EOF
   codex_logf="$artifacts_dir/codex-review.log"
   : >"$codex_logf"
   local codex_ec=0
-  if ! BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_read_only "$BT_ROOT/prompts/review.md" "$out"; then
+  if BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_read_only "$BT_ROOT/prompts/review.md" "$out"; then
+    codex_ec=0
+  else
     codex_ec=$?
     bt_warn "codex exited non-zero (review): $codex_ec"
+    bt_die "codex failed (review), stopping."
+    return 1
   fi
 
   if [[ ! -f "$out" ]]; then

package/commands/spec.sh

@@ -39,24 +39,48 @@ NODE
 }
 
 bt_cmd_spec() {
-  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
-    cat <<'EOF'
+  local force=0
+  local arg=""
+  while [[ $# -gt 0 ]]; do
+    case "${1:-}" in
+      -h|--help)
+        cat <<'EOF'
 Usage:
-  bt spec <issue#>
-  bt spec <feature>
+  bt spec [--force] <issue#>
+  bt spec [--force] <feature>
+
+Options:
+  --force   Overwrite existing SPEC.md if it already exists.
 
 For an <issue#>, requires `gh` and creates `specs/issue-<n>/SPEC.md` using the issue title/body.
 For a <feature>, creates `specs/<feature>/SPEC.md` with a minimal, parseable story list.
 EOF
-    return 0
+        return 0
+        ;;
+      --force)
+        force=1
+        shift
+        ;;
+      --*)
+        bt_die "unknown option for spec: $1"
+        ;;
+      *)
+        if [[ -n "$arg" ]]; then
+          bt_die "spec accepts exactly one <issue#> or <feature>"
+        fi
+        arg="$1"
+        shift
+        ;;
+    esac
+  done
+
+  if [[ -z "$arg" ]]; then
+    bt_die "spec requires <issue#> or <feature>"
   fi
 
   bt_env_load || true
   bt_ensure_dirs
 
-  local arg="${1:-}"
-  [[ -n "$arg" ]] || bt_die "spec requires <issue#> or <feature>"
-
   local feature issue
   issue=""
   if [[ "$arg" =~ ^[0-9]+$ ]]; then
@@ -72,8 +96,12 @@ EOF
 
   local spec="$dir/SPEC.md"
   if [[ -f "$spec" ]]; then
-    bt_info "SPEC already exists: $spec"
-    return 0
+    if (( force == 1 )); then
+      bt_info "overwriting existing SPEC: $spec"
+    else
+      bt_info "SPEC already exists: $spec"
+      return 0
+    fi
   fi
 
   if [[ -n "$issue" ]]; then

package/commands/status.sh

@@ -5,14 +5,14 @@ bt__count_statuses() {
   local spec="$1"
   awk '
     BEGIN { pending=0; in_progress=0; done=0; failed=0; blocked=0; total=0 }
-    /^\- \*\*status:\*\*/ {
+    /^[[:space:]]*- \*\*status:\*\*/ {
       s=$0
-      sub(/.*\*\*status:\*\* /,"",s)
+      sub(/^[[:space:]]*- \*\*status:\*\*[[:space:]]*/,"",s)
       gsub(/[[:space:]]+/,"",s)
       total++
       if (s=="pending") pending++
       else if (s=="in_progress") in_progress++
-      else if (s=="done") done++
+      else if (s=="done" || s=="completed") done++
       else if (s=="failed") failed++
       else if (s=="blocked") blocked++
     }
@@ -33,12 +33,12 @@ bt__show_gates() {
   json="$(cat "$json_file")"
   
   local ts
-  ts=$(printf '%s' "$json" | grep -oE '"ts": "[^"]+"' | cut -d'"' -f4 || echo "unknown")
+  ts=$(printf '%s' "$json" | grep -oE '"ts"[[:space:]]*:[[:space:]]*"[^"]+"' | cut -d'"' -f4 || echo "unknown")
   
   # A simple heuristic to check if any status is non-zero
-  # We look for "status": N where N > 0
+  # We look for "status": N where N > 0 (whitespace-insensitive)
   local fails
-  fails=$(printf '%s' "$json" | grep -oE '"status": [1-9][0-9]*' | wc -l | xargs)
+  fails=$(printf '%s' "$json" | grep -oE '"status"[[:space:]]*:[[:space:]]*[1-9][0-9]*' | wc -l | xargs)
   
   local status="pass"
   [[ "$fails" -gt 0 ]] && status="fail"
@@ -52,7 +52,7 @@ bt__show_gates() {
     local k
     # This regex is a bit fragile but works for the predictable format we write
     for k in "lint" "typecheck" "test"; do
-        if echo "$json" | grep -qE "\"$k\": \{[^\}]*\"status\": [1-9][0-9]*"; then
+        if echo "$json" | grep -qE "\"$k\"[[:space:]]*:[[:space:]]*\{[^\}]*\"status\"[[:space:]]*:[[:space:]]*[1-9][0-9]*"; then
             detail="${detail}${k} "
         fi
     done

package/lib/codex.sh

@@ -19,7 +19,8 @@ bt_codex_exec_full_auto() {
   bin="$(bt_codex_bin)"
   local log_file
   log_file="${BT_CODEX_LOG_FILE:-/dev/null}"
-  "$bin" exec --full-auto -C "$BT_PROJECT_ROOT" "$(cat "$prompt_file")" > >(tee -a "$log_file") 2>&1
+  "$bin" exec --full-auto -C "$BT_PROJECT_ROOT" "$(cat "$prompt_file")" 2>&1 | tee -a "$log_file"
+  return "${PIPESTATUS[0]}"
 }
 
 bt_codex_exec_read_only() {
@@ -34,6 +35,5 @@ bt_codex_exec_read_only() {
   bin="$(bt_codex_bin)"
   local log_file
   log_file="${BT_CODEX_LOG_FILE:-/dev/null}"
-  "$bin" exec -s read-only -C "$BT_PROJECT_ROOT" -o "$out_file" "$(cat "$prompt_file")" > >(tee -a "$log_file") 2>&1
+  "$bin" exec -s read-only -C "$BT_PROJECT_ROOT" -o "$out_file" "$(cat "$prompt_file")" 2>&1 | tee -a "$log_file"
 }
-

package/lib/env.sh

@@ -68,12 +68,12 @@ bt_env_load() {
     env_file="$(bt_realpath "$env_file")"
     bt_env_load_file "$env_file" || bt_die "failed to load BT_ENV_FILE=$env_file"
   else
-    # Prefer project config from the caller's current working directory.
-    if [[ -f "$PWD/.bt.env" ]]; then
-      bt_env_load_file "$PWD/.bt.env" || bt_die "failed to load env: $PWD/.bt.env"
-    # If running with a target repo, fall back to that repo's .bt.env.
-    elif [[ -n "${BT_TARGET_DIR:-}" && -f "$BT_TARGET_DIR/.bt.env" ]]; then
+    # When targeting another repo, its env must win over caller CWD config.
+    if [[ -n "${BT_TARGET_DIR:-}" && -f "$BT_TARGET_DIR/.bt.env" ]]; then
       bt_env_load_file "$BT_TARGET_DIR/.bt.env" || bt_die "failed to load env: $BT_TARGET_DIR/.bt.env"
+    # Otherwise use caller project config.
+    elif [[ -f "$PWD/.bt.env" ]]; then
+      bt_env_load_file "$PWD/.bt.env" || bt_die "failed to load env: $PWD/.bt.env"
     fi
   fi
 

package/lib/gates.sh

@@ -33,6 +33,18 @@ bt__gate_cmd() {
   esac
 }
 
+bt__json_escape() {
+  local s="${1-}"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  s="${s//$'\t'/\\t}"
+  s="${s//$'\b'/\\b}"
+  s="${s//$'\f'/\\f}"
+  printf '%s' "$s"
+}
+
 # Returns gate config (key=cmd) for those available.
 bt_get_gate_config() {
   local detected
@@ -89,8 +101,10 @@ bt_run_gates() {
       overall_ok=1
     fi
 
-    local entry
-    printf -v entry '"%s": {"cmd": "%s", "status": %d}' "$k" "$v" "$status"
+    local entry k_json v_json
+    k_json="$(bt__json_escape "$k")"
+    v_json="$(bt__json_escape "$v")"
+    printf -v entry '"%s": {"cmd": "%s", "status": %d}' "$k_json" "$v_json" "$status"
     if [[ -z "$results_json" ]]; then
       results_json="$entry"
     else

package/lib/log.sh

@@ -43,6 +43,9 @@ bt_debug() {
 
 bt_die() {
   bt_err "$*"
+  if [[ "${BT_DIE_MODE:-exit}" == "return" ]]; then
+    return 1
+  fi
   exit 1
 }
 

package/lib/path.sh

@@ -11,11 +11,42 @@ bt_realpath() {
     python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$p" 2>/dev/null && return 0
   fi
 
-  # Best-effort fallback: not fully resolving .. or symlinks.
+  # Pure-bash lexical fallback when neither `realpath` nor `python3` is available.
+  # Resolves relative paths and normalizes "."/".." segments without requiring
+  # filesystem existence checks.
+  local abs
   case "$p" in
-    /*) printf '%s\n' "$p" ;;
-    *) printf '%s/%s\n' "$(pwd)" "$p" ;;
+    /*) abs="$p" ;;
+    *) abs="$(pwd)/$p" ;;
   esac
+
+  local IFS='/'
+  local -a parts stack
+  read -r -a parts <<< "$abs"
+
+  local seg
+  for seg in "${parts[@]}"; do
+    [[ -z "$seg" || "$seg" == "." ]] && continue
+    if [[ "$seg" == ".." ]]; then
+      if ((${#stack[@]} > 0)); then
+        unset 'stack[${#stack[@]}-1]'
+      fi
+      continue
+    fi
+    stack+=("$seg")
+  done
+
+  if ((${#stack[@]} == 0)); then
+    printf '/\n'
+    return 0
+  fi
+
+  printf '/%s' "${stack[0]}"
+  local i
+  for ((i = 1; i < ${#stack[@]}; i++)); do
+    printf '/%s' "${stack[$i]}"
+  done
+  printf '\n'
 }
 
 bt_find_up() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biotonomy",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Codex-native autonomous development loop CLI",
   "license": "MIT",
   "repository": {
@@ -31,7 +31,8 @@
     "demo": "bash scripts/demo-issue-3-real-loop.sh",
     "pr:open": "bash scripts/gh-pr.sh",
     "verify:pack": "node scripts/verify-pack.mjs",
-    "prepublishOnly": "npm test && npm run lint && npm run verify:pack"
+    "release:ready": "node scripts/release-readiness.mjs",
+    "prepublishOnly": "npm run release:ready"
   },
   "engines": {
     "node": ">=18"

package/prompts/plan-review.md

@@ -0,0 +1,6 @@
+# Plan Review Loop
+
+Review the generated SPEC.md and RESEARCH.md (if exists) for the feature.
+Ensure the plan is sound and safe.
+
+Output Verdict: APPROVED_PLAN or Verdict: NEEDS_CHANGES.

package/scripts/release-readiness.mjs

@@ -0,0 +1,78 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+function run(label, cmd, args, opts = {}) {
+  process.stderr.write(`\n==> ${label}\n`);
+  const res = spawnSync(cmd, args, {
+    encoding: "utf8",
+    stdio: opts.stdio || "inherit",
+  });
+  return {
+    ok: (res.status ?? 1) === 0,
+    status: res.status ?? 1,
+    stdout: res.stdout || "",
+    stderr: res.stderr || "",
+  };
+}
+
+function parsePackJson(stdout) {
+  try {
+    const data = JSON.parse(stdout);
+    return data?.[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+function formatBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return "n/a";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KiB`;
+  return `${(n / (1024 * 1024)).toFixed(2)} MiB`;
+}
+
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+const test = run("npm test", "npm", ["test"]);
+const lint = run("npm run lint", "npm", ["run", "lint"]);
+const verifyPack = run("npm run verify:pack", "npm", ["run", "verify:pack"]);
+
+const packDryRun = run("npm pack --dry-run --json", "npm", ["pack", "--dry-run", "--json"], {
+  stdio: "pipe",
+});
+if (packDryRun.stdout) process.stdout.write(packDryRun.stdout);
+if (packDryRun.stderr) process.stderr.write(packDryRun.stderr);
+
+const packInfo = packDryRun.ok ? parsePackJson(packDryRun.stdout) : null;
+const npmWhoami = run("npm whoami (optional)", "npm", ["whoami"], { stdio: "pipe" });
+const npmUser = npmWhoami.ok ? npmWhoami.stdout.trim() : "not authenticated";
+
+const checks = [
+  ["tests", test.ok],
+  ["lint", lint.ok],
+  ["pack contents", verifyPack.ok],
+  ["npm pack --dry-run", packDryRun.ok],
+];
+const allOk = checks.every(([, ok]) => ok);
+
+process.stderr.write("\nPublish preflight summary\n");
+process.stderr.write(`- package: ${pkg.name}@${pkg.version}\n`);
+process.stderr.write(`- npm auth: ${npmUser}\n`);
+for (const [name, ok] of checks) {
+  process.stderr.write(`- ${name}: ${ok ? "PASS" : "FAIL"}\n`);
+}
+
+if (packInfo) {
+  process.stderr.write("- pack artifact:\n");
+  process.stderr.write(`  - file: ${packInfo.filename || "n/a"}\n`);
+  process.stderr.write(`  - files: ${packInfo.files?.length ?? "n/a"}\n`);
+  process.stderr.write(`  - package size: ${formatBytes(packInfo.size)}\n`);
+  process.stderr.write(`  - unpacked size: ${formatBytes(packInfo.unpackedSize)}\n`);
+}
+
+if (!allOk) {
+  process.stderr.write("\nRelease readiness failed. Fix failures before publishing.\n");
+  process.exit(1);
+}
+
+process.stderr.write("\nRelease readiness passed. Safe to proceed with manual publish steps.\n");