Config Repository Functional Specification¶

This document defines the functional specification of this repository, including the intended structure and how shared configuration assets are organized.

Usage guidance is documented in README.md at the repository root. This document is the specification source of truth under docs. Structural details are documented in Config Repository Architecture, and operational issue handling is documented in Troubleshooting.

Scope¶

Item	Detail
Features	APM packages, GitHub Actions workflows, Renovate policy
Environments	All consumer repositories (dev, CI, production)
Exclusions	Runtime application code, infrastructure provisioning

Out-of-scope items:

Application-level business logic
Infrastructure resource provisioning
Language-specific runtime libraries
Autogenerated documentation

Overview¶

This repository provides shared configuration assets for AI-assisted development and platform operations.

The primary goals are:

share AI agent settings as APM-distributed packages
share reusable GitHub Actions workflows
share Renovate update policy and defaults

Prerequisites¶

APM CLI for package-based distribution
GitHub Actions for workflow execution and workflow reuse
Renovate for dependency update automation

Repository Structure¶

The repository structure is function-oriented.

Root-Level Components¶

README.md: usage and onboarding
docs/: repository specifications and reference documents
apm.yml: APM package metadata and dependency entry point
apm.lock.yaml: lock file for deterministic APM resolution
renovate/: Renovate shared policy definitions
.github/workflows/: reusable and caller workflows

.apm/packages/: grouped package bundles for target environments
- common/: shared workflows, documentation, and tools (MCP servers + instructions + skills, including loop domain skills: docs-updater, ci-sweeper, changelog, tech-debt, refactor)
- common-hooks-claude/, common-hooks-copilot/, common-hooks-cursor/: target-specific common hooks
- aws/: AWS development (MCP servers only)
- terraform/: Terraform development (MCP server + hook + instruction + skills)
- terraform-aws/: Terraform + AWS integration (MCP server only)
- terraform-hooks-claude/, terraform-hooks-copilot/, terraform-hooks-cursor/: target-specific Terraform hooks
- go/: Go development (hook + instruction + skills)
- go-hooks-claude/, go-hooks-copilot/, go-hooks-cursor/: target-specific Go hooks
- shell-script/: Shell script development (hook + instruction + skills)
- shell-script-hooks-claude/, shell-script-hooks-copilot/, shell-script-hooks-cursor/: target-specific shell script hooks
apm.yml: APM package metadata and dependency entry point
apm.lock.yaml: lock file for deterministic APM resolution
apm_modules/: locally materialized module content

Validation and Utility Components¶

scripts/: execution helpers for validation, build, and deployment support
test/: test assets and fixtures
env/: container and environment helpers

APM¶

This repository shares AI agent settings as APM-distributed packages. Each package is a self-contained bundle of MCP servers, hooks, instructions, and skills for a specific domain.

Package Architecture¶

The repository uses a multi-package structure under .apm/packages/. Each package has its own apm.yml and optional .apm/ subdirectory containing hooks, instructions, and skills.

