biotonomy 0.1.0 → 0.2.2

package/README.md

@@ -1,186 +1,98 @@
 # 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 (`bt`) is a CLI for running a Codex-driven development workflow in a repo:
 
-Biotonomy is intentionally file-based:
-- project config lives in `.bt.env`
-- ephemeral state lives in `.bt/`
-- feature state lives in `specs/<feature>/`
+`spec -> research -> plan-review -> implement -> review -> fix -> pr`
 
-## The Codex Loop
+It supports both:
+- manual stage-by-stage execution
+- a one-command iterative loop with `bt loop`
 
-For a feature folder `specs/<feature>/`, the loop is:
+## Quickstart
 
-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)
-
-## Ship Archie (Walkthrough)
-
-This is the intended "ship a feature" path. Some steps are still manual; each TODO points at the tracking issue.
+Prereqs: Node.js >= 18, `git`, Codex CLI available as `codex` (or set `BT_CODEX_BIN`).
 
 ```bash
-# 0) Install
-npm install -g biotonomy
+# Install
+npm i -g biotonomy
 
-# 1) Initialize the repo for Biotonomy (creates .bt.env, specs/, .bt/)
+# In your project repo
 bt bootstrap
 
-# 2) Create a spec (local feature name)
-bt spec archie
-
-# (Optional) If "Archie" is a GitHub issue:
-# bt spec 123   # pulls issue title/body via `gh` into specs/issue-123/SPEC.md
-
-# 3) Research (requires Codex; see Issue #3 for the end-to-end loop/demo harness)
-bt research archie
-
-# 4) Implement (runs gates; if Codex is unavailable this records history and still runs gates)
-bt implement archie
-
-# 5) Review (writes specs/archie/REVIEW.md; stub output if Codex is unavailable)
-bt review archie
-
-# 6) Fix until review is clean (gates are re-run)
-bt fix archie
-
-# 7) Check progress at any time
-bt status
-```
-
-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)
-
-## Artifacts And Layout
-
-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
-
-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
-
-## Quality Gates
-
-Stages that run gates:
-- `bt implement <feature>`
-- `bt fix <feature>`
-- `bt gates [<feature>]`
-
-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)
+# Create a feature scaffold
+FEATURE=hello-world
+bt spec "$FEATURE"
 
-## PR Automation (Opt-In Today)
+# Loop requires an approved plan review verdict first
+cat > "specs/$FEATURE/PLAN_REVIEW.md" <<'MD'
+Verdict: APPROVED_PLAN
+MD
 
-There is currently a safe helper script (defaults to `--dry-run`) that uses `git` and `gh`:
-
-```bash
-npm run pr:open -- archie --dry-run
-npm run pr:open -- archie --run
+# Run autonomous implement/review/fix iterations (with gates)
+bt loop "$FEATURE" --max-iterations 3
 ```
 
-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).
+## `bt loop`
 
-## Demos
+`bt loop <feature> [--max-iterations N]` runs:
+1. preflight quality gates
+2. `implement`
+3. `review`
+4. `fix` only when review verdict is `NEEDS_CHANGES`
+5. repeat until verdict is `APPROVE`/`APPROVED` and gates pass, or max iterations is reached
 
-### Issue #3 Real Loop (End-to-End, Deterministic)
+Loop hard-requires an approved `specs/<feature>/PLAN_REVIEW.md` verdict (`APPROVE_PLAN` or `APPROVED_PLAN`).
 
-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/`
+## Artifacts And State
 
-```bash
-npm install
-npm run demo
-
-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
-```
+Biotonomy writes feature state under `specs/<feature>/`:
+- `SPEC.md`
+- `RESEARCH.md`
+- `PLAN_REVIEW.md`
+- `REVIEW.md`
+- `history/` stage snapshots (`###-<stage>.md`) and loop iteration snapshots (`*-loop-iter-###.md`)
+- `loop-progress.json` loop summary and per-iteration status
+- `progress.txt` append-only stage log
+- `.artifacts/` Codex logs and command artifacts (for example `codex-implement.log`, `codex-review.log`, `codex-fix.log`)
+- `gates.json` feature gate results when running `bt gates <feature>`
 
-## Install
-
-Global install:
-
-```bash
-npm install -g biotonomy
-bt --help
-```
+Global gate state is written to `.bt/state/gates.json` when running `bt gates` without a feature.
 
-Local (repo) usage:
+## Manual Commands
 
 ```bash
-npx biotonomy --help
+bt bootstrap
+bt spec <feature|issue#>
+bt research <feature>
+bt plan-review <feature>
+bt implement <feature>
+bt review <feature>
+bt fix <feature>
+bt loop <feature> [--max-iterations N]
+bt gates [feature]
+bt status
+bt pr <feature> [--run]
 ```
 
-## Targeting A Repo From Anywhere
-
-By default, `bt` uses your current working directory as the project root.
+## Configuration
 
-To run against a different repo, use `--target <path>` (sets `BT_TARGET_DIR` for that invocation):
+Project config lives in `.bt.env` (created by `bt bootstrap`). Common overrides:
 
 ```bash
-bt --target /path/to/repo bootstrap
-bt --target /path/to/repo status
-bt --target /path/to/repo spec archie
+BT_SPECS_DIR=specs
+BT_STATE_DIR=.bt
+BT_GATE_LINT="npm run lint"
+BT_GATE_TYPECHECK="tsc --noEmit"
+BT_GATE_TEST="npm test"
+BT_CODEX_BIN="/path/to/codex"
 ```
 
-You can also set `BT_TARGET_DIR` in the environment (same behavior):
-
-```bash
-BT_TARGET_DIR=/path/to/repo bt status
-```
-
-## Status (v0.1.0)
-
-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
-
-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
+## Release
 
-## Development
+Run the release readiness checks:
 
 ```bash
-npm test
-npm run lint
+npm run release:ready
 ```
 
-Lint uses `shellcheck` if it is installed; otherwise it skips with a warning (CI installs shellcheck and runs strict).
+That script runs tests, lint, pack verification, and `npm pack --dry-run`.

package/bt

@@ -1,5 +1,16 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+bt_script_dir() {
+  local src="${BASH_SOURCE[0]}"
+  while [ -h "$src" ]; do
+    local dir
+    dir="$(cd -P "$(dirname "$src")" && pwd)"
+    src="$(readlink "$src")"
+    [[ "$src" != /* ]] && src="$dir/$src"
+  done
+  cd -P "$(dirname "$src")" && pwd
+}
+
+SCRIPT_DIR="$(bt_script_dir)"
 exec "$SCRIPT_DIR/bt.sh" "$@"

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.2",
   "description": "Codex-native autonomous development loop CLI",
   "license": "MIT",
   "repository": {
@@ -12,7 +12,8 @@
   },
   "homepage": "https://github.com/archive-dot-com/biotonomy#readme",
   "bin": {
-    "bt": "bt"
+    "bt": "bt",
+    "biotonomy": "bt"
   },
   "files": [
     "bt",
@@ -31,7 +32,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");