biotonomy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Archive Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# 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 intentionally file-based:
+- project config lives in `.bt.env`
+- ephemeral state lives in `.bt/`
+- feature state lives in `specs/<feature>/`
+
+## The Codex Loop
+
+For a feature folder `specs/<feature>/`, the loop is:
+
+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.
+
+```bash
+# 0) Install
+npm install -g biotonomy
+
+# 1) Initialize the repo for Biotonomy (creates .bt.env, specs/, .bt/)
+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)
+
+## PR Automation (Opt-In Today)
+
+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
+```
+
+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).
+
+## Demos
+
+### Issue #3 Real Loop (End-to-End, Deterministic)
+
+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/`
+
+```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
+```
+
+## Install
+
+Global install:
+
+```bash
+npm install -g biotonomy
+bt --help
+```
+
+Local (repo) usage:
+
+```bash
+npx biotonomy --help
+```
+
+## Targeting A Repo From Anywhere
+
+By default, `bt` uses your current working directory as the project root.
+
+To run against a different repo, use `--target <path>` (sets `BT_TARGET_DIR` for that invocation):
+
+```bash
+bt --target /path/to/repo bootstrap
+bt --target /path/to/repo status
+bt --target /path/to/repo spec archie
+```
+
+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
+
+## Development
+
+```bash
+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

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/bt.sh" "$@"

package/bt.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BT_VERSION="0.1.0"
+
+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
+}
+
+BT_ROOT="$(bt_script_dir)"
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/log.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/path.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/env.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/repo.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/notify.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/codex.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/gates.sh"
+
+bt_usage() {
+  cat <<EOF
+biotonomy (bt) v$BT_VERSION
+
+Usage:
+  bt [--target <path>] <command> [args]
+
+Commands:
+  bootstrap  spec  research  implement  review  fix  compound  design  status  gates  reset  pr  ship
+
+Global options:
+  -h, --help     Show help
+  --target <p>   Operate on target project root for this invocation (sets BT_TARGET_DIR)
+  BT_ENV_FILE    Explicit path to a .bt.env (otherwise read ./.bt.env)
+  BT_TARGET_DIR  Operate on this repo dir (sets BT_PROJECT_ROOT); env falls back to \$BT_TARGET_DIR/.bt.env
+
+Examples:
+  bt bootstrap
+  bt spec 123
+  bt status
+  bt --target /path/to/repo status
+EOF
+}
+
+bt_dispatch() {
+  # Global argv parsing (kept intentionally small; this is bash, not a full CLI framework).
+  # We support:
+  # - bt --target <path> <command> ...
+  # - bt <command> ... --target <path> ...
+  # - bt --target=<path> <command> ...
+  local rest=()
+  local target_arg=""
+  while [[ $# -gt 0 ]]; do
+    case "${1:-}" in
+      --target)
+        [[ $# -ge 2 ]] || bt_die "--target requires a value"
+        target_arg="${2:-}"
+        shift 2
+        ;;
+      --target=*)
+        target_arg="${1#--target=}"
+        shift
+        ;;
+      *)
+        rest+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  if [[ -n "$target_arg" ]]; then
+    export BT_TARGET_DIR="$target_arg"
+  fi
+
+  set -- "${rest[@]}"
+
+  local cmd="${1:-help}"
+  shift || true
+
+  case "$cmd" in
+    -h|--help|help) bt_usage; return 0 ;;
+  esac
+
+  bt_env_load || true
+
+  case "$cmd" in
+    bootstrap|spec|research|implement|review|fix|compound|design|status|gates|reset|pr|ship) ;;
+    *)
+      bt_err "unknown command: $cmd"
+      bt_usage >&2
+      return 2
+      ;;
+  esac
+
+  local cmd_file="$BT_ROOT/commands/$cmd.sh"
+  if [[ "$cmd" == "ship" ]]; then
+    cmd_file="$BT_ROOT/commands/pr.sh"
+  fi
+
+  if [[ ! -f "$cmd_file" ]]; then
+    bt_die "missing command implementation: $cmd_file"
+  fi
+
+  # shellcheck source=/dev/null
+  source "$cmd_file"
+
+  local fn="bt_cmd_$cmd"
+  if [[ "$cmd" == "ship" ]]; then
+    fn="bt_cmd_pr"
+  fi
+
+  if ! declare -F "$fn" >/dev/null 2>&1; then
+    bt_die "command function not found: $fn (in $cmd_file)"
+  fi
+
+  "$fn" "$@"
+}
+
+bt_dispatch "$@"