.apm/packages/
├── common/          # Shared workflows, documentation, and tools
│   ├── apm.yml      # 5 MCP servers
│   └── .apm/
│       ├── instructions/  # 4 instruction files
│       └── skills/        # 12 skills (includes loop domain skills)
├── common-hooks-claude/   # Common hooks for Claude Code (6 hooks)
├── common-hooks-copilot/  # Common hooks for GitHub Copilot CLI (6 hooks)
├── common-hooks-cursor/   # Common hooks for Cursor (6 hooks)
├── aws/             # AWS development
│   └── apm.yml      # 5 MCP servers
├── terraform/       # Terraform development (cloud-agnostic)
│   ├── apm.yml      # 1 MCP server
│   └── .apm/
│       ├── instructions/  # 1 instruction file
│       └── skills/        # 2 skills
├── terraform-aws/   # Terraform + AWS integration
│   └── apm.yml      # 1 MCP server
├── terraform-hooks-claude/  # Terraform hooks for Claude Code (2 hooks)
├── terraform-hooks-copilot/ # Terraform hooks for GitHub Copilot CLI (2 hooks)
├── terraform-hooks-cursor/  # Terraform hooks for Cursor (2 hooks)
├── go/              # Go development
│   ├── apm.yml      # 0 MCP servers
│   └── .apm/
│       ├── instructions/  # 1 instruction file
│       └── skills/        # 2 skills
├── go-hooks-claude/       # Go hooks for Claude Code (1 hook)
├── go-hooks-copilot/      # Go hooks for GitHub Copilot CLI (1 hook)
├── go-hooks-cursor/       # Go hooks for Cursor (1 hook)
├── shell-script/    # Shell script development
│   ├── apm.yml      # 0 MCP servers
│   └── .apm/
│       ├── instructions/  # 2 instruction files
│       └── skills/        # 2 skills
├── shell-script-hooks-claude/  # Shell script hooks for Claude Code (2 hooks)
├── shell-script-hooks-copilot/ # Shell script hooks for GitHub Copilot CLI (2 hooks)
└── shell-script-hooks-cursor/  # Shell script hooks for Cursor (2 hooks)

Distribution Behavior¶

The repository must be consumable as an APM dependency.

consumers can install the full package or individual sub-packages with apm install
package resolution must be deterministic with apm.lock.yaml
configuration assets are deployed to the appropriate target by APM
each sub-package is independently installable via its path

Configuration Philosophy¶

APM packages distribute configuration. Tool execution rules differ by layer — do not treat hooks or skills as MCP-style runtime fetch.

Layer Summary¶

Layer	Purpose	Tool resolution	When tool absent	Quality guarantee
MCP	Agent capabilities at runtime	`npx` / `uvx`, pinned in `apm.yml`	Server fails to start	N/A (capability, not lint)
Hooks	Optional in-session lint/format	Native binary on `PATH`	Exit 0	No — best-effort only
Skills	On-demand validation when invoked	Native binary via `validate.sh`	`SKIP` in output	No — agent-triggered only

Consumer Setup Tiers¶

Minimal (MCP and configuration):

APM CLI, Node.js (npx) and/or Python with uv (uvx), network for runtime fetch
No per-linter global install before apm install

Recommended dev (full hook/skill enforcement):

Linters on PATH (for example via mise)
Same packages behave differently: hooks run checks instead of skipping

MCP — Runtime Resolution¶

Prefer ephemeral runners with pinned versions:

- name: context7
  command: npx
  args: ["-y", "@upstash/context7-mcp@3.2.3"]

Optional binary MCP servers (no npm/PyPI package) use a bare command and require separate consumer install — for example codebase-memory-mcp. Consumers may omit these servers.

Hooks — Optional Enforcement¶

Hooks invoke native binaries when present on PATH. Most hook tools are not available via npx/uvx.

command -v actionlint > /dev/null 2>&1 || exit 0

Hooks exit 0 when optional native tools are missing so agent sessions continue. This is intentional — hooks are not a substitute for CI or pre-commit. lean-ctx agent hooks and shell integration are left to lean-ctx itself (not distributed via common-hooks-*).

Skills — Explicit Validation¶

Validation skills (*-validation, plus agent-skills-review) run through scripts/validate.sh when an agent invokes them. Missing tools produce SKIP in structured output rather than silent pass. Judgment review skills (*-review other than agent-skills-review) have no scripts/validate.sh — they apply checklist references only.

Authoring rules: companion rules (stem agent-skills, instructions) — portability and structure only; see APM Package Design Principles. Maintainer routing: CLAUDE.md. Design context: Config Repository Architecture.

MCP Servers¶

MCP servers are declared in each package's apm.yml under dependencies.mcp.

