biotonomy 0.2.1 → 0.2.3

package/README.md

@@ -1,211 +1,98 @@
 # Biotonomy
 
-Biotonomy is a command-line workflow for shipping code changes with Codex.
+Biotonomy (`bt`) is a CLI for running a Codex-driven development workflow in a repo:
 
-- 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.
+`spec -> research -> plan-review -> implement -> review -> fix -> pr`
 
-## 60-Second Quickstart
+It supports both:
+- manual stage-by-stage execution
+- a one-command iterative loop with `bt loop`
 
-Install either way:
+## Quickstart
 
-```bash
-npm i -g biotonomy
-# then use: bt ...
-```
-
-```bash
-npx biotonomy ...
-```
-
-Minimal demo in a fresh repo:
-
-```bash
-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
-```
-
-Expected files after the demo:
-
-- `.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`
-
-Notes:
-
-- `review` still creates `REVIEW.md` even if Codex is not installed.
-- `research` requires Codex.
-
-## Ship A Small Change
-
-Use this for a real change from idea to PR.
-
-1. `spec` (define the change)
-
-```bash
-bt spec my-change
-# or from GitHub issue:
-# bt spec 123
-```
-
-- Automated today: creates `specs/<feature>/SPEC.md`, history, and progress logs.
-- Manual today: fill in/clean up stories and acceptance criteria in `SPEC.md`.
-
-2. `research` (gather context)
+Prereqs: Node.js >= 18, `git`, Codex CLI available as `codex` (or set `BT_CODEX_BIN`).
 
 ```bash
-bt research my-change
-```
-
-- Automated today: runs Codex in read-only mode and writes `RESEARCH.md`.
-- Manual today: confirm research quality and adjust plan if needed.
-
-3. `implement` (make the change)
-
-```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.
-
-4. `review` (check what changed)
-
-```bash
-bt review my-change
-```
-
-- Automated today: writes `REVIEW.md` (with a fallback stub if Codex fails).
-- Manual today: decide whether findings are acceptable for your team.
-
-5. `fix` (address findings)
-
-```bash
-bt fix my-change
-```
-
-- 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
-```
-
-- 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.
-
-## Current Limitations
-
-- 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
-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`.
-
-Quality gate failures on `implement`/`fix`:
-
-```bash
-bt gates my-change
-```
-
-- 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.
-
-```bash
-git checkout main
-git pull --ff-only
-```
+# Install
+npm i -g biotonomy
 
-2. Run release preflight checks (tests, lint, pack verification, and `npm pack --dry-run` summary).
+# In your project repo
+bt bootstrap
 
-```bash
-npm run release:ready
-```
+# Create a feature scaffold
+FEATURE=hello-world
+bt spec "$FEATURE"
 
-3. Ensure npm authentication is ready for publish.
+# Loop requires an approved plan review verdict first
+cat > "specs/$FEATURE/PLAN_REVIEW.md" <<'MD'
+Verdict: APPROVED_PLAN
+MD
 
-```bash
-npm whoami
-# if needed:
-npm login
+# Run autonomous implement/review/fix iterations (with gates)
+bt loop "$FEATURE" --max-iterations 3
 ```
 
-4. Bump version and create a tag.
+## `bt loop`
 
-```bash
-npm version patch
-# or: npm version minor / npm version major
-```
+`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
 
-5. Push commit and tag.
+Loop hard-requires an approved `specs/<feature>/PLAN_REVIEW.md` verdict (`APPROVE_PLAN` or `APPROVED_PLAN`).
 
-```bash
-git push --follow-tags
-```
+## Artifacts And State
 
-6. Publish manually.
+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>`
 
-```bash
-npm publish --access public
-```
-
-- If your npm account uses 2FA for publish, npm will require a one-time code during `npm publish`.
+Global gate state is written to `.bt/state/gates.json` when running `bt gates` without a feature.
 
-## Commands
+## Manual Commands
 
 ```bash
 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> [--dry-run|--run]
-bt reset
+bt pr <feature> [--run]
+```
+
+## Configuration
+
+Project config lives in `.bt.env` (created by `bt bootstrap`). Common overrides:
+
+```bash
+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"
 ```
 
-## Development
+## Release
+
+Run the release readiness checks:
 
 ```bash
