agent-control-plane 0.3.0 → 0.6.0

package/tools/templates/pr-fix-template.md

@@ -11,6 +11,7 @@ PR metadata:
 - PR: {PR_NUMBER} - {PR_TITLE}
 - URL: {PR_URL}
 - Base branch: {PR_BASE_REF}
+- Base tracking ref: {PR_BASE_TRACKING_REF}
 - Head branch: {PR_HEAD_REF}
 - Linked issue: {PR_LINKED_ISSUE_ID}
 - Risk classification: {PR_RISK}
@@ -55,7 +56,7 @@ Required flow:
 
 1. Inspect the current diff and the failing/pending CI signals first:
    - `openspec list` if the repo uses OpenSpec
-   - `git diff --stat origin/main...HEAD`
+   - `git diff --stat {PR_BASE_TRACKING_REF}...HEAD`
    - `git status --short`
    - if `Merge state` is not `CLEAN` or `Mergeable` is `FALSE`, treat branch drift/conflicts as the concrete blocker first
    - if `Actionable current-head review findings` is not `- none`, treat those findings as the concrete blockers to address first
@@ -68,6 +69,7 @@ Required flow:
    - do not run `git fetch`, `git merge`, `git rebase`, `git commit`, `git push`, or other Git metadata-writing commands from inside this worker; host-side wrappers own those steps
 3. If the blocker is branch drift or a merge conflict, use the already-prepared local refs and make the smallest branch-local source update needed to restore mergeability on this PR branch. Keep the resolution scoped to the PR intent; do not rewrite unrelated code.
    - Treat `Current local merge-conflict paths` as the authoritative conflict list to clear.
+   - Treat `{PR_BASE_TRACKING_REF}` as the authoritative base ref for any read-only diff or merge-base inspection.
    - Do not stop after fixing only one file if other conflict paths remain.
    - Before you declare success, rerun local merge simulation and confirm there are no remaining conflict paths for this branch against `{PR_BASE_REF}`.
 4. Make the smallest change that fixes the concrete PR blockers on this existing branch.

package/tools/templates/pr-merge-repair-template.md

@@ -11,6 +11,7 @@ PR metadata:
 - PR: {PR_NUMBER} - {PR_TITLE}
 - URL: {PR_URL}
 - Base branch: {PR_BASE_REF}
+- Base tracking ref: {PR_BASE_TRACKING_REF}
 - Head branch: {PR_HEAD_REF}
 - Linked issue: {PR_LINKED_ISSUE_ID}
 - Risk classification: {PR_RISK}
@@ -43,7 +44,7 @@ PR body:
 Required flow:
 
 1. Treat this worktree as an already-prepared merge repair state from host control-plane.
-   - `origin/{PR_BASE_REF}` has already been merged into this worktree locally.
+   - `{PR_BASE_TRACKING_REF}` has already been merged into this worktree locally.
    - if `Current unresolved merge-conflict paths` is not `- none detected after host merge preparation`, resolve those files first.
 2. Never run Git control commands from inside the worker:
    - do not run `git fetch`, `git pull`, `git merge`, `git rebase`, `git commit`, `git push`, or any command that writes Git metadata

package/references/architecture.md