Package	Server	Transport	Command
common	context7	stdio	npx
common	fetch	stdio	uvx
common	github	stdio	bash
common	codebase-memory-mcp	stdio	binary (optional; consumer install)
common	lean-ctx	stdio	npx
aws	aws-mcp	streamable-http	url (OAuth)
aws	aws-knowledge-mcp-server	stdio	uvx
aws	aws-documentation-mcp-server	stdio	uvx
aws	aws-pricing-mcp-server	stdio	uvx
terraform	hashicorp-terraform-mcp-server	stdio	npx
terraform-aws	awslabs-terraform-mcp-server	stdio	uvx

Hooks¶

Hooks provide optional, best-effort lint and format when native binaries are on PATH. They are not a quality gate — missing tools cause exit 0, not failure. For full enforcement, install linters separately (see Configuration Philosophy consumer setup tiers).

Hooks are defined as JSON files under each hooks package's .apm/hooks/ directory.

Hooks Package	Hook	Trigger	Description
common-hooks-*	markdownlint-cli2	Stop	Auto-fix Markdown files with markdownlint
common-hooks-*	markdown-link-check	Stop	Check Markdown links
common-hooks-*	github-actions-actionlint	Stop	Lint GitHub Actions workflows with actionlint
common-hooks-*	github-actions-ghalint	Stop	Lint GitHub Actions workflows with ghalint
common-hooks-*	github-actions-zizmor	Stop	Security scan `.github` with zizmor when workflows/actions change
common-hooks-*	gitleaks	Stop	Scan changed files for secrets with gitleaks
go-hooks-*	golangci-lint	Stop	Auto-fix Go files with golangci-lint
terraform-hooks-*	terraform-fmt	PostToolUse	Run terraform fmt on changed files
terraform-hooks-*	tflint	Stop	Run tflint on changed files
shell-script-hooks-*	shellcheck	Stop	Run shellcheck on changed shell scripts
shell-script-hooks-*	shfmt	Stop	Auto-format shell scripts with shfmt

Note: * represents target suffix (claude, copilot, or cursor). Each target has identical hook scripts with different JSON formats.

Hooks are distributed as separate target-specific packages because each AI agent has a different hooks JSON format:

Hooks Package	Target	Hooks	Description
common-hooks-claude	Claude	6	Common hooks for Claude Code
common-hooks-copilot	Copilot	6	Common hooks for GitHub Copilot CLI
common-hooks-cursor	Cursor	6	Common hooks for Cursor
go-hooks-claude	Claude	1	Go hooks for Claude Code
go-hooks-copilot	Copilot	1	Go hooks for GitHub Copilot CLI
go-hooks-cursor	Cursor	1	Go hooks for Cursor
shell-script-hooks-claude	Claude	2	Shell script hooks for Claude Code
shell-script-hooks-copilot	Copilot	2	Shell script hooks for GitHub Copilot CLI
shell-script-hooks-cursor	Cursor	2	Shell script hooks for Cursor
terraform-hooks-claude	Claude	2	Terraform hooks for Claude Code
terraform-hooks-copilot	Copilot	2	Terraform hooks for GitHub Copilot CLI
terraform-hooks-cursor	Cursor	2	Terraform hooks for Cursor

Hooks Limitations¶

Hooks JSON format is incompatible across AI agents and cannot be auto-converted between targets:

Each agent uses a different JSON structure (event names, command keys, timeout keys, nesting depth)
Copilot CLI uses camelCase (agentStop), Claude Code/VS Code use PascalCase (Stop), Cursor uses lowercase (stop)
Claude Code uses 2-level nesting ({ matcher, hooks: [...] }) with tool name regex filtering (matcher)
The hook scripts themselves are multi-agent aware and portable; only the hook JSON definitions need per-target packaging

Skills¶

Validation skills (*-validation, plus agent-skills-review) provide on-demand validation when an agent invokes them through scripts/validate.sh. Missing native binaries produce SKIP in structured output — not silent pass. Judgment review skills load checklist references/ only (no in-skill validate.sh). Skills are agent-triggered; they do not replace CI, pre-commit, or hooks. See Configuration Philosophy.

