@oneie/claude 0.6.0 → 0.7.0

package/scripts/factory-repo.sh

@@ -0,0 +1,1361 @@
+#!/usr/bin/env bash
+# factory-repo.sh — generate the standalone factory repo (github.com/one-ie/factory)
+#
+# The factory repo is OUTPUT, never a mirror. This script builds it from canon;
+# --check rebuilds and diffs, so drift is reported loudly instead of rotting.
+# Design: text/factory-repo-plan.md §1. Promise: text/factory-repo.md.
+#
+# Usage:
+#   factory-repo.sh <target-dir>          build the repo (fresh git history)
+#   factory-repo.sh --check-history [dir] one commit · no env/key blob on any ref
+#   factory-repo.sh --check [dir]         drift: canon vs a built tree
+#   factory-repo.sh --check-env-indirection
+#   factory-repo.sh --check-portability
+#   factory-repo.sh --check-targets
+#   factory-repo.sh --check-connect [dir]
+#   factory-repo.sh --check-no-secrets [dir]
+#   factory-repo.sh --check-tests [dir]
+#   factory-repo.sh --check-canon [dir]   spine cites nothing the tree lacks
+#   factory-repo.sh --check-substrate     live world-key round trip (needs ONE_ENV_FILE)
+#   factory-repo.sh --verify              build to temp, install published, run the checks
+#   factory-repo.sh --manifest            print the portability manifest
+#
+# Env:
+#   ONE_TARGET     workspace | published   (default: published)
+#   ONE_ENV_FILE   credentials for --check-substrate (default: one.ie/web/.env)
+#   FACTORY_VERIFY_CYCLE=0  skip --verify's real /do cycle (default: it RUNS — the
+#                           proof must not need extra env to pass; skipping still fails)
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT" || exit 1
+
+ONE_TARGET="${ONE_TARGET:-published}"
+
+# Pinned published versions — the version IS the boundary (plan §4).
+SDK_VERSION="^0.14.11"
+MCP_VERSION="^0.6.0"
+CLI_VERSION="^4.0.4"
+
+# A monorepo path is a directory that must exist on disk. `https://one.ie/x`
+# is a host, not a path — the factory repo reaches the substrate over HTTPS by
+# design, so matching the URL would flag the very thing we want.
+MONOREPO_PATH_RE='(^|[^:a-zA-Z0-9._-])(one\.ie/(web|ai)|pay/(backend|contracts|tools)|channels/src|api/src|sync/src|backup/src|schema/[a-z-]*\.tql)|\.dev\.vars'
+
+pass() { printf '  ok   %s\n' "$*"; }
+fail() { printf '  FAIL %s\n' "$*" >&2; FAILED=$((FAILED + 1)); }
+info() { printf '       %s\n' "$*"; }
+head_() { printf '\n== %s\n' "$*"; }
+
+# ---------------------------------------------------------------------------
+# The portability manifest — data, asserted against the scripts by
+# --check-portability. Three buckets:
+#
+#   portable       no monorepo path, no credential read           → ships
+#   needs-env      needs ONE_ENV_FILE and/or names monorepo paths
+#                  that degrade to no-ops when absent             → ships
+#   monorepo-only  hard-asserts against THIS tree; refuses
+#                  without it                                     → never ships
+# ---------------------------------------------------------------------------
+manifest() {
+  cat <<'MANIFEST'
+portable       browser-check.mjs
+portable       chrome.mjs
+portable       do-analyze.sh
+portable       do-learn-loop.sh
+portable       do-promise-lint.sh
+portable       do-recon-cache.sh
+portable       do-validate-armed.py
+portable       package.json
+portable       w1-recon.ts
+portable       wf-check.mjs
+needs-env      cc-connect.sh
+needs-env      do-accept.sh
+needs-env      do-auto.sh
+needs-env      do-derives-check.sh
+needs-env      do-fleet.sh
+needs-env      do-folder.sh
+needs-env      do-killswitch-audit.py
+needs-env      do-orchestrate.sh
+needs-env      do-promise-settle.sh
+needs-env      do-prove.sh
+needs-env      do-reconcile.sh
+needs-env      do-rubric.py
+needs-env      do-signal.sh
+needs-env      do-survey.sh
+needs-env      do-tier.sh
+needs-env      do-untracked-gate.sh
+needs-env      do-walk.sh
+needs-env      notify.sh
+needs-env      reconcile-allow.txt
+needs-env      rubric-weights.json
+needs-env      w4-rubric.ts
+monorepo-only  cc-events-proof.sh
+monorepo-only  do-consumer-sweep.sh
+monorepo-only  do-rank.py
+monorepo-only  do-smoke.sh
+monorepo-only  do-substrate-check.sh
+monorepo-only  do-tasks-wire-check.sh
+monorepo-only  do-ui-gate.sh
+monorepo-only  factory-check.sh
+monorepo-only  factory-repo.sh
+monorepo-only  factory-tasks-check.sh
+monorepo-only  fade-toxic.sh
+monorepo-only  hourly-brief.sh
+monorepo-only  outcome-pull.ts
+monorepo-only  promise-manifest.mjs
+monorepo-only  spine-canary.sh
+monorepo-only  subdomains-proof.sh
+monorepo-only  sync-claude-mirror.sh
+monorepo-only  tg-listen.sh
+monorepo-only  typedb-cluster-status.sh
+monorepo-only  typedb-env.sh
+monorepo-only  typedb-flap-recorder.sh
+monorepo-only  typedb-scratch.sh
+monorepo-only  typedb-probes/containment-probe.py
+monorepo-only  typedb-probes/panic-probe-version.py
+monorepo-only  typedb-probes/panic-probe.py
+monorepo-only  urls-lint.sh
+MANIFEST
+}
+
+# The canon pack: the text/ files the loop itself reads. Everything else in
+# text/ is this company's work product and never ships.
+canon_text() {
+  cat <<'CANON'
+text/CLAUDE.md
+text/contracts.md
+text/dictionary.md
+text/do.md
+text/do-engine-plan.md
+text/docs.md
+text/dsl.md
+text/one-loop.md
+text/one-ontology.md
+text/patterns.md
+text/promise-signals.md
+text/promises.md
+text/rubrics.md
+text/rubric-migration-plan.md
+text/templates.md
+text/templates-plan.md
+text/voice-and-tone.md
+text/writing-style-guide.md
+text/lifecycle.md
+text/routing.md
+text/routing-plan.md
+text/promise-plan.md
+text/skill-invocation.md
+text/surfaces-layers.md
+text/orchestrator-how-to.md
+text/do-autonomous-plan.md
+text/agent-template-plan.md
+text/marketplace.md
+text/factory.md
+text/factory-plan.md
+CANON
+}
+
+# text/ files the shipped spine references DELIBERATELY without shipping them.
+# Two kinds, both allowed, neither silent:
+#   company   this repo's own work product, cited as a worked example
+#   stale     the reference is already dead upstream (monorepo doc rot) —
+#             listed so --check-canon reports a real gap, not a known one
+allowed_dangling() {
+  cat <<'ALLOW'
+company  text/playbook.md
+company  text/remote-suspend-todo.md
+company  text/sdk-mcp-cli-schema-design-integration.md
+company  text/agent-api-plan.md
+company  text/workflow-bridge-plan.md
+stale    text/feature.md
+stale    text/loop-log-archive.md
+stale    text/rich-messages.md
+stale    text/template-frame.md
+stale    text/template-spec-plan.md
+ALLOW
+}
+
+# Files under .claude/ that are this machine's or this company's, not the loop's.
+excluded_claude() {
+  cat <<'EXCLUDED'
+.claude/settings.json
+.claude/settings.local.json
+.claude/improvements.queue.md
+.claude/typedb/dev.env
+.claude/commands/kill.md
+.claude/commands/restart.md
+.claude/commands/db-sync.md
+.claude/commands/deploy.md
+.claude/commands/release.md
+.claude/commands/oo-push.md
+.claude/skills/dev.md
+.claude/skills/build.md
+EXCLUDED
+}
+
+# ---------------------------------------------------------------------------
+# 1. classify — resolve which tracked scripts ship
+# ---------------------------------------------------------------------------
+ships() { # $1 = script basename/relpath under .claude/scripts
+  local b="$1"
+  local bucket
+  bucket="$(manifest | awk -v n="$b" '$2 == n {print $1}')"
+  [ -n "$bucket" ] || return 2   # unclassified
+  [ "$bucket" = "monorepo-only" ] && return 1
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# build — the 7 steps, each failing closed
+# ---------------------------------------------------------------------------
+build() {
+  local TARGET="$1"
+  [ -n "$TARGET" ] || { echo "usage: factory-repo.sh <target-dir>" >&2; return 2; }
+
+  if [ -e "$TARGET" ] && [ -n "$(ls -A "$TARGET" 2>/dev/null)" ]; then
+    echo "refusing: $TARGET exists and is not empty" >&2; return 2
+  fi
+
+  local STAGE; STAGE="$(mktemp -d)"
+  # No RETURN trap: bash keeps a RETURN trap set inside a function as the
+  # shell's trap, so it fires again (with STAGE unbound) on every later
+  # function return. Clean up explicitly instead — _bail does both.
+  _bail() { rm -rf "$STAGE"; return "$1"; }
+
+  # --- 1. classify -----------------------------------------------------
+  local unclassified=0
+  while IFS= read -r f; do
+    local rel="${f#.claude/scripts/}"
+    ships "$rel"; local rc=$?
+    [ $rc -eq 2 ] && { echo "unclassified script (add to manifest): $rel" >&2; unclassified=1; }
+  done < <(git ls-files .claude/scripts)
+  [ $unclassified -eq 0 ] || { echo "refusing to build with an incomplete manifest" >&2; _bail 3; return 3; }
+
+  # --- 2. assemble — from the TRACKED set, never `cp -r` ---------------
+  # Generating from `git ls-files` makes secret-exclusion structural: an
+  # untracked .env, a scratch dir, or node_modules cannot enter by accident.
+  local excl; excl="$(excluded_claude)"
+  while IFS= read -r f; do
+    case "$f" in
+      .claude/scripts/*)
+        ships "${f#.claude/scripts/}" || continue ;;
+    esac
+    grep -qxF "$f" <<<"$excl" && continue
+    # launchd plists hard-code this machine's absolute paths and schedule
+    # monorepo-only jobs; scratch/ is one cycle's leftovers. Neither travels.
+    case "$f" in .claude/launchd/*|.claude/scratch/*) continue ;; esac
+    mkdir -p "$STAGE/$(dirname "$f")"
+    cp "$f" "$STAGE/$f"
+  done < <(git ls-files .claude)
+
+  while IFS= read -r f; do
+    [ -f "$f" ] || { echo "canon missing: $f" >&2; _bail 3; return 3; }
+    mkdir -p "$STAGE/$(dirname "$f")"
+    cp "$f" "$STAGE/$f"
+  done < <(canon_text)
+
+  # The loop's doc templates — every -todo/-plan/-docs starts from one.
+  while IFS= read -r f; do
+    mkdir -p "$STAGE/$(dirname "$f")"
+    cp "$f" "$STAGE/$f"
+  done < <(git ls-files 'text/template-*.md')
+
+  # Accumulators: the loop APPENDS to these. Ship them seeded and empty — our
+  # history is not the collaborator's, but the files must exist or the first
+  # cycle that tries to append has nothing to append to.
+  printf '# Learnings\n\nOne line per closed cycle. See `.claude/rules/documentation.md`\n(§ Loop Close) for the format, including the eight-field rubric vector.\n' \
+    > "$STAGE/text/learnings.md"
+  printf '# Improvements\n\nAnchor mismatches and deferred fixes land here at `/close`, for the next\ncycle'"'"'s W2 to pick up. See `.claude/rules/documentation.md` § Loop Close.\n' \
+    > "$STAGE/text/improvements.md"
+  printf '# Loop log\n\nOne entry per ONE LOOP turn — lane, move, receipt. Read and appended by\n`.claude/workflows/one-loop.js`. See `text/one-loop.md`.\n' \
+    > "$STAGE/text/loop-log.md"
+
+  # --- 3. strip — settings.json never ships, and no absolute path travels ---
+  write_settings_example "$STAGE/.claude/settings.example.json"
+  portabilise "$STAGE" || { _bail 3; return 3; }
+
+  # --- 4. bind — the connect layer, one file ---------------------------
+  write_connect "$STAGE"
+  write_package_json "$STAGE" "$TARGET"
+  write_gitignore "$STAGE"
+  write_readme "$STAGE"
+  write_contributing "$STAGE"
+
+  # --- 5. scan — refuse to emit on a key-shaped string -----------------
+  if ! scan_secrets "$STAGE"; then
+    echo "refusing to emit: key-shaped string found in the staged tree" >&2
+    _bail 4; return 4
+  fi
+
+  # --- 6. seed — tests that reach into nothing -------------------------
+  write_tests "$STAGE"
+
+  # --- 7. init — fresh history, one commit, no remote ------------------
+  mkdir -p "$TARGET"
+  # shellcheck disable=SC2086
+  ( cd "$STAGE" && tar cf - . ) | ( cd "$TARGET" && tar xf - )
+  (
+    cd "$TARGET" || exit 1
+    git init -q -b main
+    git add -A
+    git -c user.name="ONE" -c user.email="build@one.ie" \
+      commit -q -m "The factory, standalone.
+
+Generated by .claude/scripts/factory-repo.sh from canon.
+Fresh history by design: a history-preserving cut of any prefix
+carries root-level blobs."
+  ) || return 5
+
+  rm -rf "$STAGE"
+  echo "built: $TARGET  (ONE_TARGET=$ONE_TARGET)"
+  echo "files: $(cd "$TARGET" && git ls-files | wc -l | tr -d ' ')"
+}
+
+# An absolute path to the maintainer's disk is not a secret, but it is a
+# dependency the clone cannot satisfy — and it tells a reader where the private
+# tree lives. Rewrite what can be made relative; refuse to emit what cannot.
+portabilise() {
+  local S="$1" home_re
+  home_re="$(printf '%s' "$ROOT" | sed 's/[][\.*^$/]/\\&/g')"
+
+  # The maintainer's workspace root — the directory the monorepo sits in. Paths
+  # under it name private sibling repos (vendoring provenance, /oo-push targets)
+  # and must not travel even as prose.
+  local WS; WS="$(dirname "$ROOT")"
+
+  local _sed
+  if sed --version >/dev/null 2>&1; then _sed=(sed -i); else _sed=(sed -i ''); fi
+
+  while IFS= read -r f; do
+    [ -f "$f" ] || continue
+    # The monorepo root becomes the repo root; the loop already runs from there.
+    "${_sed[@]}" -e "s|$ROOT/one\.ie/web|<the project you are building>|g" \
+                 -e "s|$ROOT|.|g" \
+                 -e "s|$WS/[A-Za-z0-9._-]*|<a private sibling repo>|g" "$f" 2>/dev/null || true
+  done < <(grep -rl -e "$ROOT" -e "$WS" "$S" 2>/dev/null)
+
+  # Anything still absolute under /Users or /home is a path we could not make
+  # portable. Fail closed rather than shipping a broken reference.
+  local left
+  left="$(grep -rlE '(/Users/[a-z]+/|/home/[a-z]+/)' "$S" 2>/dev/null | sed "s|^$S/||")"
+  if [ -n "$left" ]; then
+    echo "refusing to emit: absolute machine paths survive in:" >&2
+    echo "$left" | head -10 >&2
+    grep -rhoE '(/Users/[a-z]+/|/home/[a-z]+/)[^ "'"'"')]*' "$S" 2>/dev/null | sort -u | head -5 >&2
+    return 1
+  fi
+  return 0
+}
+
+write_settings_example() {
+  cat > "$1" <<'JSON'
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "env": {
+    "FABLE_AVAILABLE": "off"
+  },
+  "permissions": {
+    "allow": [
+      "Bash(bash .claude/scripts/*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Read(//**)"
+    ]
+  }
+}
+JSON
+}
+
+# The connect layer: ONE file names the URL and the key, and it names them
+# by ENV VAR, never by value. Nothing else in the repo knows a URL or a secret.
+write_connect() {
+  local S="$1"
+  cat > "$S/.mcp.json" <<JSON
+{
+  "mcpServers": {
+    "oneie": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@oneie/mcp@${MCP_VERSION#^}"],
+      "env": {
+        "ONEIE_API_URL": "\${ONEIE_API_URL:-https://one.ie}",
+        "ONEIE_API_KEY": "\${ONEIE_API_KEY}"
+      }
+    }
+  }
+}
+JSON
+
+  cat > "$S/.env.example" <<'ENVX'
+# The connect layer. Copy to .env and fill in. .env is gitignored and must stay that way.
+#
+# This private repo drives the PUBLIC stack — github.com/one-ie/one and the
+# published @oneie/{sdk,mcp,cli} packages — over the api.one.ie substrate.
+# Nothing here needs a private checkout.
+#
+# Mint your own key rather than being handed one — it carries exactly your
+# authority and nothing more:
+#
+#   npx -y @oneie/cli auth login
+#
+# ONEIE_API_URL must be the app origin, not the gateway. The MCP client calls
+# /api/* paths; https://api.one.ie serves the substrate unprefixed and every
+# tool 404s against it.
+
+# IMPORTANT: this file is not loaded for you. Claude Code expands ${VAR} in
+# .mcp.json from the PROCESS environment, and does not read .env. Export it
+# before starting the client, every session:
+#
+#   set -a; source .env; set +a
+#   claude
+#
+# Skip that and the MCP server starts with an empty key: every substrate tool
+# fails, and nothing says why.
+
+ONEIE_API_URL=https://one.ie
+ONEIE_API_KEY=
+
+# The loop's own scripts (signals, promise settle, the /close propagate) default
+# to a localhost dev server. In a clone there isn't one — point them at the live
+# substrate or every mark and warn the loop emits goes nowhere quietly.
+ONE_API_URL=https://one.ie
+
+# A dotenv file is not a shell: ${ONEIE_API_KEY} would be read literally by any
+# script that parses this file. Paste the SAME key here.
+ONE_API_KEY=
+
+# The loop's own scripts read credentials through this indirection, so the
+# harness never needs a one.ie/web/ on disk.
+ONE_ENV_FILE=.env
+ENVX
+}
+
+write_package_json() {
+  local S="$1" deps overrides=""
+  if [ "$ONE_TARGET" = "workspace" ]; then
+    # `workspace:*` only resolves for a member of a workspace that DECLARES it.
+    # A generated tree sitting outside the monorepo is not one, so a
+    # workspace:* dep here fails to resolve — verified: `bun install` errors on
+    # all three. The maintainer target therefore uses file: paths, computed at
+    # build time relative to this tree, which is what workspace:* was only
+    # pretending to be. Relative on purpose: portabilise() refuses to emit an
+    # absolute machine path, and a relative one is honest about being local.
+    # Absolute, deliberately. A relative link looked cleaner and was wrong:
+    # on macOS /var is a symlink to /private/var, so a path computed from an
+    # unresolved temp dir was one level short and every dep failed to resolve.
+    # The maintainer target is machine-local by definition and is never the
+    # tree that gets pushed, so naming the machine's path is honest here —
+    # --check-no-machine-paths asserts against the PUBLISHED target, which ships.
+    local rel="$ROOT"
+    deps="\"@oneie/sdk\": \"file:$rel/packages/sdk\",
+    \"@oneie/mcp\": \"file:$rel/packages/mcp\",
+    \"@oneie/cli\": \"file:$rel/packages/cli\""
+    # The linked packages declare workspace:* between THEMSELVES (cli → sdk,
+    # cli → evals). Those resolve for a workspace member and fail for anyone
+    # else, so every @oneie/* reachable transitively is overridden to the same
+    # local path. Without this, `bun install` errors on evals even though all
+    # three direct deps resolve — verified.
+    overrides=",
+  \"overrides\": {
+    \"@oneie/sdk\": \"file:$rel/packages/sdk\",
+    \"@oneie/mcp\": \"file:$rel/packages/mcp\",
+    \"@oneie/cli\": \"file:$rel/packages/cli\",
+    \"@oneie/evals\": \"file:$rel/packages/evals\",
+    \"@oneie/react\": \"file:$rel/packages/react\"
+  }"
+  else
+    deps="\"@oneie/sdk\": \"$SDK_VERSION\",
+    \"@oneie/mcp\": \"$MCP_VERSION\",
+    \"@oneie/cli\": \"$CLI_VERSION\""
+  fi
+  cat > "$S/package.json" <<JSON
+{
+  "name": "@one-ie/factory",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The ONE factory — the /do loop and its connect layer, standalone.",
+  "type": "module",
+  "scripts": {
+    "test": "bun test tests/",
+    "check": "bash .claude/scripts/wf-check.mjs 2>/dev/null; node .claude/scripts/wf-check.mjs"
+  },
+  "dependencies": {
+    $deps
+  }$overrides,
+  "engines": { "node": ">=20" },
+  "//": "ONE_TARGET=$ONE_TARGET — the version is the boundary. See README.md."
+}
+JSON
+}
+
+write_gitignore() {
+  cat > "$1/.gitignore" <<'GI'
+.env
+.env.*
+!.env.example
+.dev.vars
+*.key
+*.pem
+.claude/settings.local.json
+.claude/settings.json
+.claude/scratch/
+.claude/worktrees/
+.do-worktrees/
+node_modules/
+__pycache__/
+.DS_Store
+GI
+}
+
+# ---------------------------------------------------------------------------
+# step 5 — the scan. Runs BEFORE git init, so a secret can never enter
+# history even for one commit.
+# ---------------------------------------------------------------------------
+scan_secrets() {
+  local S="$1" hits=0
+  # Key shapes this substrate actually mints, plus the usual suspects.
+  local pat='(one-[0-9a-f]{32,})|(osk_[A-Za-z0-9]{16,})|(sk-[A-Za-z0-9_-]{20,})|(ghp_[A-Za-z0-9]{20,})|(suiprivkey[a-z0-9]{20,})|(AKIA[0-9A-Z]{16})|(-----BEGIN [A-Z ]*PRIVATE KEY-----)'
+  while IFS= read -r line; do
+    hits=$((hits + 1)); echo "  secret-shaped: $line" >&2
+  done < <(grep -rInE "$pat" "$S" 2>/dev/null | grep -v '\.env\.example:' | head -20)
+
+  # Any real dotenv (not the example) must not exist at all.
+  while IFS= read -r f; do
+    hits=$((hits + 1)); echo "  dotenv in tree: ${f#"$S"/}" >&2
+  done < <(find "$S" -name '.env' -o -name '.env.*' ! -name '.env.example' -o -name '.dev.vars' 2>/dev/null)
+
+  [ $hits -eq 0 ]
+}
+
+write_tests() {
+  local S="$1"
+  mkdir -p "$S/tests"
+  cat > "$S/tests/factory.test.ts" <<'TS'
+/**
+ * The factory repo's own suite. It reaches into nothing — reaching tests are
+ * what pin the monorepo together (24 files, 43 refs) and this tree must not
+ * inherit that. Every assertion below reads only this repo.
+ */
+import { describe, expect, test } from "bun:test"
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join } from "node:path"
+
+const ROOT = join(import.meta.dir, "..")
+const read = (p: string) => readFileSync(join(ROOT, p), "utf8")
+
+describe("the loop is present", () => {
+  test("/do and its spine exist", () => {
+    for (const f of [".claude/commands/do.md", ".claude/commands/close.md", ".claude/CLAUDE.md"])
+      expect(existsSync(join(ROOT, f))).toBe(true)
+  })
+
+  test("the four build-wave agents exist", () => {
+    for (const w of ["w1-recon", "w2-decide", "w3-edit", "w4-verify"])
+      expect(existsSync(join(ROOT, `.claude/agents/${w}.md`))).toBe(true)
+  })
+
+  test("the promise lint ships and is executable", () => {
+    expect(existsSync(join(ROOT, ".claude/scripts/do-promise-lint.sh"))).toBe(true)
+  })
+
+  test("the doc templates ship", () => {
+    const t = readdirSync(join(ROOT, "text")).filter((f) => f.startsWith("template-"))
+    expect(t.length).toBeGreaterThan(3)
+  })
+})
+
+describe("the boundary holds", () => {
+  test("no monorepo-only script shipped", () => {
+    const banned = ["factory-check.sh", "do-substrate-check.sh", "spine-canary.sh", "typedb-env.sh", "do-rank.py"]
+    for (const b of banned) expect(existsSync(join(ROOT, `.claude/scripts/${b}`))).toBe(false)
+  })
+
+  test("no shipped script HARD-depends on the monorepo", () => {
+    // The property that matters is not "never says one.ie/web" — a comment or
+    // an optional fallback path is harmless and degrades to nothing here. What
+    // breaks a clone is an *unconditional* dependency: importing a module from
+    // the monorepo, sourcing a file there, or writing output into it.
+    const scripts = readdirSync(join(ROOT, ".claude/scripts"), { withFileTypes: true })
+      .filter((e) => e.isFile())
+      .map((e) => `.claude/scripts/${e.name}`)
+
+    const HARD = [
+      /^\s*(import|export)\s.*['"][^'"]*one\.ie\/web[^'"]*['"]/m, // import from the app tree
+      /^\s*(source|\.)\s+\S*one\.ie\/web/m,                       // source a file there
+      /resolve\([^)]*['"]one\.ie\/web/m,                          // resolve an output path there
+    ]
+    const offenders = scripts.filter((f) => {
+      let src: string
+      try { src = read(f) } catch { return false }
+      return HARD.some((re) => re.test(src))
+    })
+    expect(offenders).toEqual([])
+  })
+
+  test("every shipped credential read honours ONE_ENV_FILE", () => {
+    // A script that reads one.ie/web/.env with no override cannot find
+    // credentials in a clone — it fails silently, which is worse than loudly.
+    const scripts = readdirSync(join(ROOT, ".claude/scripts"), { withFileTypes: true })
+      .filter((e) => e.isFile())
+      .map((e) => `.claude/scripts/${e.name}`)
+
+    const offenders = scripts.filter((f) => {
+      let src: string
+      try { src = read(f) } catch { return false }
+      if (!/one\.ie\/web\/\.(env|secrets|dev\.vars)/.test(src)) return false
+      return !/ONE_ENV_FILE/.test(src)
+    })
+    expect(offenders).toEqual([])
+  })
+
+  test("settings.json does not ship; the example does", () => {
+    // Assert what is TRACKED, not what is on disk. A set-up clone is a superset
+    // of the shipped tree: README step 3 tells you to create .claude/settings.json,
+    // so an existsSync check here goes red for every collaborator who followed
+    // the instructions — a suite that fails when you do it right teaches people
+    // to ignore the suite.
+    expect(existsSync(join(ROOT, ".claude/settings.example.json"))).toBe(true)
+    const gi = read(".gitignore")
+    expect(gi).toMatch(/^\.claude\/settings\.json$/m)
+  })
+
+  test("CONTRIBUTING.md ships and names the return path", () => {
+    // A generated tree that doesn't say it's generated invites the one mistake
+    // that loses work: fixing it here and never carrying it upstream. The doc
+    // has to name the direction, not just invite contributions generically.
+    expect(existsSync(join(ROOT, "CONTRIBUTING.md"))).toBe(true)
+    // \s+ between words, never a literal space: prose here is hard-wrapped at
+    // ~78 chars, so any phrase can acquire a newline mid-sentence on an edit.
+    const c = read("CONTRIBUTING.md")
+    expect(c).toMatch(/generated\s+output/i)
+    expect(c).toMatch(/not\s+a\s+second\s+source/i)
+    expect(c).toMatch(/pull\s+requests?\s+.*canonical\s+harness/is)
+    expect(c).toMatch(/regenerated\s+outward/i)
+  })
+})
+
+describe("the connect layer is one file", () => {
+  test(".mcp.json names the substrate by env var, never by value", () => {
+    const mcp = read(".mcp.json")
+    expect(mcp).toContain("@oneie/mcp")
+    expect(mcp).toContain("ONEIE_API_KEY")
+    expect(/one-[0-9a-f]{32,}/.test(mcp)).toBe(false)
+  })
+
+  test(".env is gitignored and .env.example is not", () => {
+    const gi = read(".gitignore")
+    expect(gi).toMatch(/^\.env$/m)
+    expect(gi).toMatch(/^!\.env\.example$/m)
+  })
+
+  test("no key-shaped string anywhere in the tree", () => {
+    const walk = (d: string): string[] =>
+      readdirSync(join(ROOT, d), { withFileTypes: true }).flatMap((e) => {
+        if (e.name === "node_modules" || e.name === ".git") return []
+        return e.isDirectory() ? walk(join(d, e.name)) : [join(d, e.name)]
+      })
+    const pat = /(one-[0-9a-f]{32,})|(osk_[A-Za-z0-9]{16,})|(sk-[A-Za-z0-9_-]{20,})|(-----BEGIN [A-Z ]*PRIVATE KEY-----)/
+    const offenders = walk(".").filter((f) => {
+      if (f.endsWith(".env.example")) return false
+      try { return pat.test(read(f)) } catch { return false }
+    })
+    expect(offenders).toEqual([])
+  })
+})
+TS
+}
+
+# Authored by the loop itself, in a clone, on 2026-07-30 — then folded back
+# into the generator. That round trip is the contribution path this file
+# describes, run once for real.
+write_contributing() {
+  cat > "$1/CONTRIBUTING.md" <<'MD'
+# Contributing
+
+This tree is **generated output**, not a second source. It is built from the
+canonical harness and can be rebuilt at any time — so a fix committed only here
+survives exactly until the next regeneration, then vanishes. That is not a bug
+to work around; it is the one direction of truth the factory keeps.
+
+## The return path
+
+An improvement travels back up, then outward again:
+
+```
+1. change it here          prove it in this tree — the loop is runnable
+2. pull request upstream    against the canonical harness, not against this tree
+3. regenerate outward       merged canon is regenerated into every built tree
+4. --check                  reports drift between a built tree and canon
+```
+
+Step 2 is the whole rule: **improvements return as pull requests against the
+canonical harness upstream and get regenerated outward.** One direction of
+truth, both ways of travelling it.
+
+Use this tree to *prove* the change — edit the command, run the loop, watch it
+close a cycle. Then carry the proven diff upstream. A patch that was never run
+here is a patch nobody has tested; a patch that only landed here is a patch
+nobody will keep.
+
+If the two ever disagree, canon wins and `--check` is how you find out.
+
+## What a returning change must hold
+
+The boundary is the reason a clone works at all, so contributions keep it:
+
+- **No secrets, ever.** Not in a file, not in one commit. The generator scans
+  for key-shaped strings *before* `git init`; `tests/factory.test.ts` scans the
+  whole tree again.
+- **No monorepo-only checks.** A script that asserts against the tree this was
+  generated from fails here for the wrong reason, so it must not ship.
+- **No hard dependency on a private checkout.** A comment or an optional
+  fallback is fine; an unconditional import, `source`, or output path into the
+  application tree is not.
+- **Credential reads honour `ONE_ENV_FILE`.** A script that reads a fixed
+  `.env` inside the app tree finds nothing in a clone and fails silently —
+  worse than failing loudly.
+- **Tests reach into nothing.** Every assertion in `tests/` reads only this
+  repo. Reaching tests are what pin a monorepo together, and this tree must not
+  inherit that.
+
+## Checks this tree can run
+
+Both run with no monorepo, no substrate, and no key:
+
+```bash
+bun test tests/     # the boundary suite — the tree's own shape
+bun run check       # syntax-checks .claude/workflows/*.js
+```
+
+Anything needing a workspace needs your own key (`.env.example` → `.env`) and
+is not part of the boundary suite by design.
+
+---
+
+*Details of what is deliberately absent, and why: `README.md`.*
+MD
+}
+
+write_readme() {
+  local S="$1"
+  cat > "$S/README.md" <<'MD'
+# The ONE Factory
+
+A loop that takes an intention and returns shipped, verified work — with a
+promise at the top that can only settle when a command exits zero.
+
+This repo is the loop itself, standalone. It contains no secrets, no tenant
+data, and no part of the system it was cut from. You point it at your own
+workspace and it builds *your* projects.
+
+**Private repo, public stack.** Everything the loop reaches for is open or
+published:
+
+| | |
+|---|---|
+| `github.com/one-ie/one` | the open-source starter the loop scaffolds projects from |
+| `@oneie/sdk` · `@oneie/mcp` · `@oneie/cli` | published on npm |
+| `api.one.ie` · `one.ie/api/*` | the substrate, over HTTPS |
+
+Nothing here requires a private checkout. The repo is private because the
+*loop* is the thing worth keeping close — not because its dependencies are.
+
+---
+
+## Clone to first closed cycle
+
+```bash
+git clone git@github.com:one-ie/factory.git
+cd factory
+
+# 1. mint your own key — it carries exactly your authority, nothing more
+npx -y @oneie/cli auth login
+
+# 2. bind the connect layer
+cp .env.example .env
+$EDITOR .env          # paste ONEIE_API_KEY
+
+# 3. bring the harness up
+cp .claude/settings.example.json .claude/settings.json
+bun install
+
+# 4. export — nothing loads .env for you, and an unexported
+#    key means every substrate tool fails without saying why
+set -a; source .env; set +a
+
+# 5. warm the npx cache once — on a cold cache the MCP
+#    server download outlasts startup and reads as unavailable
+npx -y @oneie/mcp@0.6.0 --help
+
+# 6. run the loop
+claude
+> /do add a health endpoint that reports substrate reachability
+```
+
+`/do` walks AIM → PROMISE → SURVEY → DESIGN → PLAN → BUILD → TEST → VERIFY →
+PROVE → TEACH → SHIP → LEARN. Every stage is an artifact made true; the promise
+at the top settles only when its `proof:` command exits zero.
+
+## Building a project
+
+The factory doesn't hold your project — it builds one, next to itself, from the
+public starter:
+
+```bash
+npx -y @oneie/cli new my-project     # scaffolds from github.com/one-ie/one
+cd my-project && bun install
+```
+
+Then run the loop against it. `/do` finds the project by its `text/` canon, so
+point it at the tree you want built:
+
+```bash
+claude
+> /do in ../my-project, add a pricing page that reads plans from the substrate
+```
+
+Every cycle closes back into the substrate — `mark` on what worked, `warn` on
+what didn't — so the next cycle starts from evidence rather than from scratch.
+
+## Adding tasks to the board
+
+Your tasks live in the substrate, not in a file. The MCP server in `.mcp.json`
+gives the loop — and you — a board:
+
+```
+tasks_create   title + notes + tags        → returns a tid
+tasks_list     the open queue, weight-ranked
+tasks_claim    take one off the queue, stamps @you
+tasks_status   open | picked | done | verified | dissolved
+```
+
+Or over plain HTTP, which is all the MCP server is doing:
+
+```bash
+curl -s -X POST https://one.ie/api/ask/tasks:create \
+  -H "Authorization: Bearer $ONEIE_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"data":{"title":"Ship the health endpoint","notes":"Done = /health returns 200 and names the substrate it reached.","tags":["factory"]}}'
+```
+
+The `data` envelope is required. Every task you create is tagged with your
+workspace, and the board ranks by *learned* weight where it has evidence — the
+priority you author is the starting point, not the final order.
+
+## What is here
+
+| | |
+|---|---|
+| `.claude/commands/` | `/do`, `/close`, `/go`, `/see`, `/create` … the operator surface |
+| `.claude/agents/` | the four build waves — recon, decide, edit, verify |
+| `.claude/skills/` | domain skills the loop pulls in on match |
+| `.claude/rules/` | auto-loaded per file glob |
+| `.claude/hooks/` | the gates — staging guards, doc-sync, outcome checks |
+| `.claude/scripts/` | the deterministic checks: promise lint, reconcile, rubric, walk |
+| `text/` | the canon the loop reads, and the doc templates it writes from |
+| `tests/` | this repo's own suite — it reaches into nothing |
+
+## What is deliberately absent
+
+Not an oversight, a boundary.
+
+- **No secrets.** The generator refuses to emit a tree containing a key-shaped
+  string, and it scans *before* `git init` — so nothing can enter history even
+  for one commit.
+- **No tenant data, no client sites, no application tree.**
+- **No production credentials.** You bring your own workspace and your own key.
+- **No upstream history.** This tree is born with one commit, because a
+  history-preserving cut of any prefix carries root-level blobs.
+- **No monorepo-only checks.** Scripts that assert against the tree this was
+  generated from do not ship; they would fail here for the wrong reason.
+
+## The two targets
+
+The repo binds to the substrate through a published interface, not a directory.
+
+```
+ONE_TARGET=published   @oneie/{sdk,mcp,cli} from npm
+                       (no monorepo on disk — the default)
+
+ONE_TARGET=workspace   workspace links, for a maintainer
+                       with the monorepo checked out
+```
+
+No source edits between them. The version is the boundary.
+
+## Contributing back
+
+This tree is **generated output**, not a second source. Improvements return as
+pull requests against the canonical harness upstream and get regenerated
+outward — one direction of truth, both ways of travelling it.
+
+The return path, the boundary suite a PR must keep green, and what never
+travels upstream: [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+*Generated by `factory-repo.sh`. Licence: see `.claude/LICENSE`.*
+MD
+}
+
+# ---------------------------------------------------------------------------
+# checks
+# ---------------------------------------------------------------------------
+tmpbuild() { # build into a temp dir and echo the path
+  local d; d="$(mktemp -d)/factory"
+  build "$d" >/dev/null 2>&1 || { echo ""; return 1; }
+  echo "$d"
+}
+
+use_tree() { # $1 = optional dir; else build one
+  if [ -n "${1:-}" ] && [ -d "$1" ]; then echo "$1"; else tmpbuild; fi
+}
+
+check_history() {
+  head_ "check-history — one commit, no env/key blob on any ref"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return; }
+  local n; n="$(git -C "$T" rev-list --count --all 2>/dev/null || echo 0)"
+  [ "$n" = "1" ] && pass "exactly one commit on all refs" || fail "expected 1 commit, found $n"
+  local blobs
+  blobs="$(git -C "$T" log --all --full-history --name-only --format="" \
+    -- '*.dev.vars' '*.env' '.env.*' '*secret*' '*.pem' '*.key' 2>/dev/null \
+    | grep -v '\.env\.example$' | sort -u)"
+  [ -z "$blobs" ] && pass "no env/key blob reachable from any ref" || fail "blobs in history: $blobs"
+  [ -z "$(git -C "$T" remote 2>/dev/null)" ] && pass "born with no remote" || info "remote already set (expected after handover)"
+}
+
+check_drift() {
+  head_ "check — drift between canon and a built tree"
+  local T="${1:-}"
+  if [ -z "$T" ] || [ ! -d "$T" ]; then
+    # Determinism first — a generator that varies makes every drift report noise.
+    local A B; A="$(tmpbuild)"; B="$(tmpbuild)"
+    [ -n "$A" ] && [ -n "$B" ] || { fail "build failed"; return; }
+    local d; d="$(diff -rq --exclude=.git "$A" "$B" 2>&1)"
+    [ -z "$d" ] && pass "generator is deterministic" || { fail "non-deterministic build:"; echo "$d" | head -10 >&2; }
+
+    # Then the drift the deliverable actually names: canon vs the PUBLISHED
+    # tree. Without this, "--check reports drift" was only ever comparing the
+    # generator to itself — and the live remote could rot unnoticed, which is
+    # the exact failure mode this repo is designed to avoid.
+    local REMOTE="${FACTORY_REMOTE:-https://github.com/one-ie/factory.git}"
+    local C; C="$(mktemp -d)/published"
+    if git clone -q --depth 1 "$REMOTE" "$C" 2>/dev/null; then
+      T="$C"
+      info "comparing canon against the published tree at $REMOTE"
+    else
+      # FAIL, never skip. This check's entire deliverable is "drift is detected
+      # loudly"; letting an unreachable remote pass green means the proof
+      # settles KEPT on a machine that verified no drift at all. Set
+      # FACTORY_CHECK_OFFLINE=1 to acknowledge deliberately — it still fails,
+      # because a check that did not run proved nothing.
+      if [ "${FACTORY_CHECK_OFFLINE:-0}" = "1" ]; then
+        fail "drift NOT CHECKED — FACTORY_CHECK_OFFLINE=1 was set deliberately"
+      else
+        fail "drift NOT CHECKED — cannot reach $REMOTE (no access, or no network)"
+        info "the published tree is the thing this check exists to compare against"
+      fi
+      return
+    fi
+  fi
+  local F; F="$(tmpbuild)"
+  [ -n "$F" ] || { fail "build failed"; return; }
+  local d; d="$(diff -rq --exclude=.git --exclude=node_modules --exclude=.env "$F" "$T" 2>&1)"
+  if [ -z "$d" ]; then pass "built tree matches canon"
+  else fail "drift vs canon:"; echo "$d" | head -30 >&2; fi
+}
+
+check_env_indirection() {
+  head_ "check-env-indirection — every credential read honours ONE_ENV_FILE"
+  local bad=0
+  while IFS= read -r rel; do
+    local f=".claude/scripts/$rel"
+    [ -f "$f" ] || continue
+    grep -qE 'one\.ie/web/\.(env|secrets|dev\.vars)' "$f" || continue
+    if grep -q 'ONE_ENV_FILE' "$f"; then
+      pass "$rel honours ONE_ENV_FILE"
+    else
+      fail "$rel reads one.ie/web/.env with no ONE_ENV_FILE override"; bad=1
+    fi
+  done < <(manifest | awk '$1 != "monorepo-only" {print $2}')
+
+  # Behavioural: point ONE_ENV_FILE at a foreign path and prove it is read.
+  # Behavioural: point ONE_ENV_FILE at a path nothing in this tree knows about
+  # and prove the resolver actually reads it. A grep for the variable name is
+  # not evidence the override works.
+  local tmp; tmp="$(mktemp -d)/foreign.env"
+  mkdir -p "$(dirname "$tmp")"
+  printf 'SERVER_SECRET=factory-repo-probe\n' > "$tmp"
+  local got; got="$(ONE_ENV_FILE="$tmp" bash .claude/scripts/do-signal.sh --print-env 2>/dev/null)"
+  if [ "$got" = "resolved-from: $tmp" ]; then
+    pass "do-signal.sh resolves credentials from a foreign ONE_ENV_FILE"
+  else
+    fail "ONE_ENV_FILE override is not honoured at runtime — got: ${got:-<nothing>}"; bad=1
+  fi
+
+  # And it must go red: with the override pointing at nothing, the resolver
+  # must not silently claim success.
+  local none; none="$(ONE_ENV_FILE=/nonexistent/nope.env bash .claude/scripts/do-signal.sh --print-env 2>/dev/null)"
+  if [ "$none" = "resolved-from: $tmp" ]; then
+    fail "the probe reports a stale path — it is not reading the override"; bad=1
+  else
+    pass "the probe tracks the override (proof it is a check, not theatre)"
+  fi
+  [ $bad -eq 0 ] || return 1
+}
+
+check_portability() {
+  head_ "check-portability — the manifest is asserted against the scripts"
+  local bad=0
+
+  # Every tracked script is classified.
+  while IFS= read -r f; do
+    local rel="${f#.claude/scripts/}"
+    manifest | awk -v n="$rel" '$2 == n {found=1} END {exit !found}' \
+      || { fail "unclassified: $rel"; bad=1; }
+  done < <(git ls-files .claude/scripts)
+
+  # Every manifest entry names a real file.
+  while IFS= read -r rel; do
+    [ -f ".claude/scripts/$rel" ] || { fail "manifest names a missing file: $rel"; bad=1; }
+  done < <(manifest | awk '{print $2}')
+
+  # `portable` means portable: no monorepo path, no credential read.
+  # A URL (https://one.ie/…) is not a path — the boundary is a directory that
+  # must exist on disk, not a host the script talks to over HTTPS.
+  while IFS= read -r rel; do
+    local f=".claude/scripts/$rel"
+    if grep -qE "$MONOREPO_PATH_RE" "$f" 2>/dev/null; then
+      fail "declared portable but names a monorepo path: $rel"
+      grep -nE "$MONOREPO_PATH_RE" "$f" | head -3 | sed 's/^/         /' >&2
+      bad=1
+    fi
+  done < <(manifest | awk '$1 == "portable" {print $2}')
+
+  [ $bad -eq 0 ] && pass "$(manifest | wc -l | tr -d ' ') scripts classified, portable set is clean"
+  [ $bad -eq 0 ] || return 1
+}
+
+check_targets() {
+  head_ "check-targets — one flag, no source edits"
+  local bad=0
+  local A B
+  A="$(ONE_TARGET=published tmpbuild)"; B="$(ONE_TARGET=workspace tmpbuild)"
+  [ -n "$A" ] && [ -n "$B" ] || { fail "build failed under one of the targets"; return 1; }
+
+  grep -q '"@oneie/sdk": "\^' "$A/package.json" && pass "published → pinned npm versions" \
+    || { fail "published target does not pin versions"; bad=1; }
+  grep -q '"@oneie/sdk": "file:' "$B/package.json" && pass "workspace → local file: links" \
+    || { fail "workspace target does not link locally"; bad=1; }
+
+  # A dep string is not a resolvable dep. `workspace:*` in a tree outside the
+  # workspace that declares it fails to resolve — verified, all three packages —
+  # so this must install, not merely parse. This is the check that caught it.
+  if command -v bun >/dev/null 2>&1; then
+    local out; out="$(cd "$B" && bun install --dry-run 2>&1)"
+    if grep -q 'failed to resolve' <<<"$out"; then
+      fail "workspace target does not install:"; grep 'failed to resolve' <<<"$out" | sed 's/^/         /' >&2; bad=1
+    else
+      pass "workspace target's deps actually resolve (bun install --dry-run)"
+    fi
+  else
+    info "bun not found — workspace deps not resolution-tested"
+  fi
+
+  local d; d="$(diff -rq --exclude=.git --exclude=package.json "$A" "$B" 2>&1)"
+  [ -z "$d" ] && pass "the two targets differ in package.json only — no source edits" \
+    || { fail "targets differ outside package.json:"; echo "$d" | head -10 >&2; bad=1; }
+  [ $bad -eq 0 ] || return 1
+}
+
+check_connect() {
+  head_ "check-connect — the connect layer is one file"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return 1; }
+  local bad=0
+
+  [ -f "$T/.mcp.json" ] && pass ".mcp.json present" || { fail ".mcp.json missing"; bad=1; }
+
+  # One file BINDS the substrate; many may READ it. The distinction is the
+  # whole point of a connect layer: `${ONE_API_URL:-https://one.ie}` in a
+  # script is a consumer with an overridable default, whereas a bare
+  # `ONE_API_URL=https://one.ie` is a second binding that .env can no longer
+  # move. Only unconditional assignments count as bindings.
+  local binders
+  binders="$(grep -rlE '^[[:space:]]*(export[[:space:]]+)?(ONEIE?_API_URL|ONEIE?_API_KEY)=[^$]' "$T" 2>/dev/null \
+    | sed "s|^$T/||" | grep -v '^\.env\.example$' | sort)"
+  [ -z "$binders" ] && pass "nothing but the connect layer binds the substrate — every other reference is an overridable default" \
+    || { fail "a second file binds the substrate:"; echo "$binders" >&2; bad=1; }
+
+  # Every shipped origin default must be overridable, or a clone is pinned to
+  # a host it cannot reach.
+  local pinned
+  # Overridable takes three shapes across bash, TS, and node: `${VAR:-url}`,
+  # `process.env.VAR ?? 'url'`, and `argv.find(…) ?? 'url'`. All three are fine.
+  # A doc example inside help text is not a binding either.
+  pinned="$(grep -rInE 'https?://(one\.ie|api\.one\.ie|localhost:4321)' "$T/.claude/scripts" "$T/.claude/hooks" 2>/dev/null \
+    | grep -vE '\$\{[A-Z_]+:-' \
+    | grep -vE '\?\?[[:space:]]*.https?://' \
+    | grep -vE '^\S+:[0-9]+:[[:space:]]*#' \
+    | grep -vE 'one\.ie/foo' \
+    | sed "s|^$T/||")"
+  [ -z "$pinned" ] && pass "no shipped script pins an origin it cannot be moved off" \
+    || { fail "a script pins an origin with no env override:"; echo "$pinned" | head -8 >&2; bad=1; }
+
+  # .env.example must set every origin the shipped scripts fall back on, or a
+  # clone silently signals into a localhost dev server that does not exist.
+  grep -q '^ONE_API_URL=' "$T/.env.example" && pass ".env.example moves the loop off the localhost default" \
+    || { fail ".env.example does not set ONE_API_URL — the loop would signal into localhost"; bad=1; }
+
+  # Claude Code expands ${VAR} in .mcp.json from the PROCESS environment and
+  # does not read dotenv files. A .env nobody exports is a connect layer that
+  # silently comes up with an empty key — so the tree must say so out loud.
+  grep -q 'source .env' "$T/.env.example" && pass ".env.example says how to actually load itself" \
+    || { fail ".env.example does not name the export step — a clone would start with an empty key"; bad=1; }
+
+  grep -q 'oneie/mcp' "$T/.mcp.json" && pass ".mcp.json runs the published @oneie/mcp" \
+    || { fail ".mcp.json does not reference @oneie/mcp"; bad=1; }
+  grep -qE 'one-[0-9a-f]{16,}' "$T/.mcp.json" && { fail ".mcp.json carries a literal key"; bad=1; } \
+    || pass ".mcp.json names the key by env var, never by value"
+
+  grep -q 'ONEIE_API_KEY' "$T/.env.example" && pass ".env.example names the key without a value" \
+    || { fail ".env.example does not name ONEIE_API_KEY"; bad=1; }
+  grep -qE '^ONEIE_API_KEY=$' "$T/.env.example" && pass "the example key is empty" \
+    || { fail ".env.example has a non-empty key"; bad=1; }
+  grep -qx '.env' "$T/.gitignore" && pass ".env is gitignored" || { fail ".env not gitignored"; bad=1; }
+  [ $bad -eq 0 ] || return 1
+}
+
+check_no_secrets() {
+  head_ "check-no-secrets — the scan, and the refusal"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return 1; }
+  if scan_secrets "$T"; then pass "no key-shaped string in the built tree"
+  else fail "key-shaped string in the built tree"; return 1; fi
+
+  # The check must be able to go red. Plant one and prove the scan catches it.
+  local canary; canary="$(mktemp -d)"
+  cp -R "$T/." "$canary/" 2>/dev/null
+  printf 'ONEIE_API_KEY=one-%s\n' "$(printf '0%.0s' $(seq 1 40))" > "$canary/planted.txt"
+  if scan_secrets "$canary" >/dev/null 2>&1; then
+    fail "the scan passed a tree containing a planted key — it cannot go red"
+    return 1
+  else
+    pass "the scan goes red on a planted key (proof it is a check, not theatre)"
+  fi
+  rm -rf "$canary"
+}
+
+check_tests() {
+  head_ "check-tests — the repo carries its own suite, reaching into nothing"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return 1; }
+  [ -f "$T/tests/factory.test.ts" ] && pass "suite present" || { fail "no suite"; return 1; }
+
+  if grep -qE '\.\./\.\./(one\.ie|pay|channels|api|schema)' "$T/tests/"*.ts 2>/dev/null; then
+    fail "the suite reaches out of the repo"; return 1
+  fi
+  pass "the suite has no cross-tree imports"
+
+  if command -v bun >/dev/null 2>&1; then
+    local out; out="$(cd "$T" && bun test tests/ 2>&1)"
+    if grep -qE '[0-9]+ pass' <<<"$out" && ! grep -qE '[1-9][0-9]* fail' <<<"$out"; then
+      pass "suite runs green in the built tree — $(grep -oE '[0-9]+ pass' <<<"$out" | head -1)"
+    else
+      fail "suite is red in the built tree:"; echo "$out" | tail -25 >&2; return 1
+    fi
+  else
+    info "bun not found — suite present but not executed"
+  fi
+}
+
+# The shipped harness reads canon. A command that cites text/lifecycle.md in a
+# tree that doesn't carry it sends the reader — human or agent — to a file that
+# isn't there. This was real: rules/documentation.md names SIX source-of-truth
+# docs and the first build shipped four.
+check_canon() {
+  head_ "check-canon — the spine cites nothing the tree does not carry"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return 1; }
+  local bad=0 allow; allow="$(allowed_dangling | awk '{print $2}')"
+
+  local dangling=""
+  while IFS= read -r ref; do
+    [ -f "$T/$ref" ] && continue
+    grep -qxF "$ref" <<<"$allow" && continue
+    dangling="$dangling$ref
+"
+  done < <(grep -rhoE 'text/[a-z0-9-]+\.md' \
+             "$T/.claude/commands" "$T/.claude/rules" \
+             "$T/.claude/agents" "$T/.claude/workflows" 2>/dev/null | sort -u)
+
+  if [ -z "$dangling" ]; then
+    pass "every text/ file the spine cites is present, or explicitly allowed"
+  else
+    fail "the spine cites canon the tree does not carry:"
+    printf '%s' "$dangling" | sed 's/^/         /' >&2
+    bad=1
+  fi
+
+  # The allowlist must not rot either: an entry that is now shipped, or a
+  # `stale` entry that came back upstream, is a stale exemption.
+  while IFS= read -r line; do
+    local kind ref; kind="${line%% *}"; ref="${line##* }"
+    if [ -f "$T/$ref" ]; then
+      fail "allowlisted but now shipped — drop the exemption: $ref"; bad=1
+    elif [ "$kind" = "stale" ] && [ -f "$ROOT/$ref" ]; then
+      fail "allowlisted as stale but exists upstream now — reclassify: $ref"; bad=1
+    fi
+  done < <(allowed_dangling)
+
+  # It must be able to go red.
+  local canary; canary="$(mktemp -d)/tree"
+  mkdir -p "$canary/.claude/commands"
+  printf 'see text/definitely-not-shipped.md\n' > "$canary/.claude/commands/probe.md"
+  if grep -rhoE 'text/[a-z0-9-]+\.md' "$canary/.claude/commands" | grep -q 'definitely-not-shipped'; then
+    pass "the check goes red on a planted dangling reference"
+  else
+    fail "the dangling-reference scan cannot detect a planted reference"; bad=1
+  fi
+  rm -rf "$canary"
+  [ $bad -eq 0 ] || return 1
+}
+
+check_no_machine_paths() {
+  head_ "check-no-machine-paths — no absolute path to the maintainer's disk travels"
+  local T; T="$(use_tree "${1:-}")" || { fail "build failed"; return 1; }
+  local left
+  left="$(grep -rlE '(/Users/[a-z]+/|/home/[a-z]+/)' "$T" 2>/dev/null | sed "s|^$T/||")"
+  [ -z "$left" ] && pass "no absolute machine path in the built tree" \
+    || { fail "absolute machine paths survive in:"; echo "$left" | head -8 >&2; return 1; }
+
+  # It must be able to go red: plant one and prove the build refuses.
+  local canary; canary="$(mktemp -d)/tree"
+  mkdir -p "$canary"; cp -R "$T/." "$canary/" 2>/dev/null
+  printf 'cd /Users/someone/private/repo && bun run dev\n' > "$canary/planted.sh"
+  if grep -rqE '(/Users/[a-z]+/|/home/[a-z]+/)' "$canary" 2>/dev/null; then
+    pass "the check goes red on a planted path (proof it is a check, not theatre)"
+  else
+    fail "the check passed a tree containing a planted machine path"; return 1
+  fi
+  rm -rf "$canary"
+}
+
+# Live round trip on the rail a standalone clone actually uses: a world key,
+# over HTTPS, no monorepo. Reads ONE_ENV_FILE (or the monorepo default).
+check_substrate() {
+  head_ "check-substrate — a world key creates a task over plain HTTPS"
+  local envf="${ONE_ENV_FILE:-$ROOT/one.ie/web/.env}"
+  local key="${ONEIE_API_KEY:-}" url="${ONEIE_API_URL:-https://one.ie}"
+  if [ -z "$key" ] && [ -f "$envf" ]; then
+    key="$(grep -m1 -E '^(ONEIE_API_KEY|ONE_API_KEY)=' "$envf" | cut -d= -f2- | tr -d '"'"'"' ')"
+  fi
+  if [ -z "$key" ]; then
+    # FAIL, never skip — same reasoning as --check. This is the deliverable that
+    # says a clone can put work on a board; with no key the round trip never
+    # happens, so passing green would settle the contract on nothing.
+    if [ "${FACTORY_SKIP_SUBSTRATE:-0}" = "1" ]; then
+      fail "substrate rail NOT CHECKED — FACTORY_SKIP_SUBSTRATE=1 was set deliberately"
+    else
+      fail "substrate rail NOT CHECKED — no ONEIE_API_KEY in env or $envf"
+      info "the live round trip is the proof that a clone can add tasks; without a key there is none"
+    fi
+    return
+  fi
+
+  local body; body="$(curl -s -m 20 -X POST "$url/api/ask/tasks:create" \
+    -H "Authorization: Bearer $key" -H 'Content-Type: application/json' \
+    -d '{"data":{"title":"factory-repo --check-substrate probe","notes":"Automated rail probe. Dissolved immediately.","tags":["factory","probe"]}}')"
+  local tid; tid="$(sed -n 's/.*"tid":"\([^"]*\)".*/\1/p' <<<"$body")"
+  if [ -n "$tid" ]; then
+    pass "task created over the world-key rail — $tid"
+    curl -s -m 20 -o /dev/null -X POST "$url/api/ask/tasks:status" \
+      -H "Authorization: Bearer $key" -H 'Content-Type: application/json' \
+      -d "{\"data\":{\"tid\":\"$tid\",\"status\":\"dissolved\"}}"
+    pass "probe dissolved"
+  else
+    fail "tasks:create did not return a tid: $(head -c 200 <<<"$body")"; return 1
+  fi
+}
+
+verify() {
+  head_ "verify — build to temp, no monorepo assumed, run every check"
+  local T; T="$(mktemp -d)/factory"
+  build "$T" || { fail "build failed"; return 1; }
+  info "built at $T"
+
+  FAILED=0
+  check_history "$T"
+  check_connect "$T"
+  check_no_secrets "$T"
+  check_tests "$T"
+  check_portability
+  check_targets
+  check_canon "$T"
+
+  head_ "verify — the loop in a clone"
+  # Default ON. The opt-in version was a cross-surface lie: the proof passed
+  # when a human ran it with FACTORY_VERIFY_CYCLE=1 and failed under
+  # do-promise-settle.sh, which runs the proof string verbatim with no extra
+  # env — so the promise settled BROKEN while every check was green. A proof
+  # that only passes with setup its own settle harness doesn't apply is not the
+  # proof in the contract. Set FACTORY_VERIFY_CYCLE=0 to skip deliberately;
+  # skipping still FAILS, because a cycle that didn't run proved nothing.
+  if [ "${FACTORY_VERIFY_CYCLE:-1}" = "1" ] && command -v claude >/dev/null 2>&1; then
+    info "running a real /do cycle in $T …"
+    # A freshly generated tree is an untrusted workspace, so Claude Code ignores
+    # settings.json's permissions.allow and every bash gate in W4 goes unrun.
+    # The mode must be passed here or this step silently proves less than it
+    # claims — the cycle "closes" without its deterministic checks having fired.
+    local log="$T/../cycle.log" after
+    (
+      cd "$T" || exit 1
+      cp .claude/settings.example.json .claude/settings.json
+      claude -p --permission-mode "${FACTORY_VERIFY_PERMS:-bypassPermissions}" \
+        "${FACTORY_VERIFY_PROMPT:-/do PATCH: create docs/standalone-proof.md — a short file recording that this tree closed a /do cycle with no monorepo on disk, naming the date and what the boundary suite asserts. The file does not exist yet; create it. Then run \`bun test tests/\` and report the count. Close the cycle properly.}"
+    ) > "$log" 2>&1
+    after="$(cd "$T" && git status --porcelain | wc -l | tr -d ' ')"
+    local suite; suite="$(cd "$T" && bun test tests/ 2>&1 | grep -oE '[0-9]+ pass' | head -1)"
+    if [ "$after" -gt 0 ] && [ -n "$suite" ] && ! (cd "$T" && bun test tests/ 2>&1 | grep -qE '[1-9][0-9]* fail'); then
+      pass "a real cycle ran in the clone and left the boundary suite green — $after file(s) changed, $suite"
+    else
+      fail "the cycle did not close — $after file(s) changed, suite: ${suite:-none}"
+      info "cycle transcript: $log"
+      tail -20 "$log" 2>/dev/null | sed 's/^/       | /' >&2
+    fi
+  else
+    fail "NOT RUN — a real /do cycle in a clone is the deliverable that gates KEPT."
+    if command -v claude >/dev/null 2>&1; then
+      info "FACTORY_VERIFY_CYCLE=0 was set. Unset it to run the cycle."
+    else
+      info "\`claude\` not on PATH — the cycle cannot run here."
+    fi
+  fi
+
+  head_ "verify — result"
+  [ "$FAILED" -eq 0 ] && echo "  all green" || echo "  $FAILED check(s) red"
+  return "$FAILED"
+}
+
+# ---------------------------------------------------------------------------
+FAILED=0
+case "${1:-}" in
+  --manifest)              manifest ;;
+  --check-history)         check_history "${2:-}" ;;
+  --check)                 check_drift "${2:-}" ;;
+  --check-env-indirection) check_env_indirection ;;
+  --check-portability)     check_portability ;;
+  --check-targets)         check_targets ;;
+  --check-connect)         check_connect "${2:-}" ;;
+  --check-no-secrets)      check_no_secrets "${2:-}" ;;
+  --check-tests)           check_tests "${2:-}" ;;
+  --check-canon)           check_canon "${2:-}" ;;
+  --check-no-machine-paths) check_no_machine_paths "${2:-}" ;;
+  --check-substrate)       check_substrate ;;
+  --verify)                verify ;;
+  -h|--help|"")            sed -n '2,30p' "$0" ;;
+  -*)                      echo "unknown flag: $1" >&2; exit 2 ;;
+  *)                       build "$1" ;;
+esac
+rc=$?
+[ "$FAILED" -gt 0 ] && exit 1
+exit $rc