@@ -1,217 +0,0 @@
-# Architecture Guide
-
-This document explains how `agent-control-plane` is put together as an
-operator-facing system, not just a collection of scripts.
-
-ACP has five practical layers:
-
-1. package entrypoint and staging
-2. profile installation and publication
-3. runtime supervision and heartbeat scheduling
-4. worker execution and reconcile
-5. dashboard and operator visibility
-
-If you are reading the repo for the first time, start with the system overview
-diagram below, then jump to the flow you care about most.
-
-## System Overview
-
-```mermaid
-flowchart LR
-  User[Operator] --> CLI["npm/bin/agent-control-plane.js"]
-
-  CLI --> Init["project-init.sh"]
-  CLI --> Sync["sync-shared-agent-home.sh"]
-  CLI --> RuntimeCtl["project-runtimectl.sh"]
-  CLI --> DashboardCmd["serve-dashboard.sh"]
-
-  Init --> Profiles["Profile registry\n~/.agent-runtime/control-plane/profiles/<id>"]
-  Sync --> RuntimeHome["Runtime home\n~/.agent-runtime/runtime-home"]
-
-  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
-  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
-  Bootstrap --> Heartbeat["heartbeat-safe-auto.sh"]
-  Heartbeat --> Scheduler["agent-project-heartbeat-loop"]
-
-  Scheduler --> IssueWorkers["start-issue-worker.sh"]
-  Scheduler --> PRWorkers["start-pr-review-worker.sh\nstart-pr-fix-worker.sh\nstart-pr-merge-repair-worker.sh"]
-  IssueWorkers --> Router["run-codex-task.sh"]
-  PRWorkers --> Router
-
-  Router --> Codex["agent-project-run-codex-session"]
-  Router --> Claude["agent-project-run-claude-session"]
-  Router --> OpenClaw["agent-project-run-openclaw-session"]
-  Router --> Ollama["agent-project-run-ollama-session"]
-  Router --> Pi["agent-project-run-pi-session"]
-  Router --> OpenCode["agent-project-run-opencode-session"]
-  Router --> Kilo["agent-project-run-kilo-session"]
-
-  Codex --> Artifacts["run.env / runner.env /\nresult.env / verification.jsonl"]
-  Claude --> Artifacts
-  OpenClaw --> Artifacts
-  Ollama --> Artifacts
-  Pi --> Artifacts
-  OpenCode --> Artifacts
-  Kilo --> Artifacts
-
-  Artifacts --> Reconcile["reconcile-issue-worker.sh\nreconcile-pr-worker.sh"]
-  Reconcile --> GitHub["GitHub issues / PRs / labels / comments"]
-  Reconcile --> History["runs/ + history/ + state/"]
-
-  DashboardCmd --> Snapshot["dashboard_snapshot.py"]
-  Snapshot --> Profiles
-  Snapshot --> History
-  Snapshot --> Browser["Local dashboard browser"]
-```
-
-The important architectural choice is that ACP separates:
-
-- package distribution from runtime execution
-- shared engine logic from per-profile config
-- worker execution from reconcile and GitHub side effects
-- operator visibility from the worker CLIs themselves
-
-## Install and Publication Flow
-
-This is the path from `npx agent-control-plane ...` to a usable runtime on disk.
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant CLI as agent-control-plane.js
-  participant Stage as staged shared-home
-  participant Init as project-init.sh
-  participant Scaffold as scaffold-profile.sh
-  participant Smoke as profile-smoke.sh
-  participant Adopt as profile-adopt.sh
-  participant Sync as sync-shared-agent-home.sh
-
-  User->>CLI: npx agent-control-plane init ...
-  CLI->>Stage: copy packaged skill into temp shared-home
-  CLI->>Init: forward command with staged env
-  Init->>Scaffold: write control-plane.yaml + profile docs
-  Init->>Smoke: validate profile contract
-  Init->>Adopt: create runtime roots / sync anchor repo / workspace
-  Init->>Sync: publish shared runtime into ~/.agent-runtime/runtime-home
-```
-
-Why this split exists:
-
-- the npm package is treated as a distribution artifact
-- the real runtime is copied into `~/.agent-runtime/runtime-home`
-- installed profiles live outside the package in
-  `~/.agent-runtime/control-plane/profiles/<id>`
-- upgrades are therefore explicit and repeatable instead of depending on a temp
-  `npx` cache directory
-
-## Runtime Scheduler Loop
-
-This is the heartbeat path ACP follows after `runtime start`.
-
-```mermaid
-flowchart TD
-  Start["runtime start"] --> RuntimeCtl["project-runtimectl.sh"]
-  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
-  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
-  Bootstrap --> SyncCheck["sync runtime copy if needed"]
-  SyncCheck --> Heartbeat["heartbeat-safe-auto.sh"]
-  Heartbeat --> Preflight["locks / quota preflight /\nretained-worktree audit"]
-  Preflight --> SharedLoop["agent-project-heartbeat-loop"]
-
-  SharedLoop --> ReconcileCompleted["reconcile completed sessions"]
-  SharedLoop --> Capacity["compute capacity / cooldown / pending launches"]
-  SharedLoop --> Workflows["select workflow lane from issue + PR state"]
-
-  Workflows --> IssueImplementation["issue implementation"]
-  Workflows --> IssueScheduled["scheduled issue checks"]
-  Workflows --> IssueRecovery["blocked recovery"]
-  Workflows --> PRReview["PR review"]
-  Workflows --> PRFix["PR fix"]
-  Workflows --> PRMergeRepair["merge repair"]
-```
-
-Key detail: the shared scheduler owns the control logic around workers:
-
-- concurrency and heavy-worker limits
-- cooldown and retry gating
-- resident recurring and scheduled issue lanes
-- launch ordering
-- summary output and queue visibility
-
-That is why workers do not need to be "smart" about the entire system. The
-workflow around them carries a lot of the operational burden.
-
-## Worker Session Lifecycle
-
-This is the path from one chosen issue or PR to a reconciled outcome.
-
-```mermaid
-flowchart LR
-  Pick["heartbeat selects issue or PR"] --> Launch["start-issue-worker.sh\nor start-pr-*.sh"]
-  Launch --> Worktree["open or reuse managed worktree"]
-  Worktree --> Prompt["render prompt + context files"]
-  Prompt --> Route["run-codex-task.sh"]
-
-  Route --> Backend["Codex / Claude / OpenClaw adapter"]
-  Backend --> Session["backend session wrapper"]
-  Session --> Output["result.env / comments /\nverification.jsonl / runner.env"]
-
-  Output --> Reconcile["agent-project-reconcile-issue-session\nor agent-project-reconcile-pr-session"]
-  Reconcile --> Labels["update labels / retry state /\nresident metadata / cooldown"]
-  Reconcile --> Publish["comment on issue, open PR,\nor leave blocked report"]
-  Reconcile --> Archive["archive run into history root"]
-```
-
-The contract here is deliberate:
-
-- worker backends focus on producing work and result artifacts
-- reconcile scripts own the final interpretation and GitHub-facing outcome
-- resident metadata and history are updated by the host workflow, not by the
-  worker trying to infer the entire system state
-
-## Dashboard Snapshot Pipeline
-
-The dashboard is a read-only window into ACP state. It does not own scheduling.
-
-```mermaid
-flowchart LR
-  Browser["browser"] --> Server["tools/dashboard/server.py"]
-  Server --> API["GET /api/snapshot.json"]
-  API --> Snapshot["dashboard_snapshot.py"]
-
-  Snapshot --> Registry["profile registry"]
-  Snapshot --> Config["render-flow-config.sh"]
-  Snapshot --> WorkerStatus["agent-project-worker-status"]
-  Snapshot --> Runs["runs/ history/ state/"]
-
-  Registry --> JSON["snapshot payload"]
-  Config --> JSON
-  WorkerStatus --> JSON
-  Runs --> JSON
-
-  JSON --> UI["dashboard app.js + index.html"]
-```
-
-This means the dashboard reflects the current state of:
-
-- installed profiles
-- live and recent runs
-- resident controller metadata
-- provider cooldowns
-- scheduled issue state
-- runtime process status
-
-without introducing a second control path that could drift away from the real
-scheduler state.
-
-## Reading Order
-
-If you want the shortest path through the architecture:
-
-1. [System Overview](#system-overview)
-2. [Runtime Scheduler Loop](#runtime-scheduler-loop)
-3. [Worker Session Lifecycle](#worker-session-lifecycle)
-4. [Dashboard Snapshot Pipeline](#dashboard-snapshot-pipeline)
-
-If you are changing packaging or onboarding, also read
-[Install and Publication Flow](#install-and-publication-flow).

package/references/commands.md

@@ -1,128 +0,0 @@
-# Command Map
-
-Run commands from the current isolated checkout for the task.
-
-Profile-specific repo roots and repo-local dev/test commands belong in
-`~/.agent-runtime/control-plane/profiles/<id>/README.md`. Resolve the active
-profile first, then use the selected profile's notes for product-repo commands.
-
-## Profile Resolution
-
-```bash
-bash tools/bin/workflow-catalog.sh profiles
-tools/bin/workflow-catalog.sh context
-bash tools/bin/profile-activate.sh --profile-id <id>
-ACP_PROJECT_ID=<id> bash tools/bin/render-flow-config.sh
-```
-
-Use `render-flow-config.sh` when you need the effective repo root, worktree
-root, runtime root, worker backend, or profile-specific script bindings.
-When multiple available profiles exist, set `ACP_PROJECT_ID=<id>` first or use
-`profile-activate.sh --profile-id <id>` before running manual operator
-commands.
-
-## Dependency bootstrap
-
-Run dependency bootstrap only from the clean automation baseline for the
-selected profile when you explicitly need to refresh shared dependencies. Do not
-repair shared `node_modules` from inside a worker worktree.
-
-For control-plane changes in this repo, prefer focused shell tests over broad
-bootstrap unless the task actually changes dependency behavior.
-
-## Control-Plane Verification
-
-```bash
-bash tools/bin/check-skill-contracts.sh
-bash tools/bin/flow-runtime-doctor.sh
-bash tools/bin/profile-smoke.sh
-bash tools/bin/test-smoke.sh
-bash tools/tests/test-project-init.sh
-bash tools/tests/test-project-init-force-and-skip-sync.sh
-bash tools/tests/test-project-remove.sh
-bash tools/tests/test-project-runtimectl.sh
-bash tools/tests/test-project-runtimectl-missing-profile.sh
-bash tools/tests/test-project-runtimectl-stop-cancels-pending-kick.sh
-bash tools/tests/test-project-runtimectl-start-falls-back-to-bootstrap.sh
-bash tools/tests/test-project-runtimectl-status-supervisor-running.sh
-bash tools/tests/test-project-launchd-bootstrap.sh
-bash tools/tests/test-install-project-launchd.sh
-bash tools/tests/test-uninstall-project-launchd.sh
-bash tools/tests/test-project-runtimectl-launchd.sh
-bash tools/tests/test-dashboard-launchd-bootstrap.sh
-bash tools/tests/test-install-dashboard-launchd.sh
-bash tools/tests/test-render-dashboard-snapshot.sh
-bash tools/tests/test-serve-dashboard.sh
-bash tools/tests/test-control-plane-dashboard-runtime-smoke.sh
-bash tools/tests/test-workflow-catalog.sh
-bash tools/tests/test-render-flow-config.sh
-```
-
-Add or run targeted tests in `tools/tests/` for the changed surface.
-
-## Flow maintenance
-
-```bash
-tools/bin/flow-runtime-doctor.sh
-tools/bin/workflow-catalog.sh list
-tools/bin/workflow-catalog.sh show pr-review
-tools/bin/workflow-catalog.sh profiles
-tools/bin/workflow-catalog.sh context
-tools/bin/profile-activate.sh --profile-id <id>
-tools/bin/project-init.sh --profile-id <id> --repo-slug <owner/repo>
-tools/bin/render-flow-config.sh
-tools/bin/scaffold-profile.sh --profile-id <id> --repo-slug <owner/repo>
-tools/bin/profile-smoke.sh
-tools/bin/test-smoke.sh
-tools/bin/profile-adopt.sh --profile-id <id>
-tools/bin/project-runtimectl.sh status --profile-id <id>
-tools/bin/project-runtimectl.sh sync --profile-id <id>
-tools/bin/project-runtimectl.sh stop --profile-id <id>
-tools/bin/project-runtimectl.sh start --profile-id <id>
-tools/bin/project-runtimectl.sh restart --profile-id <id>
-tools/bin/install-project-launchd.sh --profile-id <id>
-tools/bin/uninstall-project-launchd.sh --profile-id <id>
-tools/bin/project-remove.sh --profile-id <id>
-tools/bin/project-remove.sh --profile-id <id> --purge-paths
-tools/bin/sync-shared-agent-home.sh
-python3 tools/dashboard/dashboard_snapshot.py --pretty
-bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
-bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
-```
-
-Installed profile prompts should live under
-`~/.agent-runtime/control-plane/profiles/<id>/templates/`; generic fallback
-prompts live under `tools/templates/`.
-
-## Dashboard
-
-```bash
-python3 tools/dashboard/dashboard_snapshot.py --pretty
-bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
-bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
-```
-
-Use the snapshot command for CLI/debug output and the HTTP server for the live
-dashboard at `http://127.0.0.1:8765`. Use the LaunchAgent installer when you
-want the dashboard to come back automatically after macOS restart/login.
-
-## Project Autostart
-
-```bash
-bash tools/bin/install-project-launchd.sh --profile-id <id>
-bash tools/bin/uninstall-project-launchd.sh --profile-id <id>
-```
-
-Use the project installer when one profile should come back automatically after
-macOS restart/login. `project-runtimectl.sh start|stop|status` will detect that
-per-project LaunchAgent automatically once it is installed.
-
-## Repo-Specific Commands
-
-After choosing a profile, read `~/.agent-runtime/control-plane/profiles/<id>/README.md` for:
-
-- clean automation baseline and retained checkout roots
-- repo-local startup docs such as `AGENTS.md` and OpenSpec paths
-- app/package-specific dev commands
-- isolated smoke and release-rehearsal commands
-- project-specific operator runbooks