Skills are defined under each package's .apm/skills/ directory. Each skill contains a SKILL.md and references; validation skills also ship scripts/validate.sh (and related helpers).

Package	Skill
common	agent-skills-review
common	changelog
common	ci-sweeper
common	docs-creator
common	docs-updater
common	github-actions-review
common	github-actions-validation
common	github-pr-body
common	instructions-review
common	markdown-validation
common	refactor
common	tech-debt
go	go-review
go	go-validation
terraform	terraform-review
terraform	terraform-validation
shell-script	shell-script-review
shell-script	shell-script-validation

Instructions¶

Instructions are defined under each package's .apm/instructions/ directory.

Package	Instruction	Scope
common	agent-skills	Agent skill files
common	github-actions-workflow	GitHub Actions workflows
common	instructions	Instruction files
common	markdown	Markdown files
go	go	`*/.go`
terraform	terraform	`*/.tf`, `*/.tfvars`, `*/.hcl`
shell-script	shell-script	`*/.sh`
shell-script	bats	`*/.bats`

Scope¶

.apm/packages/: all package bundles and their sub-components
apm.yml and apm.lock.yaml: package metadata and lock state

Lint Configs¶

This repository provides shared lint configuration files for consumer projects. These files are not distributed via APM (which handles agent-specific assets only) but via install scripts.

Install Scripts¶

Script	Target	Distributed Files
`install_go.sh`	Go projects	`.pre-commit-config.yaml`, `.golangci.yaml`, `.markdownlint-cli2.yaml`, `.gitleaks.toml`, `.commitlintrc.yaml`, `trivy.yaml`
`install_terraform.sh`	Terraform projects	`.pre-commit-config.yaml`, `.tflint.hcl`, `.markdownlint-cli2.yaml`, `.gitleaks.toml`, `.commitlintrc.yaml`, `trivy.yaml`

Pre-commit Config Variants¶

File	Description
`.pre-commit-config.yaml`	Base config used by this repository (Terraform hooks commented out)
`.pre-commit-config-go.yaml`	Go projects: golangci-lint active, commitlint active
`.pre-commit-config-terraform.yaml`	Terraform projects: terraform_fmt, terraform_tflint, terraform_trivy active

Behavior¶

Install scripts download files from this repository's main branch
Existing files are not overwritten unless --force is passed
Scripts require curl and an internet connection
After installation, projects run pre-commit install to activate hooks

Scope¶

install_go.sh, install_terraform.sh: install scripts at repository root
.pre-commit-config-go.yaml, .pre-commit-config-terraform.yaml: pre-commit config variants
.golangci.yaml, .tflint.hcl, trivy.yaml, .markdownlint-cli2.yaml, .gitleaks.toml, .commitlintrc.yaml: shared lint configs

GitHub Actions¶

This repository shares reusable GitHub Actions workflow definitions.

Reusable Workflow Behavior¶

The repository must provide reusable workflows.

workflows intended for reuse are defined with workflow_call
caller workflows can reference reusable workflows within this repository
external repositories can consume reusable workflows via uses: <owner>/<repo>/.github/workflows/<workflow>.yaml@<ref>

Security CI Workflows¶

Workflow	Type	Purpose
`ci-security.yaml`	Reusable	Trivy fs scan + SARIF + CycloneDX SBOM + PR `dependency-review`
`ci-sast.yaml`	Reusable	CodeQL + Semgrep (language-agnostic SAST; keep `govulncheck` in `ci-go`)
`on-ci-security.yaml`	Caller	Daily cron + path-filtered push/PR for repository-wide security and SAST

Language CI workflows (ci-go, ci-nodejs, ci-aws-terraform, ci-terraform) retain language-specific checks (govulncheck, npm audit, Terraform fmt/validate/tflint). ci-terraform runs without AWS credentials; ci-aws-terraform adds remote state init/plan/apply. Trivy/SBOM/dependency-review/SAST are centralized in ci-security and ci-sast. Container image scanning runs in cd-aws-go-registry after ECR push (trivy_image_scan, default true). See CI Security Workflow Design.

