Additional Policy Guides

[ArchonVII]

We should have global policies for hooks, GitHub Actions, sweeps, skills, agent lifecycle scripts, release flow, and propagation. But “global” should mean global source-of-truth and policy shape, not machine-global behavior that every repo silently obeys.

The uploaded repo map points at the right meta-layer surfaces: .github, github-workflows, repo-template, and archon-setup.

The pattern should be:

Global policy source
  ↓
Repo-local contract / pointer
  ↓
Implementation: hook, workflow, script, sweep, skill, or setup task
  ↓
Audit / enforcement / manifest trail
  ↓
Explicit propagation, not silent sync

That matches the direction already present in the ecosystem overview: provider repos publish source-of-truth, archon-setup snapshots/audits/onboards, and consumer repos stay coordination-isolated.

---

Recommended policy families

Policy family	Should exist?	Source of truth	Consumer surface	Enforcement / audit
Document policy	Yes	.github/STARTER.md + repo-template doc policy	README.md, AGENTS.md, docs/**	doc-sweep, repo-update-log, PR closeout
Git hooks policy	Yes	repo-template/.githooks/** + docs/agent-process/hooks-policy.md	.githooks/**, AGENTS.md	pre-commit, commit-msg, hook tests
GitHub Actions policy	Yes	github-workflows/docs/actions-policy.md	thin caller workflows in consumer repos	reusable workflows, repo-required-gate / decision, actionlint
Agent lifecycle policy	Yes	repo-template/AGENTS.md, scripts/agent/**	npm run agent:*, .agent/startup-baseline.json	startup audit, lifecycle tests
Coordination policy	Already exists, should be formalized	repo-template/.agent/coordination/README.md	.agent/coordination/**	local claims, board, doc-sweep lock
Doc sweep / orphan recovery policy	Already exists	repo-template/docs/agent-process/doc-sweep.md	scripts/doc-sweep/**	sweep runner, optional cron detector
Skill policy	Already exists	jma-skill-review/docs/skills-policy.md	active session skill registry / repair path	skill path audit
Propagation / snapshot policy	Yes	archon-setup/docs/propagation-policy.md	manifest, global update catalog	refresh-snapshots, onboarding audit
Release / changelog policy	Yes	.github/STARTER.md + github-workflows	CHANGELOG.md, .changelog/unreleased/**	changelog-fragment workflow
Security / secrets policy	Yes	split between .github/SECURITY.md, archon-setup, workflow docs	repo-local security docs as needed	dependency-review, secret scan, server constraints

---

The core rule

Policy should live where the authority lives

Thing	Correct authority
Community health defaults	.github
Reusable GitHub Actions bodies	github-workflows
Git hooks, agent scripts, repo-local contracts	repo-template
Setup, snapshots, onboarding, distribution	archon-setup
Shared skills / personas	jma-skill-review
App-specific behavior	the app repo itself

That means we should not create one GLOBAL_POLICY.md that tries to govern everything. It would become stale and would blur source-of-truth ownership.

Instead, create a global policy index plus domain-specific policies.

---

Proposed structure

ArchonVII/archon-setup/
  docs/ecosystem-overview.md
  docs/policy-index.md                 # meta index: where each policy lives
  docs/propagation-policy.md           # snapshot/update/distribution rules

ArchonVII/.github/
  STARTER.md                           # global document policy / new repo policy
  docs/release-policy.md               # optional, if release rules outgrow STARTER

ArchonVII/github-workflows/
  docs/actions-policy.md               # reusable workflow policy
  docs/required-gate-policy.md         # optional if gate policy grows

ArchonVII/repo-template/
  docs/agent-process/document-policy.md
  docs/agent-process/hooks-policy.md
  docs/agent-process/agent-lifecycle-policy.md
  docs/agent-process/doc-sweep.md      # already present
  .agent/coordination/README.md        # already present

ArchonVII/jma-skill-review/
  docs/skills-policy.md                # already present
  docs/skill-catalog.md

archon-setup/docs/policy-index.md should be meta-layer only. It should not be copied into every consumer repo, because ordinary repos should start from their own AGENTS.md, not from an ecosystem-wide map. The current ecosystem overview already says consumer repos should not assume sibling repos exist.

---

Hooks policy

We should definitely have a hooks policy.

Right now the hook behavior exists in several places: the template README explains the commit-msg and pre-commit baseline, including Conventional Commit enforcement, main-branch protection, owner-maintenance exceptions, and bypass logging. The actual pre-commit hook blocks direct commits to main / master except for the narrow Owner Maintenance Lane and logs bypasses.

A formal hooks policy should define:

Topic	Rule
Authority	Hooks are repo-owned, shipped from repo-template, installed locally per clone
Purpose	Prevent unsafe local state from reaching commits
Scope	Commit message format, protected-branch guard, checkout-role guard, owner-maintenance lane
Bypass	Allowed only through named env vars that log to .agent/bypass.log
Testing	Every hook behavior change must update hook tests
Propagation	Change provider first in repo-template, then refresh archon-setup snapshots
Consumer drift	Onboarding audit should detect stale or missing hook baselines

Suggested file:

repo-template/docs/agent-process/hooks-policy.md

Short pointer in AGENTS.md:

## Local Hooks

This repo uses the ArchonVII hook baseline. The full policy lives at
`docs/agent-process/hooks-policy.md`.

Hooks are safety gates, not suggestions. Do not bypass with `--no-verify`.
Named bypass env vars are allowed only when the hook documents them and the
bypass leaves an audit trail.

---

GitHub Actions policy

We should also have a GitHub Actions policy.

github-workflows already acts as the workflow provider. It says consumers opt in by adding thin caller workflows that use reusable workflows pinned to @v1. It also already establishes the single required branch-protection check: repo-required-gate / decision.

A formal Actions policy should define:

Topic	Rule
Authority	Workflow bodies live in github-workflows; consumers use thin callers
Versioning	Consumers pin to @v1; breaking changes require v2
Required checks	Prefer one stable required gate over path-filtered required checks
Action validation	Workflow changes require actionlint
Caller policy	Consumer repos may tune inputs but should not fork reusable bodies casually
Retag policy	Moving v1 requires explicit release/owner step
Security	Minimal permissions, no unsafe pull_request_target patterns
Propagation	Provider PR → retag if needed → snapshot refresh → consumer audit

Suggested file:

github-workflows/docs/actions-policy.md

This should not replace the README workflow table. The README stays “what exists and how to consume it”; the policy doc says “what rules govern workflow design, versioning, and enforcement.”

---

“Other things” policy

The catch-all should be an automation capability policy.

Any automation that can read, write, commit, open issues, alter PR state, merge, install files, or distribute changes should have a policy record.

That includes:

Capability	Needs policy?	Why
scripts/agent/start-task / status / prune	Yes	Creates worktrees, branches, task state, cleanup decisions
scripts/doc-sweep/**	Already has one	Can commit recovered docs
anomaly triage	Yes	Turns agent notes into PR comments/issues
archon-setup feature registry	Yes	Installs files and records manifests
global update catalog	Yes	Can distribute policy blocks into repos
release automation	Yes	Changes changelog, tags, release notes
skills/hooks/personas	Yes	Affect agent runtime behavior
branch protection setup	Yes	Changes repo governance
label setup	Lower-level, but yes	Affects issue/PR workflow vocabulary

The universal rule:

Any automation that mutates repo state must declare its authority, trigger, inputs, write targets, safety gates, audit trail, rollback/disable path, and propagation model.

---

Policy template for any automation

Use this template for hooks, actions, sweeps, scripts, skills, or setup tasks:

# <Capability> Policy

> **Status:** draft | active | superseded
> **Owner:** <repo / role>
> **Source of truth:** <repo/path>
> **Consumer surface:** <files/scripts/workflows installed in repos>
> **Propagation:** <manual | snapshot refresh | @v1 tag | global update catalog>
> **Last reviewed:** YYYY-MM-DD

## Purpose

What problem this capability solves.

## Authority boundary

What this capability may do, and what it must never do.

## Applies to

Repos, paths, agents, branches, events, or workflows covered by this policy.

## Does not apply to

Explicit exclusions.

## Runtime triggers

When this runs: commit, PR open, PR synchronize, session start, closeout, cron, manual command.

## Inputs

Files, env vars, labels, PR body markers, config files, secrets, CLI args.

## Write targets

Every path, GitHub object, branch, label, comment, issue, release, or manifest this may mutate.

## Safety gates

Validation, liveness checks, secret scans, role separation, branch checks, idempotency, dry-run behavior.

## Audit trail

Where results are recorded: logs, PR body, comments, repo-update-log, manifest, issue, changelog.

## Escape hatches

Allowed bypasses, who may use them, and what must be logged.

## Rollback / disable

How to undo or safely disable the capability.

## Propagation

How updates move from provider to consumers.

## Verification

Required tests/checks before changing this capability.

---

Where I would start

The next useful policy PR should not try to cover everything at once. I would create three small policy docs:

archon-setup/docs/policy-index.md
repo-template/docs/agent-process/hooks-policy.md
github-workflows/docs/actions-policy.md

Then update:

repo-template/AGENTS.md
repo-template/.agent/startup-baseline.json
archon-setup/docs/ecosystem-overview.md
archon-setup/src/registry/features.json or snapshots as needed

The first PR goal would be:

Establish the policy architecture for automation: documents, hooks, actions, sweeps, skills, and propagation each have a source-of-truth owner, repo-local contract surface, enforcement mechanism, and audit trail.

That gives us a cohesive system without turning every repo into a copy of the meta-layer.