-npm test
-npm run lint
+npm run release:ready
 ```
+
+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/commands/loop.sh

@@ -59,15 +59,6 @@ bt_cmd_loop() {
   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"
@@ -77,6 +68,27 @@ bt_cmd_loop() {
     bt_die "loop hard-fails without approved PLAN_REVIEW verdict before implement/review"
   fi
 
+  bt_info "starting loop for: $feature (max iterations: $max_iter)"
+
+  local -a gate_args=()
+  if [[ "${BT_LOOP_REQUIRE_GATES:-0}" == "1" ]]; then
+    gate_args=(--require-any)
+  fi
+
+  bt_info "running preflight gates..."
+  if (( ${#gate_args[@]} > 0 )); then
+    if ! bt_run_gates "${gate_args[@]}"; then
+      bt_err "preflight gates failed (or none configured); aborting before implement/review"
+      return 1
+    fi
+  else
+    if ! bt_run_gates; then
+      bt_err "preflight gates failed (or none configured); aborting before implement/review"
+      return 1
+    fi
+  fi
+  bt_info "preflight gates: PASS"
+
   # Source required commands so we can call them directly
   # shellcheck source=/dev/null
   source "$BT_ROOT/commands/implement.sh"
@@ -165,11 +177,20 @@ PY
     # 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"
+    if (( ${#gate_args[@]} > 0 )); then
+      if ! bt_run_gates "${gate_args[@]}"; then
+        gates_ok=0
+        bt_info "gates: FAIL"
+      else
+        bt_info "gates: PASS"
+      fi
     else
-      bt_info "gates: PASS"
+      if ! bt_run_gates; then
+        gates_ok=0
+        bt_info "gates: FAIL"
+      else
+        bt_info "gates: PASS"
+      fi
     fi
 
     local fix_status="SKIP"

package/commands/plan-review.sh

@@ -31,7 +31,12 @@ EOF
 
   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
+    local artifacts_dir codex_logf
+    artifacts_dir="$dir/.artifacts"
+    mkdir -p "$artifacts_dir"
+    codex_logf="$artifacts_dir/codex-plan-review.log"
+    : >"$codex_logf"
+    if BT_FEATURE="$feature" BT_CODEX_LOG_FILE="$codex_logf" bt_codex_exec_full_auto "$BT_ROOT/prompts/plan-review.md"; then
       :
     else
       bt_die "codex failed (plan-review)"

package/commands/pr.sh

@@ -189,20 +189,19 @@ bt_cmd_pr() {
   fi
 
   # 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
+  # P0 #18: fail-loud even with --no-commit
+  local unstaged=""
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    # Protect all repo files, not only a fixed allowlist of directories.
+    unstaged="$(git ls-files --others --modified --exclude-standard 2>/dev/null || true)"
+  else
+    # Outside a git repo, treat present files (except .git internals) as unstaged by definition.
+    unstaged="$(find . -path './.git' -prune -o -type f -print 2>/dev/null | sed 's#^\./##' | 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
 
   if [[ "$run_mode" == "dry-run" ]]; then
@@ -255,14 +254,7 @@ bt_cmd_pr() {
   # 4. Commit changes if requested
   if [[ "$commit" == "1" ]]; then
     bt_info "committing changes..."
-    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
+    # (Unstaged check removed here as it is now redundant with global T0 check)
 
     if ! git diff --cached --quiet; then
       git commit -m "feat($feature): ship implementation"

package/commands/spec.sh

@@ -38,6 +38,84 @@ NODE
   )"
 }
 
+bt__stories_from_issue_json() {
+  bt__require_cmd node
+  node -e "$(
+    cat <<'NODE'
+const fs = require("fs");
+const j = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
+
+function clean(s) {
+  return String(s || "").replace(/\s+/g, " ").trim();
+}
+
+const title = clean(j.title);
+const body = String(j.body || "").replace(/\r/g, "");
+const lines = body.split("\n");
+
+let inAcceptance = false;
+const acceptanceBullets = [];
+const allBullets = [];
+for (const rawLine of lines) {
+  const line = rawLine || "";
+  if (/^\s*#{1,6}\s*acceptance\b/i.test(line) || /^\s*acceptance criteria\s*:?\s*$/i.test(line)) {
+    inAcceptance = true;
+    continue;
+  }
+  if (/^\s*#{1,6}\s+/.test(line) && inAcceptance) {
+    inAcceptance = false;
+  }
+
+  const m = line.match(/^\s*[-*]\s+(?:\[[ xX]\]\s*)?(.+?)\s*$/);
+  if (!m) {
+    continue;
+  }
+  const bullet = clean(m[1]);
+  if (!bullet) {
+    continue;
+  }
+  allBullets.push(bullet);
+  if (inAcceptance) {
+    acceptanceBullets.push(bullet);
+  }
+}
+
+const selectedBullets = acceptanceBullets.length > 0 ? acceptanceBullets : allBullets;
+const storyTitles = [];
+if (title) {
+  storyTitles.push(title);
+}
+for (const bullet of selectedBullets) {
+  if (storyTitles.length >= 5) {
+    break;
+  }
+  storyTitles.push(bullet);
+}
+
+if (storyTitles.length === 0) {
+  const fallback = clean(body).slice(0, 120);
+  if (fallback) {
+    storyTitles.push(fallback);
+  } else {
+    storyTitles.push("Capture issue requirements");
+  }
+}
+
+let out = "";
+for (let i = 0; i < storyTitles.length; i += 1) {
+  const id = i + 1;
+  const titleText = storyTitles[i];
+  out += "## [ID:S" + id + "] " + titleText + "\n";
+  out += "- **status:** draft\n";
+  out += "- **priority:** " + (id <= 3 ? 1 : 2) + "\n";
+  out += "- **acceptance:** " + titleText + "\n";
+  out += "- **tests:**\n\n";
+}
+process.stdout.write(out);
+NODE
+  )"
+}
+
 bt_cmd_spec() {
   local force=0
   local arg=""
@@ -132,8 +210,9 @@ EOF
     [[ -n "$title" ]] || title="(untitled)"
     [[ -n "$url" ]] || url="https://github.com/$repo/issues/$issue"
 
-    local summary
+    local summary stories
     summary="$(bt__summarize_body "$body")"
+    stories="$(printf '%s' "$json" | bt__stories_from_issue_json)"
 
     cat >"$spec" <<EOF
 ---
@@ -154,35 +233,7 @@ $summary
 
 # Stories
 
-## [ID:S1] Confirm repo resolution and env fallback
-- **status:** draft
-- **priority:** 1
-- **acceptance:** bt can determine repo slug from git remote origin; otherwise requires BT_REPO
-- **tests:**
-
-## [ID:S2] Fetch issue details via gh
-- **status:** draft
-- **priority:** 1
-- **acceptance:** bt spec <issue#> uses gh to retrieve title/body/url and handles errors clearly
-- **tests:**
-
-## [ID:S3] Generate a SPEC.md with frontmatter + problem summary
-- **status:** draft
-- **priority:** 1
-- **acceptance:** SPEC includes required frontmatter, a Problem section, and a Stories section (3-7 stories)
-- **tests:**
-
-## [ID:S4] Record exact gh commands used in SPEC footer
-- **status:** draft
-- **priority:** 2
-- **acceptance:** SPEC footer includes the exact gh command(s) executed
-- **tests:**
-
-## [ID:S5] Add tests stubbing gh via PATH
-- **status:** draft
-- **priority:** 1
-- **acceptance:** tests run offline and validate SPEC content generation
-- **tests:**
+${stories}
 
 ---
 

package/lib/gates.sh

@@ -77,6 +77,12 @@ bt_get_gate_config() {
 # Runs gates and returns a JSON string fragment with results.
 # Writes logs to stderr. Returns 0 if all gates passed, 1 otherwise.
 bt_run_gates() {
+  local require_any=0
+  if [[ "${1:-}" == "--require-any" ]]; then
+    require_any=1
+    shift
+  fi
+
   local config
   config="$(bt_get_gate_config)"
 
@@ -115,6 +121,9 @@ bt_run_gates() {
   if [[ "$any" == "0" ]]; then
     bt_warn "no gates ran"
     printf '{"ts": "%s", "results": {}}\n' "$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
+    if [[ "$require_any" == "1" ]]; then
+      return 1
+    fi
     return 0
   fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biotonomy",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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",