APM and shell CI workflows¶

Workflow	Type	Purpose
`ci-apm-audit.yaml`	Reusable	`apm install` + `apm audit --ci` with optional `check_drift` input
`on-ci-push-apm-audit.yaml`	Caller	Path-filtered push/PR for APM package changes (dogfood: `check_drift: false`)
`ci-shell-script.yaml`	Reusable	shellcheck/shfmt + Bats/ShellSpec discovery when present

Scope¶

.github/workflows/: reusable workflows and caller workflows
.github/actions/: composite actions for shared step logic

Composite action composition¶

Loop composite actions must not nest other repository composite actions via uses: <owner>/<repo>/.github/actions/.... Parent composites invoke shared bash under .github/actions/lib/<domain>/ for cross-action libraries (for example ${GITHUB_ACTION_PATH}/../lib/loop/handoff.sh, redact.sh, failure_record.sh, export_failure_diag.sh) or sibling action lib/ for action-specific orchestration (for example ${GITHUB_ACTION_PATH}/../loop-install-cli/lib/install.sh). This keeps a single action SHA self-contained at release time without transitive pin drift. Failure diagnostics must redact before persistence — see .github/workflows/CLAUDE.md (Failure diagnostics).

Workflows (including on-loop-state-promote.yaml) must call leaf actions via uses: — never ${GITHUB_WORKSPACE}/.github/actions/.../lib/run.sh. Consumer repositories pin y-miyazaki/config/.github/actions/<name>@<ref>; this repository dogfoods with ./.github/actions/<name>.

Loop Engineering Workflows¶

Workflow	Type	Purpose
`ci-loop-agent.yaml`	Reusable	Engine-agnostic agent invocation (Claude / Copilot / Codex / Cursor). L1: `loop-agent-once`; L2/L3: worktree + bounded Agent→Verify via `loop-execute`
`on-loop-changelog.yaml`	Caller	Cron-driven CHANGELOG.md maintenance (detect → execute → finalize)
`on-loop-ci-sweeper.yaml`	Caller	Schedule-driven CI failure repair (detect → execute → finalize)
`on-loop-docs-updater.yaml`	Caller	Cron-driven documentation update (detect → execute → finalize)
`on-loop-refactor.yaml`	Caller	Cron-driven structural refactor (detect → execute → finalize)
`on-loop-tech-debt.yaml`	Caller	Weekly technical debt report (detect → execute → finalize)
`on-loop-state-promote.yaml`	Platform	Merge-gated `pending` → `last_sha` promotion when a `loop-automation` fix PR closes

Loop Skill Package Pattern¶

Loop entry skills are domain skills (no loop- name prefix) split by forge: repo-maintenance (docs-updater, ci-sweeper, changelog, tech-debt, refactor) and github (github-issue-triage, github-issue-autofix, github-pr-revise). Generic checker: loop / loop-verifier. Callers set agent_maker_skill_name (maker), agent_checker_skill_name (checker; default loop-verifier), and detect_script to installed paths (.agents/skills/<name>/... after apm install). Family map: Loop-Capable Skills.

Artifact	Location	Role
Skill	`.apm/skills/<name>/SKILL.md`	Maker behavior, classification, allowed paths
Detect script	`.apm/skills/<name>/scripts/detect_*.sh`	Per-target scan in branch context set by `loop-detect`
Persistence script (optional)	`.apm/skills/<name>/scripts/*_ledger.sh`	Domain ledger via `loop-finalize` `domain_persistence_script`

Loop Engineering Actions¶

