biotonomy 0.1.0

package/prompts/implement.md

@@ -0,0 +1,19 @@
+# Implement (Biotonomy v0.1.0)
+
+You are the implementation agent.
+
+Rules:
+- Prefer small, surgical commits.
+- Add/adjust tests first.
+- Run the project's quality gates.
+- Update `specs/<feature>/SPEC.md` story status as you make progress.
+
+Inputs:
+- `specs/<feature>/SPEC.md`
+- `specs/<feature>/RESEARCH.md` (if present)
+- `specs/<feature>/progress.txt`
+
+Outputs:
+- Modified source + tests
+- Updated `SPEC.md`
+

package/prompts/research.md

@@ -0,0 +1,12 @@
+# Research (Biotonomy v0.1.0)
+
+You are the research agent. Learn the codebase quickly and record actionable guidance.
+
+Write to:
+- `specs/<feature>/RESEARCH.md`
+
+Capture:
+- How to run tests, lint, typecheck
+- Key architectural patterns and conventions
+- Risky areas and common pitfalls
+

package/prompts/review.md

@@ -0,0 +1,15 @@
+# Review (Biotonomy v0.1.0)
+
+You are the reviewer agent. You must not implement features; only identify issues.
+
+Checklist:
+- Correctness and edge cases
+- Tests: coverage and brittleness
+- Security and safety
+- Style and maintainability
+
+Output:
+- Write `specs/<feature>/REVIEW.md` with:
+  - `Verdict: APPROVE` or `Verdict: NEEDS_CHANGES`
+  - A numbered list of findings with file paths and suggested fixes
+

package/scripts/demo-issue-3-real-loop.sh

