ArchonVII · ArchonVII · Jun 11, 2026 · Jun 11, 2026
@@ -0,0 +1,69 @@
+version: 1
+
+required_gate:
+  check_name: repo-required-gate / decision
+  workflow: .github/workflows/repo-required-gate.yml
+
+defaults:
+  stack: minimal
+  runner: github-hosted
+  optimize_for: lower-spend
+
+paths:
+  code:
+    requires:
+      - language-ci
+    patterns:
+      - src/**
+      - lib/**
+      - bin/**
+      - scripts/**
+      - test/**
+      - tests/**
+      - "**/*.js"
+      - "**/*.mjs"
+      - "**/*.cjs"
+      - "**/*.ts"
+      - "**/*.tsx"
+      - "**/*.py"
+  workflows:
+    requires:
+      - workflow-validation
+    patterns:
+      - .github/workflows/**
+      - .githooks/**
+  policy:
+    requires:
+      - policy-validation
+    patterns:
+      - AGENTS.md
+      - CLAUDE.md
+      - GEMINI.md
+      - .agent/**
+      - .github/**
+  dependencies:
+    requires:
+      - dependency-review
+      - language-ci
+    patterns:
+      - package.json
+      - package-lock.json
+      - pnpm-lock.yaml
+      - yarn.lock
+      - pyproject.toml
+      - requirements.txt
+      - requirements-dev.txt
+      - uv.lock
+      - poetry.lock
+  release:
+    requires:
+      - policy-validation
+    patterns:
+      - CHANGELOG.md
+      - .changelog/**
+  docs:
+    requires: []
+    patterns:
+      - docs/**
+      - README.md
+      - "**/*.md"
@@ -0,0 +1,36 @@
+# Coordination
+
+This repo is **coordination-isolated**. It coordinates only itself.
+
+- Do not read from or write to machine-global coordination boards.
+- Do not assume sibling repositories exist.
+- Do not reference another repo unless this repo explicitly documents that dependency.
+
+## Where coordination lives
+
+All coordination state for this repo lives under `.agent/coordination/`:
+
+```
+.agent/coordination/
+  README.md      # this contract (always present)
+  board.md       # active multi-agent board (only if this repo does active coordination)
+  claims/        # per-agent file claims / locks (optional)
+  handoffs/      # cross-session handoff notes (optional)
+  references/    # documented dependencies on other repos, if any (optional)
+```
+
+`README.md` is the only file guaranteed to exist. Everything else is created on demand,
+when this repo actually needs active coordination.
+
+## Enabling an active board
+
+If multiple agents (or people) work this repo concurrently, create or keep `board.md`
+here and record: claim format, high-contention files that need sequencing, stale-claim
+cleanup rules, and worktree conventions. A starter template ships via the archon-setup
+`coordination-board` feature; you can also write your own.
+
+## Tracked vs. untracked
+
+This repo owns the **contract** (`README.md`). Whether live coordination state
+(`board.md`, `claims/`, locks) is committed, `.gitignore`d, or handled through issues and
+PRs is this repo's choice — setup does not assume one collaboration model.
@@ -0,0 +1,30 @@
+{
+  "version": "2026-06-08-agent-start-map",
+  "required": [
+    "AGENTS.md",
+    "docs/plans/README.md",
+    ".agent/check-map.yml",
+    ".agent/coordination/README.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    "docs/repo-update-log.md",
+    "package.json",
+    "scripts/agent/lib.mjs",
+    "scripts/agent/start-task.mjs",
+    "scripts/agent/status.mjs",
+    "scripts/agent/prune.mjs",
+    "scripts/agent/pr-body.mjs",
+    "scripts/doc-sweep/lib.mjs",
+    "scripts/doc-sweep/git.mjs",
+    "scripts/doc-sweep/sweep.mjs",
+    "docs/agent-process/doc-sweep.md"
+  ],
+  "expectedDirectories": [
+    "docs/plans/",
+    "docs/agent-process/",
+    "scripts/agent/",
+    "scripts/doc-sweep/"
+  ],
+  "legacy": [
+    "docs/superpowers/plans/"
+  ]
+}
@@ -0,0 +1,8 @@
+### Added
+
+- Installed the ArchonVII governance baseline for this repository, including AGENTS/Claude/Gemini contracts, lifecycle helpers, hooks, CODEOWNERS, Dependabot, PR template, doc-sweep files, and the repo update log.
+
+### Changed
+
+- Documented that this repo owns reusable workflow bodies and examples, while generated-repo lifecycle and hook baselines remain sourced from `repo-template` and installed through `archon-setup`.
+- Fixed the minimal CI example command quoting so the examples pass actionlint as valid YAML.
@@ -0,0 +1,39 @@
+# `.changelog/unreleased/`
+
+Per-PR CHANGELOG fragments. Each PR adds one file here named:
+
+```
+<issue-number>-<short-slug>.md
+```
+
+Example: `42-oauth-device-flow.md`.
+
+## Fragment format
+
+```markdown
+### Added
+
+- New thing in clear prose.
+
+### Changed
+
+- What changed.
+
+### Fixed
+
+- What you fixed.
+```
+
+Use one or more of the standard [Keep a Changelog](https://keepachangelog.com/) sections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+
+## Fold cadence
+
+Periodically (manually for now), all fragments are concatenated into `CHANGELOG.md` under `## [Unreleased]` and the fragment files are deleted in one commit. The PR author does not edit `CHANGELOG.md` directly.
+
+## Opting out
+
+If a PR genuinely does not warrant an entry (pure refactor, test-only, chore), apply the `no-changelog` label and the CI gate (`ArchonVII/github-workflows/.github/workflows/changelog-fragment.yml`) will skip it.
+
+## Delete this directory if you're using "Mode 1"
+
+If your repo edits `CHANGELOG.md` directly, this whole `.changelog/` tree should not exist. See `STARTER.md` for the two modes.
@@ -0,0 +1,6 @@
+# Force LF for shell scripts so the .githooks/ baseline runs correctly
+# regardless of the cloning OS. Bash hooks fail with CRLF on Git Bash
+# ("bad interpreter: /usr/bin/env\r: No such file or directory") and on
+# CI Linux runners.
+*.sh        text eol=lf
+.githooks/* text eol=lf
@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+#
+# commit-msg — Repo-template baseline.
+#
+# Enforces two policies on the commit message:
+#
+#   1. Conventional-commit prefix from a fixed allow-list.
+#   2. Reference to a tracked issue or task — `(#NNN)` or `task/<id>` —
+#      unless the commit is scoped to throwaway scratch work, an append-log
+#      ledger, or the Owner Maintenance Lane:
+#        - scratch: `chore(scratch):` / `docs(scratch):` prefix, OR every
+#          staged path lives under `docs/scratch/**`;
+#        - append-log ledger: every staged path is a named ledger
+#          (`.claude/noticed.md`, `.claude/napkin.md`) — any subject;
+#        - Owner Maintenance: `docs(owner):` / `chore(owner):` plus add-only
+#          safe maintenance paths.
+#
+# Bypass for the issue-ref rule (logged in commit metadata via the env
+# var name itself — reviewers can grep for it):
+#
+#   ALLOW_NO_ISSUE_REF=1 git commit ...
+#
+# The conventional-commit prefix is non-bypassable here on purpose.
+# Reformat the message instead.
+#
+
+set -euo pipefail
+
+msg_file="${1:?commit-msg hook expects the message file as argument 1}"
+hook_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=.githooks/scripts/owner-maintenance.sh
+source "${hook_dir}/scripts/owner-maintenance.sh"
+
+# Strip comment lines (git includes the diff/template comments) before
+# inspecting the first non-empty line.
+first_line="$(grep -vE '^\s*#' "$msg_file" | sed -n '/[^[:space:]]/{p;q;}')"
+
+if [[ -z "${first_line}" ]]; then
+    echo "[commit-msg] Empty commit message; aborting." >&2
+    exit 1
+fi
+
+# --- Conventional commit prefix check ----------------------------------
+# Allowed types per repo policy. Scopes and breaking-change `!` are
+# optional. Matches:  feat: x | fix(api): x | chore(scratch)!: x
+cc_re='^(feat|fix|docs|chore|refactor|test|ci|build|perf|revert|style)(\([^)]+\))?!?: .+'
+if ! [[ "${first_line}" =~ ${cc_re} ]]; then
+    cat >&2 <<EOF
+[commit-msg] Conventional-commit prefix required.
+
+Got:    ${first_line}
+Expect: <type>(<scope>)?: <description>
+
+Allowed types: feat, fix, docs, chore, refactor, test, ci, build, perf,
+               revert, style.
+
+Examples:
+  feat(hooks): add commit-msg baseline (#16)
+  fix: handle empty diff in close-scan
+  chore(scratch): noodling on idea X
+
+This rule is not bypassable. Reformat the message and try again.
+EOF
+    exit 1
+fi
+
+# --- Scratch-scope exemptions ------------------------------------------
+# A commit is "scratch" if either:
+#   (a) the message prefix is chore(scratch): or docs(scratch):, OR
+#   (b) every staged path lives under docs/scratch/.
+is_scratch=0
+if [[ "${first_line}" =~ ^(chore|docs)\(scratch\) ]]; then
+    is_scratch=1
+else
+    # `--cached` lists staged paths. Empty output (e.g. amend with no
+    # staged changes) shouldn't be treated as scratch — fall through to
+    # the issue-ref check.
+    staged="$(git diff --cached --name-only --diff-filter=ACMRTD 2>/dev/null || true)"
+    if [[ -n "${staged}" ]]; then
+        # Treat as scratch only when *every* path is under docs/scratch/.
+        non_scratch="$(printf '%s\n' "${staged}" | grep -vE '^docs/scratch/' || true)"
+        if [[ -z "${non_scratch}" ]]; then
+            is_scratch=1
+        fi
+    fi
+fi
+
+if [[ "${is_scratch}" -eq 1 ]]; then
+    exit 0
+fi
+
+# --- Append-log ledger exemption ---------------------------------------
+# Agent-local note ledgers (see owner_maintenance_is_append_log in
+# owner-maintenance.sh) are written to frequently by standing conventions.
+# When *every* staged path is such a ledger, skip the issue-ref requirement —
+# the path allowlist is the safety boundary, exactly like the docs/scratch/**
+# lane above. Any conventional-commit subject is fine; no (owner) scope needed.
+ledger_staged="$(git diff --cached --name-only --diff-filter=ACMRTD 2>/dev/null || true)"
+if [[ -n "${ledger_staged}" ]]; then
+    all_ledger=1
+    while IFS= read -r ledger_path; do
+        [[ -n "${ledger_path}" ]] || continue
+        if ! owner_maintenance_is_append_log "${ledger_path}"; then
+            all_ledger=0
+            break
+        fi
+    done <<< "${ledger_staged}"
+    if [[ "${all_ledger}" -eq 1 ]]; then
+        exit 0
+    fi
+fi
+
+# --- Owner Maintenance Lane exemption ----------------------------------
+# This lane is intentionally narrow: lightweight direct-main maintenance with
+# add-only safe files and an explicit docs(owner): / chore(owner): subject.
+if owner_maintenance_subject "${first_line}"; then
+    if owner_maintenance_staged_paths_safe; then
+        exit 0
+    fi
+
+    cat >&2 <<EOF
+[commit-msg] docs(owner): / chore(owner): is only valid for Owner Maintenance Lane commits.
+
+Owner Maintenance Lane requires every staged path to be add-only and safe:
+  - docs/research/**
+  - docs/notes/**
+  - docs/assets/**
+  - image files
+  - .changelog/**
+
+Unsafe paths, modifications, deletes, renames, and copies require an issue/PR lane.
+EOF
+    exit 1
+fi
+
+# --- Issue reference check ---------------------------------------------
+# Accept (#NNN) anywhere, or a task/<id> reference (alnum / dash / dot /
+# underscore / slash after the prefix). Searches the whole message body,
+# not just the subject — trailers count.
+body="$(grep -vE '^\s*#' "$msg_file" | tr '\n' ' ')"
+if [[ "${body}" =~ \#[0-9]+ ]] || [[ "${body}" =~ task/[A-Za-z0-9._/-]+ ]]; then
+    exit 0
+fi
+
+if [[ "${ALLOW_NO_ISSUE_REF:-0}" == "1" ]]; then
+    echo "[commit-msg] ALLOW_NO_ISSUE_REF=1 — bypassing issue-ref requirement." >&2
+    exit 0
+fi
+
+cat >&2 <<EOF
+[commit-msg] Commit message must reference a tracked issue or task.
+
+Subject: ${first_line}
+
+Acceptable references (anywhere in the message body or trailers):
+  - GitHub issue:  (#123)
+  - Task id:       task/<id>
+
+Scratch-scope exemptions:
+  - Message prefixed chore(scratch): or docs(scratch):
+  - All staged paths under docs/scratch/
+
+Append-log ledger exemption (any conventional-commit subject):
+  - All staged paths are append-log ledgers (.claude/noticed.md,
+    .claude/napkin.md) — added or modified
+
+Owner Maintenance exemption:
+  - Message prefixed docs(owner): or chore(owner):
+  - All staged paths are add-only safe maintenance files
+
+Bypass (leaves an audit trail via the env-var name):
+  ALLOW_NO_ISSUE_REF=1 git commit ...
+
+See .githooks/commit-msg for the rule source.
+EOF
+exit 1