Action	Purpose
`loop-agent-once`	Single read-only agent session (L1); accepts `node_version` / `uv_version` and enables workspace MCP via `lib/mcp.sh`
`loop-detect`	Read `LOOP_`, enumerate branches/PRs, checkout per context, read per-target state (`lib/state.sh`), invoke `detect_script` per context, assemble candidates and maker prompts (`lib/loop/build_constraints.sh`), write loop-handoff* artifact, output slim `target_matrix`; guards (`budget`, circuit breaker). No caller re-run of detect script
`loop-execute`	Bounded Agent→Verify loop (L2/L3); inputs include `target_json`, `verifier_context`, `node_version`, `uv_version`; enables workspace MCP via `lib/mcp.sh`; worktree from `from.ref` @ `from.branch`; outputs include `failure_stage` / `failure_message` on push/notify failures
`loop-finalize`	Finalize per `target.finalize`, branch cleanup, per-target state write (`lib/write_state.sh`, `lib/prune_targets.sh`), optional `domain_persistence_script`; `.loop/*` to `LOOP_STATE_PUSH_BRANCH`; outputs include `failure_stage` / `failure_message` when finalize PR steps fail
`loop-notify-pr`	Post or update marker PR comment after finalize on `pull_request` targets (sibling step in `ci-loop-agent`, not nested in `loop-finalize`). Platform-owned Layers 1–2; optional skill appendix. See loop-notify-pr Specification
`loop-install-cli`	Install and cache the selected engine CLI; accepts `node_version` / `uv_version` so MCP servers can resolve via `npx` / `uvx`
`loop-run-log`	Append one JSONL entry to `.loop/loop-run-log.md` (optional `failure_stage` / `failure_message`), prune entries older than 30 days (sibling step in `ci-loop-agent` after `loop-finalize`, or `record-skip` in callers)
`loop-state-promote`	Promote or clear `pending` loop state after a fix PR closes (`pull_request` `closed` handler). Prefer direct push; auto-merge state PR when push is blocked (`skip_state_pr` opts out).
`loop-worktree-setup`	Isolated worktree at `base_ref` on `base_branch` + agent branch (L2/L3)

Loop agent MCP enablement¶

loop-agent-once, loop-execute, and loop-install-cli accept node_version and uv_version so workspace MCP servers can resolve via npx / uvx during CI agent runs (keep aligned with mise.toml Node and uv pins).

loop-execute / loop-agent-once source .github/actions/loop-execute/lib/mcp.sh to:

Prefer the MCP manifest at .mcp.json, then .cursor/mcp.json, then .github/mcp.json
Pass engine-specific non-interactive MCP approval flags (Claude project MCP settings, Copilot --allow-all-tools, Cursor --approve-mcps)
For Codex, materialize an isolated CODEX_HOME/config.toml from the shared manifest (Codex does not read project .mcp.json automatically)

Detect script output (per context)¶

Invoked by loop-detect per scan context (not by the caller). Scans the branch/ref that loop-detect checked out.

Field	Required	Description
`skip`	yes	`true` when this context has no actionable work
`result`	when actionable	Domain JSON (facts). Semantic `findings[]` are produced by the Skill
`verifier_context`	no	Markdown for checker (may be empty)

loop-detect assembles each candidate (target_json, result, prompt, verifier_context), applies priority/cap, uploads a loop-handoff artifact bundle, and outputs a slim target_matrix (JSON array) for matrix fan-out.

Job handoff (`loop-handoff` artifact)¶

GitHub Actions job outputs are capped at 1MB. Large per-target payloads (result, verifier_context) are not inlined in target_matrix.

Stage	Mechanism
detect	`loop-detect` writes `loop-handoff-<run_id>` artifact (`manifest.json` + `payloads/<sanitized-key>.json`); uploads via `actions/upload-artifact`
execute	`ci-loop-agent` downloads the artifact; `loop-execute` / `loop-finalize` resolve payloads by `handoff_key` (`target_json.key`)

Slim matrix candidate (job output):

Field	In `target_matrix`	Notes
`target_json`	yes	Execute/finalize target contract
`prompt`	yes	Compact prompt (`__LOOP_DETECT_RESULT_JSON__` marker when result large)
`handoff_key`	yes	Same as `target_json.key`; lookup into artifact bundle
`verifier_context`	empty string	Loaded from artifact at execute time
`result`	omitted	Loaded from artifact at execute time