@@ -0,0 +1,221 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# End-to-end "real loop" demo for Issue #3.
+# Runs the actual entrypoint (bt.sh) against a deterministic workspace and
+# writes scrubbed (timestamp/path-normalized) outputs under specs/issue-3-real-loop/.
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+ROOT="$PWD"
+BT="$ROOT/bt.sh"
+
+BASE="$ROOT/specs/issue-3-real-loop"
+WORK="$BASE/workspace"
+BIN="$WORK/bin"
+
+iters="${BT_DEMO_ITERS:-3}"
+if [[ $# -gt 0 ]]; then
+  case "${1:-}" in
+    -h|--help)
+      cat <<EOF
+Usage:
+  npm run demo -- [iterations]
+
+Writes deterministic demo outputs under:
+  specs/issue-3-real-loop/
+
+You can also set:
+  BT_DEMO_ITERS=5
+EOF
+      exit 0
+      ;;
+    *[!0-9]*)
+      echo "demo: iterations must be a number (got: $1)" >&2
+      exit 2
+      ;;
+    *)
+      iters="$1"
+      ;;
+  esac
+fi
+
+demo_sed_inplace() {
+  local expr="$1"
+  local file="$2"
+  if sed --version >/dev/null 2>&1; then
+    sed -i -E "$expr" "$file"
+  else
+    sed -i '' -E "$expr" "$file"
+  fi
+}
+
+run_bt() {
+  local -a args=("$@")
+  # bt logs to stderr; capture both, and normalize ANSI coloring.
+  (
+    export BT_NO_COLOR=1
+    export LC_ALL=C
+    export LANG=C
+    export PATH="$BIN:$PATH"
+    cd "$WORK"
+    bash "$BT" "${args[@]}"
+  ) 2>&1
+}
+
+write_stub_gh() {
+  cat >"$BIN/gh" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "${1:-}" == "issue" && "${2:-}" == "view" && "${3:-}" == "3" ]]; then
+  cat <<'JSON'
+{"title":"Core loop (Codex + gh integration)","url":"https://github.com/archive-dot-com/biotonomy/issues/3","body":"Issue #3 demo body.\n\nThis is deterministic stub data."}
+JSON
+  exit 0
+fi
+echo "stub gh: unexpected args: $*" >&2
+exit 2
+EOF
+  chmod 755 "$BIN/gh"
+}
+
+write_stub_codex() {
+  cat >"$BIN/codex" <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "${1:-}" != "exec" ]]; then
+  echo "stub codex: expected 'exec' (got: ${1:-})" >&2
+  exit 2
+fi
+shift
+
+out=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -o) shift; out="${1:-}"; shift ;;
+    *) shift ;;
+  esac
+done
+
+# Read-only path writes an output file; full-auto path just exits 0.
+if [[ -n "$out" ]]; then
+  mkdir -p "$(dirname "$out")"
+  # Keep output stable across runs (no timestamps).
+  cat >"$out" <<'MD'
+# Codex Stub Output
+
+Verdict: OK
+
+This is deterministic stub output for the Issue #3 real-loop demo.
+MD
+fi
+exit 0
+EOF
+  chmod 755 "$BIN/codex"
+}
+
+scrub_workspace_nondeterminism() {
+  # Normalize timestamps in files that intentionally include them.
+  local f
+  if [[ -f "$WORK/.bt/state/gates.json" ]]; then
+    demo_sed_inplace 's/"ts":[[:space:]]*"[^"]+"/"ts": "1970-01-01T00:00:00Z"/' "$WORK/.bt/state/gates.json"
+  fi
+  if [[ -d "$WORK/specs/issue-3" ]]; then
+    if [[ -f "$WORK/specs/issue-3/gates.json" ]]; then
+      demo_sed_inplace 's/"ts":[[:space:]]*"[^"]+"/"ts": "1970-01-01T00:00:00Z"/' "$WORK/specs/issue-3/gates.json"
+    fi
+    if [[ -f "$WORK/specs/issue-3/progress.txt" ]]; then
+      demo_sed_inplace 's/^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}/1970-01-01 00:00:00/' "$WORK/specs/issue-3/progress.txt"
+    fi
+    if [[ -d "$WORK/specs/issue-3/history" ]]; then
+      for f in "$WORK/specs/issue-3/history/"*.md; do
+        [[ -f "$f" ]] || continue
+        demo_sed_inplace 's/^- when: [0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}/- when: 1970-01-01 00:00:00/' "$f"
+      done
+    fi
+  fi
+}
+
+mkdir -p "$BASE"
+rm -rf "$WORK"
+mkdir -p "$WORK" "$BIN"
+
+# Minimal project scaffolding for deterministic repo resolution and gate behavior.
+cat >"$WORK/.bt.env" <<'EOF'
+BT_SPECS_DIR=specs
+BT_STATE_DIR=.bt
+
+# Make gates deterministic and fast.
+BT_GATE_LINT=true
+BT_GATE_TYPECHECK=true
+BT_GATE_TEST=true
+
+# Use the stubbed codex in workspace bin/.
+BT_CODEX_BIN=codex
+EOF
+
+write_stub_gh
+write_stub_codex
+
+(
+  cd "$WORK"
+  git init -q
+  git remote add origin https://github.com/archive-dot-com/biotonomy.git
+) >/dev/null 2>&1 || true
+
+raw="$BASE/transcript.raw.txt"
+out="$BASE/transcript.txt"
+snap="$BASE/snapshot.txt"
+
+: >"$raw"
+
+{
+  echo "biotonomy issue-3 real-loop demo"
+  echo "iterations=$iters"
+  echo
+
+  run_bt bootstrap
+  run_bt spec 3
+
+  i=1
+  while [[ "$i" -le "$iters" ]]; do
+    echo "== iteration $i =="
+    run_bt research issue-3
+    run_bt implement issue-3 || true
+    run_bt review issue-3
+    run_bt gates issue-3 || true
+    run_bt status
+    echo
+    i=$((i + 1))
+  done
+} >>"$raw"
+
+scrub_workspace_nondeterminism
+
+# Create a scrubbed transcript: normalize bt timestamps and any absolute paths.
+cp "$raw" "$out"
+demo_sed_inplace 's/^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}/1970-01-01 00:00:00/' "$out"
+demo_sed_inplace "s#${WORK}#<WORK>#g" "$out"
+demo_sed_inplace "s#${ROOT}#<REPO>#g" "$out"
+
+# Snapshot key outputs (tree + a couple of file excerpts).
+{
+  echo "workspace: <WORK>"
+  echo
+  echo "files:"
+  (cd "$WORK" && find . -type f -not -path "./.git/*" | LC_ALL=C sort)
+  echo
+  echo "SPEC.md (head):"
+  sed -n '1,40p' "$WORK/specs/issue-3/SPEC.md"
+  echo
+  echo "RESEARCH.md (head):"
+  sed -n '1,40p' "$WORK/specs/issue-3/RESEARCH.md"
+  echo
+  echo "REVIEW.md (head):"
+  sed -n '1,40p' "$WORK/specs/issue-3/REVIEW.md"
+} >"$snap"
+
+demo_sed_inplace "s#${WORK}#<WORK>#g" "$snap"
+
+echo "demo: wrote $out" >&2
+echo "demo: wrote $snap" >&2