package/references/control-plane-map.md

@@ -1,124 +0,0 @@
-# Agent Control Plane Map
-
-This repository is the shared `agent-control-plane` package. It provides a
-generic engine that can host multiple installed profiles, each with its own repo
-roots, labels, worker preferences, prompts, and project-specific guardrails.
-
-## What Lives Here
-
-- `SKILL.md`
-  Canonical operating manual for the shared control plane.
-- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
-  Canonical installed project profile for repo paths, queue labels, limits,
-  and script bindings.
-- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-  Repo-specific operator notes, startup docs, and command references for the
-  selected profile.
-- `~/.agent-runtime/control-plane/profiles/<id>/templates/`
-  Optional installed profile-specific prompt overrides.
-- `assets/workflow-catalog.json`
-  Declarative catalog of the workflow lanes this control plane exposes.
-- `bin/`
-  Queue, label, and risk logic shared by installed profiles.
-- `hooks/`
-  Heartbeat and reconcile hooks shared by installed profiles.
-- `tools/bin/flow-runtime-doctor.sh`
-  Reports whether the published source copy and runtime-home copy are in sync.
-- `tools/bin/workflow-catalog.sh`
-  Lists workflows, shows workflow details, or prints available profile ids.
-- `tools/bin/render-flow-config.sh`
-  Prints the effective operator/runtime config after environment overrides.
-- `tools/bin/run-codex-task.sh`
-  Routes the shared worker contract into the backend-specific session wrapper.
-- `tools/bin/agent-project-run-codex-session`
-  Launches Codex-backed worker sessions.
-- `tools/bin/agent-project-run-claude-session`
-  Launches Claude-backed worker sessions.
-- `tools/bin/agent-project-run-openclaw-session`
-  Launches OpenClaw-backed worker sessions.
-- `tools/bin/agent-project-run-ollama-session`
-  Launches Ollama-backed worker sessions with a Node.js agentic loop.
-- `tools/bin/agent-project-run-pi-session`
-  Launches Pi-backed worker sessions in `--print --no-session` mode.
-- `tools/bin/agent-project-run-opencode-session`
-  Launches Crush (formerly OpenCode) worker sessions via `crush run`.
-- `tools/bin/agent-project-run-kilo-session`
-  Launches Kilo Code worker sessions via `kilo run --auto --format json`.
-- `tools/bin/project-init.sh`
-  Runs scaffold + smoke + adopt + runtime sync for one installed profile.
-- `tools/bin/scaffold-profile.sh`
-  Scaffolds a new installed profile, profile notes, and prompt templates in the
-  local profile registry.
-- `tools/bin/project-runtimectl.sh`
-  Provides `status`, `start`, `stop`, and `restart` for one installed profile.
-- `tools/bin/project-launchd-bootstrap.sh`
-  Syncs the runtime copy and runs one profile-scoped heartbeat pass in a
-  launchd-safe foreground process for the runtime supervisor.
-- `tools/bin/install-project-launchd.sh`
-  Installs a per-user LaunchAgent for one installed profile so its runtime can
-  come back automatically after reboot/login.
-- `tools/bin/uninstall-project-launchd.sh`
-  Removes the per-project LaunchAgent wrapper and plist for one installed
-  profile.
-- `tools/bin/project-remove.sh`
-  Removes one installed profile plus ACP-owned runtime state, with optional
-  purge of ACP-managed repo/worktree/workspace paths.
-- `tools/bin/profile-smoke.sh`
-  Validates available profiles and catches session/branch prefix collisions
-  before scheduler use.
-- `tools/bin/test-smoke.sh`
-  Runs the main shared-package smoke gates in one operator-facing command.
-- `tools/dashboard/dashboard_snapshot.py`
-  Emits a JSON snapshot of active runs, resident controllers, cooldown state,
-  queue depth, and scheduled issues across installed profiles.
-- `tools/bin/serve-dashboard.sh`
-  Serves the live worker dashboard and `/api/snapshot.json` endpoint for local
-  browser-based monitoring.
-- `tools/bin/dashboard-launchd-bootstrap.sh`
-  Syncs the runtime copy and launches the dashboard server in a launchd-safe
-  foreground process.
-- `tools/bin/install-dashboard-launchd.sh`
-  Installs and bootstraps a per-user LaunchAgent so the dashboard returns after
-  reboot/login.
-- `tools/bin/profile-adopt.sh`
-  Creates runtime roots, installs the selected profile into the local profile
-  registry when needed, and syncs the anchor repo plus VS Code workspace for
-  live scheduler adoption.
-- `references/`
-  Control-plane docs, operator commands, and repository maps.
-
-## What Does Not Live Here
-
-- Repo-specific product code.
-- Local scheduler bootstrap and operator docs that belong to a particular
-  workstation. Those now live under:
-  `~/.agent-runtime/control-plane/workspace`
-
-## Vendored Runtime
-
-- Runtime engines are resolved from the current skill root first, then the
-  shared/runtime canonical copies when present, while active project profiles
-  are resolved from `~/.agent-runtime/control-plane/profiles/`.
-- Project-specific instructions should be loaded from the active profile's
-  `README.md` and templates instead of being hardcoded into the shared engine.
-
-## Published Artifacts
-
-- Source canonical package copy:
-  `$SHARED_AGENT_HOME/skills/openclaw/agent-control-plane`
-- Runtime canonical package copy:
-  `~/.agent-runtime/runtime-home/skills/openclaw/agent-control-plane`
-
-Published artifacts are rebuilt by `tools/bin/sync-shared-agent-home.sh` as
-concrete copied files, not symlink aliases. Canonical profile configs now live
-outside the repo in `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`.
-
-## Operational Rule
-
-When updating the control plane:
-
-1. Change the generic engine in this repo or the selected installed profile in the external registry.
-2. Keep workstation wrappers thin.
-3. Repair shared/runtime published copies with `tools/bin/sync-shared-agent-home.sh`.
-4. Prefer explicit profile docs and copied artifacts over hidden defaults and
-   symlink aliases.