Full candidate payloads remain in the artifact until execute/finalize read them. Inline detect_result_json on execute is supported for backward compatibility; callers pass "{}" and rely on the artifact.

Execute failure contract: When HANDOFF_KEY and LOOP_HANDOFF_DIR are set (artifact path) and inline DETECT_RESULT_JSON is empty or {}, execute must resolve a valid payload from the artifact. Missing or invalid payloads are fail-fast (::error:: + non-zero exit). Non-empty inline detect_result_json remains supported for backward compatibility.

Legacy outputs: loop-detect also writes backward-compatible single-target outputs (prompt, last_sha, etc.) from the full candidate matrix (including inlined result). Legacy consumers may hit the 1MB job-output cap when payloads are large; prefer artifact + slim target_matrix.

Library: .github/actions/lib/loop/handoff.sh (LOOP_HANDOFF_VERSION=1).

`target_json` contract¶

Execute/finalize input. Schema: Multi-Branch Loops Design.

Field	Required	Description
`mode`	yes	`integration` \| `pull_request`
`key`	yes	State key
`from.branch`, `from.ref`	yes	Worktree checkout
`to.branch`	yes	Finalize destination
`to.pr_number`	pull_request	PR to notify after `push_head`
`base.branch`	pull_request	Checker diff baseline
`finalize`	yes	`open_pr` \| `push` \| `push_head`
`workflow_run_id`	optional	CI loops

`loop-detect` outputs (caller detect job)¶

Output	When
`should_run`	`target_matrix` non-empty after guards
`skip_reason`	`none` \| `no_changes` \| `circuit_breaker` \| `budget` \| `target_budget` \| `config_error` \| `pending_pr`
`handoff_artifact_name`	`loop-handoff-<run_id>` when `should_run=true`; empty otherwise
`target_matrix`	Slim JSON array of candidates for matrix fan-out (see Job handoff)

skip_reason priority (when should_run=false): circuit_breaker > pending_pr > no_changes. Other values apply at earlier gates (config_error, budget).

target_budget semantics: Set when fan-out cap (LOOP_MAX_TARGETS_PER_SCHEDULE) trims candidates but should_run remains true. Informational deferral only — not a skip. record-skip records budget and circuit_breaker only (not target_budget).

`loop-execute` outputs (L2/L3 additions)¶

Output	Required	Description
`notify_context_json`	yes	Machine fix context for `loop-notify-pr`. See loop-notify-pr Specification
`failure_stage`	no	Platform failure stage when push/notify fails (empty on success); shared via `lib/loop/failure_record.sh`
`failure_message`	no	Redacted/truncated failure text for run-log diagnostics (empty on success)

loop-finalize likewise outputs failure_stage / failure_message when finalize PR steps fail. ci-loop-agent merges execute and finalize diagnostics into loop-run-log inputs.

`loop-finalize` inputs (additions)¶

Input	Required	Description
`target_json`	yes	Matrix cell target
`domain_persistence_script`	no	Optional bash script (ledger). Standard env: `TARGET_JSON`, `OUTCOME`, `VERDICT`, `LOOP_NAME`, `STATE_FILE`, `EXECUTE_BRANCH`
`state_push_branch`	no	Default: repository default branch

loop-notify-pr is invoked by ci-loop-agent as a sibling step after loop-finalize when target_json.to.pr_number is set. loop-run-log is invoked as a sibling step after loop-finalize in the same finalize job (loop_name is required on ci-loop-agent). Both read outputs from prior steps (not via nested composite uses:).

State `targets` map¶

Flat top-level last_sha is removed. Migration: on first read, copy legacy last_sha into targets["integration:<default_branch>"]; subsequent writes use targets only.

Outcome enum¶