package/scripts/gh-pr.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Safe, opt-in PR helper using gh.
+# Defaults to dry-run (prints commands). Pass --run to execute.
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  npm run pr:open -- <feature> [--run] [--dry-run] [--base <branch>] [--remote <name>] [--draft]
+
+Notes:
+  - Default mode is --dry-run (no git/gh side effects).
+  - Determines branch from specs/<feature>/SPEC.md frontmatter (branch: ...), else uses feat/<feature>.
+EOF
+}
+
+run_mode="dry-run"
+base=""
+remote="origin"
+draft=0
+feature=""
+
+while [[ $# -gt 0 ]]; do
+  case "${1:-}" in
+    -h|--help) usage; exit 0 ;;
+    --run) run_mode="run"; shift ;;
+    --dry-run) run_mode="dry-run"; shift ;;
+    --base) base="${2:-}"; shift 2 ;;
+    --remote) remote="${2:-}"; shift 2 ;;
+    --draft) draft=1; shift ;;
+    -*)
+      echo "pr: unknown flag: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+    *)
+      feature="$1"
+      shift
+      ;;
+  esac
+done
+
+[[ -n "$feature" ]] || { usage >&2; exit 2; }
+
+run_cmd() {
+  printf '+ '
+  printf '%q ' "$@"
+  printf '\n'
+  if [[ "$run_mode" == "run" ]]; then
+    "$@"
+  fi
+}
+
+if ! command -v git >/dev/null 2>&1; then
+  echo "pr: git not found" >&2
+  exit 127
+fi
+
+if [[ "$run_mode" == "run" ]] && ! command -v gh >/dev/null 2>&1; then
+  echo "pr: gh not found (install GitHub CLI or re-run with --dry-run)" >&2
+  exit 127
+fi
+
+specs_dir="${BT_SPECS_DIR:-specs}"
+spec="$specs_dir/$feature/SPEC.md"
+
+branch="feat/$feature"
+repo=""
+issue=""
+
+if [[ -f "$spec" ]]; then
+  # Read simple YAML-ish frontmatter keys (one per line).
+  b="$(awk -F': *' '$1=="branch"{print $2; exit}' "$spec" | tr -d '\r')"
+  r="$(awk -F': *' '$1=="repo"{print $2; exit}' "$spec" | tr -d '\r')"
+  i="$(awk -F': *' '$1=="issue"{print $2; exit}' "$spec" | tr -d '\r')"
+  [[ -n "${b:-}" ]] && branch="$b"
+  [[ -n "${r:-}" ]] && repo="$r"
+  [[ -n "${i:-}" ]] && issue="$i"
+fi
+
+if [[ -z "$base" ]]; then
+  # Try to detect the default remote HEAD (origin/main vs origin/master, etc.).
+  ref="$(git symbolic-ref -q "refs/remotes/$remote/HEAD" 2>/dev/null || true)"
+  if [[ -n "$ref" ]]; then
+    base="${ref##*/}"
+  else
+    base="main"
+  fi
+fi
+
+title="feat: $feature"
+body="Feature: $feature"
+if [[ -n "$repo" && -n "$issue" ]]; then
+  body="$body
+Issue: https://github.com/$repo/issues/$issue"
+fi
+if [[ -f "$spec" ]]; then
+  body="$body
+Spec: $spec"
+fi
+
+if git show-ref --verify --quiet "refs/heads/$branch"; then
+  run_cmd git checkout "$branch"
+else
+  run_cmd git checkout -b "$branch"
+fi
+
+run_cmd git push -u "$remote" "$branch"
+
+pr_args=(pr create --head "$branch" --base "$base" --title "$title" --body "$body")
+if [[ "$draft" == "1" ]]; then
+  pr_args+=(--draft)
+fi
+run_cmd gh "${pr_args[@]}"
+