package/commands/bootstrap.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bt_cmd_bootstrap() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt bootstrap
+
+Creates a project-local `.bt.env` and scaffolds required folders (`specs/`, `.bt/`).
+EOF
+    return 0
+  fi
+
+  # Operate within the effective project root (BT_TARGET_DIR if set).
+  local root="${BT_PROJECT_ROOT:-$PWD}"
+
+  local env_path="$root/.bt.env"
+  if [[ -f "$env_path" ]]; then
+    bt_info "found existing .bt.env"
+  else
+    cat >"$env_path" <<'EOF'
+# Biotonomy project config (loaded by bt)
+
+# Where feature state lives.
+BT_SPECS_DIR=specs
+
+# Where ephemeral state lives (locks, caches, etc).
+BT_STATE_DIR=.bt
+
+# Optional: point this at an executable script to receive notifications.
+# Example: BT_NOTIFY_HOOK=./hooks/telegram.sh
+BT_NOTIFY_HOOK=
+
+# Optional: override quality gates (commands). Empty means "auto-detect" (future).
+BT_GATE_LINT=
+BT_GATE_TYPECHECK=
+BT_GATE_TEST=
+EOF
+    bt_info "wrote $env_path"
+  fi
+
+  mkdir -p "$root/specs" "$root/.bt" "$root/hooks"
+  bt_info "ensured dirs: specs/ .bt/ hooks/"
+
+  bt_notify "bt bootstrap complete in $root"
+}

package/commands/compound.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_compound() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt compound <feature>
+
+Stubbed in v0.1.0: writes a learnings file under `learnings/`.
+EOF
+    return 0
+  fi
+
+  bt_env_load || true
+  bt_ensure_dirs
+
+  local feature
+  feature="$(bt_require_feature "${1:-}")"
+
+  mkdir -p "$BT_PROJECT_ROOT/learnings"
+  local out="$BT_PROJECT_ROOT/learnings/$feature.md"
+  cat >"$out" <<EOF
+# Learnings: $feature
+
+This is a v0.1.0 stub.
+EOF
+
+  bt_progress_append "$feature" "compound stub wrote learnings/$feature.md"
+  bt_history_write "$feature" "compound" "Wrote learnings for $feature."
+  bt_info "wrote $out"
+  bt_notify "bt compound complete for $feature"
+}
+

package/commands/design.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_design() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt design <feature>
+
+Stubbed in v0.1.0: records a design iteration marker in history/progress.
+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")"
+  mkdir -p "$dir/history"
+
+  bt_progress_append "$feature" "design stub iteration"
+  bt_history_write "$feature" "design" "Design iteration placeholder for $feature."
+  bt_info "design stub recorded for $feature"
+  bt_notify "bt design stub ran for $feature"
+}
+