Outcome	Meaning	`consecutive_failures`
`pr-created`	Fix PR or `push_head` succeeded	Reset to 0
`rejected`	Actionable; checker REJECT or no-change REJECT	Increment
`no-op`	No actionable detect result	Reset to 0
`watch`	Present; Skill Watch (no code edit)	No increment
`error`	Execute failed	Unchanged

Renovate¶

This repository shares centrally managed Renovate policy presets.

Shared Policy Behavior¶

The repository must provide centrally managed Renovate defaults.

shared policy baseline is defined in renovate/default.json
APM MCP package version updates are defined in renovate/apm-mcp-version.json
workflow tool-version updates are defined in renovate/github-actions-tool-version.json
pre-commit hook version updates are defined in renovate/pre-commit-config-tool-version.json
consumers can extend the baseline via .github/renovate.json

Scope¶

renovate/default.json: baseline policy
renovate/apm-mcp-version.json: APM MCP package version update rules
renovate/github-actions-tool-version.json: workflow tool-version update rules
renovate/pre-commit-config-tool-version.json: pre-commit hook rev update rules
renovate/README.md: policy details and operational notes

Configuration Defaults¶

Parameter	Default	Notes
`target` in root `apm.yml`	`copilot`	Default deployment target for APM install
`target` in sub-packages	`all`	Sub-packages target all supported environments
`includes` in `apm.yml`	`auto`	Automatic include behavior for package composition
Renovate minimum release age	`7 days`	Global baseline in shared Renovate policy

Testing and Validation¶

Use repository validation workflows and scripts for changed assets:

Markdown checks for documentation changes
GitHub Actions workflow checks for workflow changes
domain-specific checks for Go, shell script, and Terraform assets

Validation and Safety Checks¶

apm install --frozen: verify deterministic package resolution
ci-apm-audit workflow: install APM packages and run apm audit --ci with optional check_drift and policy checks
Markdown lint CI workflow: validate documentation formatting
GitHub Actions workflow validation: check reusable workflow syntax
Renovate config validation: verify shared policy JSON schema compliance
Domain-specific checks: Shell (shellcheck)

Troubleshooting¶

If APM install results differ across environments, verify apm.lock.yaml is committed and up to date.
If reusable workflows fail to resolve, verify repository visibility and workflow reference format.
If Renovate behavior differs from expectation, verify extends and rule precedence against renovate/default.json.

Config Repository Functional Specification¶

Scope¶

Overview¶

Prerequisites¶

Repository Structure¶

Root-Level Components¶

APM-Related Components¶

Validation and Utility Components¶

APM¶

Package Architecture¶

Distribution Behavior¶

Configuration Philosophy¶

Layer Summary¶

Consumer Setup Tiers¶

MCP — Runtime Resolution¶

Hooks — Optional Enforcement¶

Skills — Explicit Validation¶

MCP Servers¶

Hooks¶

Hooks Limitations¶

Skills¶

Instructions¶

Scope¶

Lint Configs¶

Install Scripts¶

Pre-commit Config Variants¶

Behavior¶

Scope¶

GitHub Actions¶

Reusable Workflow Behavior¶

Security CI Workflows¶

APM and shell CI workflows¶

Scope¶

Composite action composition¶

Loop Engineering Workflows¶

Loop Skill Package Pattern¶

Loop Engineering Actions¶

Loop agent MCP enablement¶

Detect script output (per context)¶

Job handoff (loop-handoff artifact)¶

target_json contract¶

loop-detect outputs (caller detect job)¶

loop-execute outputs (L2/L3 additions)¶

loop-finalize inputs (additions)¶

State targets map¶

Outcome enum¶

Renovate¶

Shared Policy Behavior¶

Scope¶

Configuration Defaults¶

Testing and Validation¶

Validation and Safety Checks¶

Troubleshooting¶

Job handoff (`loop-handoff` artifact)¶

`target_json` contract¶

`loop-detect` outputs (caller detect job)¶

`loop-execute` outputs (L2/L3 additions)¶

`loop-finalize` inputs (additions)¶

State `targets` map¶