chore: bootstrap repository tooling and release automation

scripts/docs-sweep-once.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO="${REPO:-$HOME/projects/japanese/SubMiner}"
+LOCK_FILE="${LOCK_FILE:-/tmp/subminer-doc-sweep.lock}"
+STATE_FILE="${STATE_FILE:-/tmp/subminer-doc-sweep.state}"
+LOG_FILE="${LOG_FILE:-$REPO/.codex-doc-sweep.log}"
+TIMEOUT_SECONDS="${TIMEOUT_SECONDS:-240}"
+SUBAGENT_ROOT="${SUBAGENT_ROOT:-$REPO/docs/subagents}"
+SUBAGENT_INDEX_FILE="${SUBAGENT_INDEX_FILE:-$SUBAGENT_ROOT/INDEX.md}"
+SUBAGENT_COLLAB_FILE="${SUBAGENT_COLLAB_FILE:-$SUBAGENT_ROOT/collaboration.md}"
+SUBAGENT_AGENTS_DIR="${SUBAGENT_AGENTS_DIR:-$SUBAGENT_ROOT/agents}"
+LEGACY_SUBAGENT_FILE="${LEGACY_SUBAGENT_FILE:-$REPO/docs/subagent.md}"
+AGENT_ID="${AGENT_ID:-docs-sweep}"
+AGENT_ALIAS="${AGENT_ALIAS:-Docs Sweep}"
+AGENT_MISSION="${AGENT_MISSION:-Docs drift cleanup and coordination updates}"
+
+# Non-interactive agent command used to run the prompt.
+# Example:
+#   AGENT_CMD='codex exec'
+#   AGENT_CMD='opencode run'
+AGENT_CMD="${AGENT_CMD:-codex exec}"
+AGENT_ID_SAFE="$(printf '%s' "$AGENT_ID" | tr -c 'A-Za-z0-9._-' '_')"
+AGENT_FILE="${SUBAGENT_AGENTS_DIR}/${AGENT_ID_SAFE}.md"
+
+mkdir -p "$(dirname "$LOCK_FILE")"
+mkdir -p "$(dirname "$STATE_FILE")"
+mkdir -p "$SUBAGENT_ROOT" "$SUBAGENT_AGENTS_DIR" "$SUBAGENT_ROOT/archive"
+
+exec 9> "$LOCK_FILE"
+if ! flock -n 9; then
+	exit 0
+fi
+
+cd "$REPO"
+
+current_state="$({
+	git status --porcelain=v1
+	git ls-files --others --exclude-standard
+} | sha256sum | cut -d' ' -f1)"
+
+previous_state="$(cat "$STATE_FILE" 2> /dev/null || true)"
+if [[ "$current_state" == "$previous_state" ]]; then
+	exit 0
+fi
+
+printf '%s' "$current_state" > "$STATE_FILE"
+
+run_started_at="$(date -Is)"
+run_started_utc="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "[RUN] [$run_started_at] docs sweep running (agent_id=$AGENT_ID alias=$AGENT_ALIAS)"
+echo "[$run_started_at] state changed; starting docs sweep (agent_id=$AGENT_ID alias=$AGENT_ALIAS)" >> "$LOG_FILE"
+
+if [[ ! -f "$SUBAGENT_INDEX_FILE" ]]; then
+	cat > "$SUBAGENT_INDEX_FILE" << 'EOF'
+# Subagents Index
+
+Read first. Keep concise.
+
+| agent_id | alias | mission | status | file | last_update_utc |
+| --- | --- | --- | --- | --- | --- |
+EOF
+fi
+
+if [[ ! -f "$SUBAGENT_COLLAB_FILE" ]]; then
+	cat > "$SUBAGENT_COLLAB_FILE" << 'EOF'
+# Subagents Collaboration
+
+Shared notes. Append-only.
+
+- [YYYY-MM-DDTHH:MM:SSZ] [agent_id|alias] note, question, dependency, conflict, decision.
+EOF
+fi
+
+if [[ ! -f "$AGENT_FILE" ]]; then
+	cat > "$AGENT_FILE" << EOF
+# Agent: $AGENT_ID
+
+- alias: $AGENT_ALIAS
+- mission: $AGENT_MISSION
+- status: planning
+- branch: unknown
+- started_at: $run_started_utc
+- heartbeat_minutes: 20
+
+## Current Work (newest first)
+- [$run_started_utc] intent: initialize section
+
+## Files Touched
+- none yet
+
+## Assumptions
+- none yet
+
+## Open Questions / Blockers
+- none
+
+## Next Step
+- continue run
+EOF
+fi
+
+if [[ -f "$LEGACY_SUBAGENT_FILE" ]]; then
+	echo "[WARN] [$run_started_at] legacy file exists; prefer sharded layout: $LEGACY_SUBAGENT_FILE" | tee -a "$LOG_FILE"
+fi
+
+read -r -d '' PROMPT << EOF || true
+Watch for in-flight refactors. If repo changes introduced drift, update only:
+- README.md
+- AGENTS.md
+- docs/**/*.md
+- config.example.jsonc
+- docs/public/config.example.jsonc <-- generated automatically with make generate-example-config / bun run generate:config-example
+- package.json scripts/config references (only if needed)
+
+Coordination protocol:
+- Read in order before edits:
+  1) \`$SUBAGENT_INDEX_FILE\`
+  2) \`$SUBAGENT_COLLAB_FILE\`
+  3) \`$AGENT_FILE\`
+- Edit scope:
+  - MAY edit own file: \`$AGENT_FILE\`
+  - MAY append to collaboration: \`$SUBAGENT_COLLAB_FILE\`
+  - MAY update own row in index: \`$SUBAGENT_INDEX_FILE\`
+  - MUST NOT edit other agent files in \`$SUBAGENT_AGENTS_DIR\`
+- Ensure own file has updated: alias, mission, status, branch, started_at, heartbeat_minutes.
+- Add UTC ISO entries in "Current Work (newest first)" for intent/progress/handoff for this run.
+- Keep own file sections current: Files Touched, assumptions, blockers, next step.
+- Ensure index row for \`$AGENT_ID\` reflects alias/mission/status/file/last_update_utc.
+- If file conflict/dependency seen, append note in collaboration.
+
+Run metadata:
+- run_started_at_utc: $run_started_utc
+- repo: $REPO
+- agent_id: $AGENT_ID
+- agent_alias: $AGENT_ALIAS
+- agent_file: $AGENT_FILE
+
+Rules:
+- Keep edits minimal and accurate to current code.
+- Do not commit.
+- Do not push.
+- If ambiguous, do not guess; skip and report uncertainty.
+- Print concise summary with:
+  1) files changed + why
+  2) coordination updates made (\`$SUBAGENT_INDEX_FILE\`, \`$SUBAGENT_COLLAB_FILE\`, \`$AGENT_FILE\`)
+  3) open questions/blockers
+EOF
+
+quoted_prompt="$(printf '%q' "$PROMPT")"
+
+job_status=0
+if timeout "${TIMEOUT_SECONDS}s" bash -lc "$AGENT_CMD $quoted_prompt" >> "$LOG_FILE" 2>&1; then
+	run_finished_at="$(date -Is)"
+	echo "[OK]  [$run_finished_at] docs sweep complete (agent_id=$AGENT_ID)"
+	echo "[$run_finished_at] docs sweep complete (agent_id=$AGENT_ID)" >> "$LOG_FILE"
+else
+	run_failed_at="$(date -Is)"
+	exit_code=$?
+	job_status=$exit_code
+	echo "[FAIL] [$run_failed_at] docs sweep failed (exit $exit_code, agent_id=$AGENT_ID)"
+	echo "[$run_failed_at] docs sweep failed (exit $exit_code, agent_id=$AGENT_ID)" >> "$LOG_FILE"
+fi
+
+exit "$job_status"