package/scripts/lint-shell.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Deterministic output ordering regardless of runner locale.
+export LC_ALL=C
+export LANG=C
+
+if ! command -v shellcheck >/dev/null 2>&1; then
+  if [[ "${BT_LINT_STRICT:-0}" == "1" ]]; then
+    echo "lint: shellcheck not found (BT_LINT_STRICT=1); failing" >&2
+    exit 1
+  fi
+  echo "lint: shellcheck not found; skipping (install shellcheck to enable)" >&2
+  exit 0
+fi
+
+files=()
+
+# Prefer tracked files when running from a git worktree. This avoids glob ordering
+# differences and silently skipping new folders.
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  while IFS= read -r f; do
+    files+=("$f")
+  done < <(git ls-files -- '*.sh' | sort)
+else
+  # npm-installed tarballs don't include `.git/`, so fall back to globs.
+  shopt -s nullglob
+  files+=(bt.sh commands/*.sh lib/*.sh hooks/*.sh scripts/*.sh)
+  shopt -u nullglob
+  # Normalize ordering.
+  mapfile -t files < <(printf '%s\n' "${files[@]}" | sort)
+fi
+
+if [[ ${#files[@]} -eq 0 ]]; then
+  echo "lint: no shell files found; skipping" >&2
+  exit 0
+fi
+
+shellcheck -x "${files[@]}"

package/scripts/verify-pack.mjs

@@ -0,0 +1,54 @@
+import { spawnSync } from "node:child_process";
+import assert from "node:assert/strict";
+
+function sh(cmd, args) {
+  const res = spawnSync(cmd, args, { encoding: "utf8" });
+  if ((res.status ?? 1) !== 0) {
+    throw new Error(
+      `command failed: ${cmd} ${args.join(" ")}\n${res.stdout || ""}\n${res.stderr || ""}`
+    );
+  }
+  return { stdout: res.stdout || "", stderr: res.stderr || "" };
+}
+
+// Prefer JSON output when available (npm >=9 supports --json for pack).
+let files = null;
+try {
+  const { stdout } = sh("npm", ["pack", "--dry-run", "--json"]);
+  const j = JSON.parse(stdout);
+  // npm returns an array; each entry has "files": [{path,size,mode}, ...]
+  files = (j?.[0]?.files || []).map((f) => f.path).filter(Boolean);
+} catch {
+  // Fallback: parse the human output (less stable, but better than nothing).
+  const { stdout } = sh("npm", ["pack", "--dry-run"]);
+  files = stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.startsWith("npm notice "))
+    .map((l) => l.replace(/^npm notice\s+/, ""))
+    .filter((l) => l.startsWith("package.json") || l.startsWith("bt.sh") || l.includes("/"));
+}
+
+assert.ok(Array.isArray(files) && files.length > 0, "npm pack produced no file list");
+
+const mustHave = [
+  "package.json",
+  "README.md",
+  "LICENSE",
+  "bt.sh",
+  "commands/bootstrap.sh",
+  "lib/env.sh",
+  "prompts/implement.md",
+  "scripts/gh-pr.sh",
+];
+for (const p of mustHave) {
+  assert.ok(files.includes(p), `pack missing required file: ${p}`);
+}
+
+const mustNotHave = [".github/workflows/ci.yml", ".gitignore", "specs/"];
+for (const p of mustNotHave) {
+  const has = files.some((f) => f === p || f.startsWith(p));
+  assert.ok(!has, `pack unexpectedly includes: ${p}`);
+}
+
+process.stderr.write(`ok - pack includes ${files.length} files\n`);