package/references/docs-map.md

@@ -1,73 +0,0 @@
-# Docs Map
-
-Canonical documentation sources inside `agent-control-plane`:
-
-## Shared Control-Plane Docs
-
-- `SKILL.md`
-  Shared operating rules and startup sequence.
-- `README.md`
-  Public-facing install, usage, funding, contributing, and security entrypoint.
-- `CHANGELOG.md`
-  Public release history for the package and repository.
-- `ROADMAP.md`
-  Public product and backend-support roadmap, including current and planned
-  worker integrations.
-- `references/architecture.md`
-  Architecture walkthrough with system, runtime, worker, and dashboard diagrams.
-- `CONTRIBUTING.md`
-  Contributor workflow, legal model, and maintainer expectations.
-- `CLA.md`
-  Contributor license agreement used for incoming changes.
-- `CODE_OF_CONDUCT.md`
-  Community behavior and moderation expectations.
-- `SECURITY.md`
-  Security reporting path and disclosure expectations.
-- `references/control-plane-map.md`
-  Ownership map for profiles, scripts, publication copies, and operator tools.
-- `references/commands.md`
-  Control-plane operator commands and profile-management entrypoints.
-- `references/release-checklist.md`
-  Maintainer release checklist for public package publishing.
-- `.github/release-template.md`
-  Reusable markdown template for GitHub release notes.
-- `.github/workflows/ci.yml`
-  Public CI workflow used for the README status badge.
-- `.github/workflows/publish.yml`
-  Trusted npm publishing workflow used for tag-driven releases with provenance.
-- `references/repo-map.md`
-  Layout of the control-plane repository itself.
-
-## Profile-Scoped Docs
-
-- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
-  Canonical repo-specific startup docs, repo roots, command map, and
-  high-risk notes.
-- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
-  Canonical machine-readable installed profile config.
-- `~/.agent-runtime/control-plane/profiles/<id>/templates/*.md`
-  Canonical prompt overrides for issue, PR fix, PR review, or scheduled issue flows.
-
-## Runtime and Publication Docs
-
-- `tools/bin/flow-runtime-doctor.sh`
-  Sync health for source and runtime copies.
-- `tools/bin/profile-smoke.sh`
-  Installed-profile validation before scheduler use.
-- `tools/bin/profile-adopt.sh`
-  Local workstation adoption helper.
-- `tools/bin/sync-shared-agent-home.sh`
-  Publication repair for shared/runtime copies.
-- `tools/bin/render-dashboard-demo-media.sh`
-  Regenerates the README dashboard screenshot and animated walkthrough from a
-  real local demo fixture.
-- `tools/bin/render-architecture-infographics.sh`
-  Regenerates the architecture infographic PNGs and PDF deck from the local
-  HTML source in `tools/architecture/`.
-
-## Rule of Thumb
-
-If a piece of guidance is specific to one repo, keep it in
-`~/.agent-runtime/control-plane/profiles/<id>/README.md` or
-`~/.agent-runtime/control-plane/profiles/<id>/templates/` instead of the shared
-control-plane docs.