package/commands/fix.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_fix() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt fix <feature>
+
+Runs Codex in full-auto using prompts/fix.md, then runs quality gates.
+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 ...)"
+
+  bt_progress_append "$feature" "fix: bt fix $feature (starting)"
+
+  local codex_ec=0
+  if bt_codex_available; then
+    bt_info "running codex (full-auto) using prompts/fix.md"
+    local artifacts_dir codex_logf
+    artifacts_dir="$dir/.artifacts"
+    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
+      codex_ec=$?
+      bt_warn "codex exited non-zero (fix): $codex_ec"
+    fi
+  else
+    codex_ec=127
+    bt_warn "codex unavailable; fix is a v0.1.0 stub"
+  fi
+
+  bt_info "running quality gates"
+  local gates_ok=1
+  if ! bt_run_gates; then
+    gates_ok=0
+    bt_progress_append "$feature" "quality gates failed"
+    bt_notify "bt fix gates FAILED for $feature"
+  fi
+
+  local h
+  h="$(bt_history_write "$feature" "fix" "$(cat <<EOF
+# Fix Run: $feature
+
+- when: $(date +'%Y-%m-%d %H:%M:%S')
+- bt_cmd: bt fix $feature
+- prompt: prompts/fix.md
+- codex_exit: $codex_ec
+- gates: $([[ "$gates_ok" == "1" ]] && echo PASS || echo FAIL)
+EOF
+)")"
+  bt_info "wrote history: $h"
+  bt_notify "bt fix complete for $feature"
+
+  [[ "$gates_ok" == "1" ]] || return 1
+}

package/commands/gates.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bt_cmd_gates() {
+  local usage="Usage: bt gates [<feature>]
+
+Runs project quality gates (lint, typecheck, test) as configured or auto-detected.
+If <feature> is provided, writes results to specs/<feature>/gates.json.
+Otherwise, writes to \$BT_PROJECT_ROOT/\$BT_STATE_DIR/state/gates.json."
+
+  local feature=""
+  if [[ $# -gt 0 ]]; then
+    case "$1" in
+      -h|--help) echo "$usage"; return 0 ;;
+      -*) bt_err "Unknown argument: $1"; echo "$usage"; return 1 ;;
+      *) feature="$(bt_require_feature "$1")" ;;
+    esac
+  fi
+
+  local json_out
+  local exit_code=0
+  
+  # bt_run_gates outputs the JSON to stdout, and exits with non-zero if any gate failed.
+  if ! json_out="$(bt_run_gates)"; then
+    exit_code=1
+  fi
+
+  local out_dir
+  if [[ -n "$feature" ]]; then
+    out_dir="$(bt_feature_dir "$feature")"
+  else
+    out_dir="$BT_PROJECT_ROOT/$BT_STATE_DIR/state"
+  fi
+
+  mkdir -p "$out_dir"
+  printf '%s\n' "$json_out" > "$out_dir/gates.json"
+  bt_info "Gate results saved to $out_dir/gates.json"
+
+  return "$exit_code"
+}

package/commands/implement.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# shellcheck source=/dev/null
+source "$BT_ROOT/lib/state.sh"
+
+bt_cmd_implement() {
+  if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+    cat <<'EOF'
+Usage:
+  bt implement <feature>
+
+Runs Codex in full-auto using prompts/implement.md, then runs quality gates.
+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 ...)"
+
+  bt_progress_append "$feature" "implement: bt implement $feature (starting)"
+
+  local codex_ec=0
+  if bt_codex_available; then
+    bt_info "running codex (full-auto) using prompts/implement.md"
+    local artifacts_dir codex_logf
+    artifacts_dir="$dir/.artifacts"
+    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
+      codex_ec=$?
+      bt_warn "codex exited non-zero (implement): $codex_ec"
+    fi
+  else
+    codex_ec=127
+    bt_warn "codex unavailable; implement is a v0.1.0 stub"
+  fi
+
+  bt_info "running quality gates"
+  local gates_ok=1
+  if ! bt_run_gates; then
+    gates_ok=0
+    bt_progress_append "$feature" "quality gates failed"
+    bt_notify "bt implement gates FAILED for $feature"
+  fi
+
+  local h
+  h="$(bt_history_write "$feature" "implement" "$(cat <<EOF
+# Implement Run: $feature
+
+- when: $(date +'%Y-%m-%d %H:%M:%S')
+- bt_cmd: bt implement $feature
+- prompt: prompts/implement.md
+- codex_exit: $codex_ec
+- gates: $([[ "$gates_ok" == "1" ]] && echo PASS || echo FAIL)
+EOF
+)")"
+  bt_info "wrote history: $h"
+  bt_notify "bt implement complete for $feature"
+
+  [[ "$gates_ok" == "1" ]] || return 1
+}