fix: feat(96a): architect-bot user + directory + run script scaffold (#99)

architect/AGENTS.md

@@ -0,0 +1,65 @@
+<!-- last-reviewed: auto-generated -->
+# Architect — Agent Instructions
+
+## What this agent is
+
+The architect is a strategic decomposition agent that breaks down vision issues
+into development sprints. It proposes sprints via PRs on the ops repo and
+converses with humans through PR comments.
+
+## Role
+
+- **Input**: Vision issues from VISION.md, prerequisite tree from ops repo
+- **Output**: Sprint proposals as PRs on the ops repo, sub-issue files
+- **Mechanism**: Formula-driven execution via `formulas/run-architect.toml`
+- **Identity**: `architect-bot` on Forgejo
+
+## Responsibilities
+
+1. **Strategic decomposition**: Break down large vision items into coherent
+   sprints that can be executed by the dev agent
+2. **Design fork identification**: When multiple implementation approaches exist,
+   identify the forks and file sub-issues for each path
+3. **Sprint PR creation**: Propose sprints as PRs on the ops repo with clear
+   acceptance criteria and dependencies
+4. **Human conversation**: Respond to PR comments, refine sprint proposals based
+   on human feedback
+5. **Sub-issue filing**: After design forks are resolved, file concrete sub-issues
+   for implementation
+
+## Formula
+
+The architect is driven by `formulas/run-architect.toml`. This formula defines
+the steps for:
+- Research: analyzing vision items and prerequisite tree
+- Design: identifying implementation approaches and forks
+- Sprint proposal: creating structured sprint PRs
+- Sub-issue filing: creating concrete implementation issues
+
+## Execution
+
+Run via `architect/architect-run.sh`, which:
+- Acquires a cron lock and checks available memory
+- Sources shared libraries (env.sh, formula-session.sh)
+- Uses FORGE_ARCHITECT_TOKEN for authentication
+- Loads the formula and builds context from VISION.md, AGENTS.md, and ops repo
+- Executes the formula via `agent_run`
+
+## Cron
+
+Suggested cron entry (every 6 hours):
+```cron
+0 */6 * * * cd /path/to/disinto && bash architect/architect-run.sh
+```
+
+## State
+
+Architect state is tracked in `state/.architect-active` (disabled by default —
+empty file not created, just document it).
+
+## Related issues
+
+- #96: Architect agent parent issue
+- #100: Architect formula — research + design fork identification
+- #101: Architect formula — sprint PR creation with questions
+- #102: Architect formula — answer parsing + sub-issue filing

architect/architect-run.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# =============================================================================
+# architect-run.sh — Cron wrapper: architect execution via SDK + formula
+#
+# Synchronous bash loop using claude -p (one-shot invocation).
+# No tmux sessions, no phase files — the bash script IS the state machine.
+#
+# Flow:
+#   1. Guards: cron lock, memory check
+#   2. Source lib/env.sh, lib/formula-session.sh
+#   3. Override FORGE_TOKEN with FORGE_ARCHITECT_TOKEN
+#   4. Load formula from formulas/run-architect.toml
+#   5. Build context: VISION.md, AGENTS.md, prerequisite tree from ops repo
+#   6. Call agent_run to execute formula
+#
+# Usage:
+#   architect-run.sh [projects/disinto.toml]   # project config (default: disinto)
+#
+# Cron: 0 */6 * * *   # every 6 hours
+# =============================================================================
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FACTORY_ROOT="$(dirname "$SCRIPT_DIR")"
+
+# Accept project config from argument; default to disinto
+export PROJECT_TOML="${1:-$FACTORY_ROOT/projects/disinto.toml}"
+# shellcheck source=../lib/env.sh
+source "$FACTORY_ROOT/lib/env.sh"
+# Override FORGE_TOKEN with architect-bot's token (#747)
+FORGE_TOKEN="${FORGE_ARCHITECT_TOKEN:-${FORGE_TOKEN}}"
+# shellcheck source=../lib/formula-session.sh
+source "$FACTORY_ROOT/lib/formula-session.sh"
+# shellcheck source=../lib/worktree.sh
+source "$FACTORY_ROOT/lib/worktree.sh"
+# shellcheck source=../lib/guard.sh
+source "$FACTORY_ROOT/lib/guard.sh"
+# shellcheck source=../lib/agent-sdk.sh
+source "$FACTORY_ROOT/lib/agent-sdk.sh"
+
+LOG_FILE="$SCRIPT_DIR/architect.log"
+# shellcheck disable=SC2034  # consumed by agent-sdk.sh
+LOGFILE="$LOG_FILE"
+# shellcheck disable=SC2034  # consumed by agent-sdk.sh
+SID_FILE="/tmp/architect-session-${PROJECT_NAME}.sid"
+SCRATCH_FILE="/tmp/architect-${PROJECT_NAME}-scratch.md"
+WORKTREE="/tmp/${PROJECT_NAME}-architect-run"
+
+log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%S)Z] $*" >> "$LOG_FILE"; }
+
+# Ensure AGENT_IDENTITY is set for profile functions
+if [ -z "${AGENT_IDENTITY:-}" ] && [ -n "${FORGE_ARCHITECT_TOKEN:-}" ]; then
+  AGENT_IDENTITY=$(curl -sf -H "Authorization: token ${FORGE_ARCHITECT_TOKEN}" \
+    "${FORGE_URL:-http://localhost:3000}/api/v1/user" 2>/dev/null | jq -r '.login // empty' 2>/dev/null || true)
+fi
+
+# ── Guards ────────────────────────────────────────────────────────────────
+check_active architect
+acquire_cron_lock "/tmp/architect-run.lock"
+check_memory 2000
+
+log "--- Architect run start ---"
+
+# ── Load formula + context ───────────────────────────────────────────────
+load_formula "$FACTORY_ROOT/formulas/run-architect.toml"
+build_context_block VISION.md AGENTS.md ops:prerequisites.md ops:sprints/.gitkeep
+
+# ── Build structural analysis graph ──────────────────────────────────────
+build_graph_section
+
+# ── Ensure ops repo is available ───────────────────────────────────────
+ensure_ops_repo
+
+# ── Load lessons from .profile repo (pre-session) ────────────────────────
+profile_load_lessons || true
+LESSONS_INJECTION="${LESSONS_CONTEXT:-}"
+
+# ── Read scratch file (compaction survival) ───────────────────────────────
+SCRATCH_CONTEXT=$(read_scratch_context "$SCRATCH_FILE")
+SCRATCH_INSTRUCTION=$(build_scratch_instruction "$SCRATCH_FILE")
+
+# ── Build prompt ─────────────────────────────────────────────────────────
+build_sdk_prompt_footer "
+  Relabel:     curl -sf -H \"Authorization: token \${FORGE_TOKEN}\" -X PUT -H 'Content-Type: application/json' '${FORGE_API}/issues/{number}/labels' -d '{\"labels\":[LABEL_ID]}'
+  Comment:     curl -sf -H \"Authorization: token \${FORGE_TOKEN}\" -X POST -H 'Content-Type: application/json' '${FORGE_API}/issues/{number}/comments' -d '{\"body\":\"...\"}'
+  Close:       curl -sf -H \"Authorization: token \${FORGE_TOKEN}\" -X PATCH -H 'Content-Type: application/json' '${FORGE_API}/issues/{number}' -d '{\"state\":\"closed\"}'
+"
+
+PROMPT="You are the architect agent for ${FORGE_REPO}. Work through the formula below.
+
+## Project context
+${CONTEXT_BLOCK}${LESSONS_INJECTION:+## Lessons learned
+${LESSONS_INJECTION}
+}
+${GRAPH_SECTION}${SCRATCH_CONTEXT:+${SCRATCH_CONTEXT}
+}
+## Formula
+${FORMULA_CONTENT}
+
+${SCRATCH_INSTRUCTION}
+
+${PROMPT_FOOTER}"
+
+# ── Create worktree ──────────────────────────────────────────────────────
+formula_worktree_setup "$WORKTREE"
+
+# ── Run agent ─────────────────────────────────────────────────────────────
+export CLAUDE_MODEL="opus"
+
+agent_run --worktree "$WORKTREE" "$PROMPT"
+log "agent_run complete"
+
+# Write journal entry post-session
+profile_write_journal "architect-run" "Architect run $(date -u +%Y-%m-%d)" "complete" "" || true
+
+rm -f "$SCRATCH_FILE"
+log "--- Architect run done ---"