package/references/release-checklist.md

@@ -1,65 +0,0 @@
-# Release Checklist
-
-Maintainer checklist for shipping a new public package release of
-`agent-control-plane`.
-
-## Pre-Release
-
-- confirm `git status` is clean
-- confirm `package.json` version is intentional
-- review `CHANGELOG.md` and prepare release notes from
-  `.github/release-template.md`
-- review `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `CLA.md` for stale
-  links or policy text
-- if a public GitHub repo now exists, set or verify the `homepage`,
-  `repository`, and `bugs` URLs in `package.json`
-- make sure sponsor links still point to the intended maintainer identity
-- confirm the intended license is still `MIT`
-
-## Verification
-
-Run the core checks:
-
-```bash
-bash tools/tests/test-package-public-metadata.sh
-bash tools/tests/test-package-funding-metadata.sh
-bash tools/tests/test-contribution-docs.sh
-bash tools/tests/test-agent-control-plane-npm-cli.sh
-bash tools/bin/test-smoke.sh
-npm pack --dry-run
-```
-
-## Publish
-
-Recommended release flow uses npm trusted publishing from GitHub Actions, so you
-do not have to enter an OTP during every local publish.
-
-One-time setup:
-
-- configure `agent-control-plane` for npm trusted publishing from
-  `ducminhnguyen0319/agent-control-plane`
-- verify the publish workflow file is `.github/workflows/publish.yml`
-- keep npm package publishing policy on the stricter setting you want after
-  trusted publishing is working
-
-Per-release command flow:
-
-```bash
-npm version <patch|minor|major>
-git push origin main --follow-tags
-```
-
-Then:
-
-- watch `.github/workflows/publish.yml` for the npm publish run
-- create or update a GitHub release using `.github/release-template.md`
-- update `CHANGELOG.md` if the final shipped notes differ from the draft
-
-## Post-Release
-
-- verify `npx agent-control-plane@latest help` works from a clean shell
-- verify the npm package shows provenance for the new version
-- verify `npm fund` shows the expected sponsor link
-- verify the repo README, sponsor button, and package metadata all point to the
-  same maintainer identity
-- announce the release where relevant