ace-swarm 2.0.5 → 2.0.7

package/README.md

@@ -43,12 +43,29 @@ npx -y ace-swarm init --project "My Project"
 This writes:
 
 - `agent-state/*`
+- `.github/hooks/*.json`
 - `.agents/ACE/*` and `.agents/skills/*`
 - `tasks/*`
 - `scripts/ace/*`
 - `.vscode/mcp.json`
 - `.mcp-config/{codex.config.toml,vscode.mcp.json,claude_desktop_config.json,cursor.mcp.json,antigravity.mcp.json}`
 
+### VS Code Copilot Hooks (Preview)
+
+`ace init` / `ace turnkey` now scaffolds a VS Code Copilot hook layer for this workspace:
+
+- `.github/hooks/ace-copilot.json`
+- `scripts/ace/copilot-hook-dispatch.mjs`
+
+The hook policy is Copilot-focused and currently does four things:
+
+- injects ACE workspace context on `SessionStart` and `SubagentStart`
+- blocks destructive terminal commands in `PreToolUse`
+- requires confirmation before editing hook/config control-plane files
+- adds verification reminders after file mutations in `PostToolUse`
+
+VS Code loads `.github/hooks/*.json` by default, so no extra workspace setting is required for the default Copilot hook path.
+
 ### Turnkey with Ollama (Local Models)
 
 Bootstrap ACE + local model profile in one command:

package/assets/.agents/skills/landing-review-watcher/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: landing-review-watcher
+description:
+  Watch review, CI, and landing loops for a change and use when the user needs a durable merge-readiness procedure rather than a one-off PR check.
+---
+
+# Landing Review Watcher
+
+## Purpose
+
+Make code-review and landing work observable, repeatable, and operator-safe.
+This skill does not own the release decision itself; it owns the watch loop that turns "waiting on review/CI/merge" into a deterministic procedure with artifacts.
+
+## Canonical Use Cases
+
+1. A change is open for review and someone needs a stable loop for comments, CI state, and merge blockers.
+2. A release candidate is waiting to land and the team wants a written handoff-safe landing procedure.
+3. A long-running review thread needs explicit acknowledgement, blocker tracking, and final landing evidence.
+
+## Inputs
+
+- active branch / change identifier
+- review comments or requested changes
+- CI status / failing checks
+- merge policy constraints
+- rollout or release artifact pointers when applicable
+
+## Workflow
+
+1. Define the watch target:
+   branch, PR, merge queue item, or review thread.
+2. Capture the current state:
+   reviewers, open comments, requested changes, CI state, merge policy, and known blockers.
+3. Classify the loop:
+   `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, or `blocked`.
+4. Write or update `agent-state/LANDING_REVIEW_WATCH.md` with:
+   owner, blockers, next checks, evidence refs, and explicit exit criteria.
+5. On every cycle, acknowledge new review input explicitly:
+   accepted, rebutted, deferred, or blocked with reason.
+6. If CI fails, route the failure to the responsible owner and record the remediation checkpoint.
+7. If merge is safe, hand off to [$release-sentry](/Users/voy/Desktop/dev-ace/.agents/skills/release-sentry/SKILL.md) for the actual approve/hold decision.
+8. After landing, record the final result, landing timestamp, and rollback pointer if one exists.
+
+## Outputs
+
+- `agent-state/LANDING_REVIEW_WATCH.md`
+- updated evidence pointer in `agent-state/EVIDENCE_LOG.md`
+- optional release routing note to `release-sentry`
+
+## Validation
+
+- Verify every open reviewer/blocker has an owner or explicit waiting reason.
+- Verify CI state is current and tied to a specific run/check reference.
+- Verify landing state is one of:
+  `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, `blocked`, `landed`.
+- Verify the watch artifact names the next action instead of only summarizing history.
+
+## Compatibility
+
+- `SKILL.md` is the portable source of truth for this workflow.
+- The skill remains useful without provider-specific PR adapters; branch names, plain-text review notes, and CI summaries are enough.
+- Client overlays may add launch shortcuts, but must not redefine the watch-state model.
+
+## Failure Policy
+
+- Do not claim a change is ready to land if requested changes or failing CI remain unresolved.
+- Do not collapse review feedback into a vague summary; every new blocker or accepted fix must be acknowledged explicitly.
+- If the change cannot be tied to a concrete watch target, stop and create the target definition first.

package/assets/.agents/skills/problem-triage/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: problem-triage
+description: 
+  Classify a new request as one of: existing skill fits, existing skill needs patching, new skill warranted, missing tool or permission, or one-off task. Use when the user asks whether something should become a skill, how to route a skill-system request, or what the right next building block is.
+---
+
+# Problem Triage
+
+Use this skill before creating or patching ACE skills. Its job is to stop duplicate or premature skill creation by turning a vague request into a concrete route decision.
+
+## Canonical Use Cases
+
+1. A user asks whether a repeated workflow deserves a new skill.
+2. A request overlaps an existing skill, but the current skill may need metadata, structure, or validation fixes.
+3. The real blocker is missing tooling, permissions, or runtime setup rather than the absence of a skill.
+
+## Inputs
+
+- The raw user request or workflow description.
+- The current skill catalog, including discoverable workspace and package-default skills.
+- Any visible blockers such as missing MCP servers, approvals, credentials, or network access.
+
+## Workflow
+
+1. Read the request for reusable-workflow signals, patch signals, and blocker signals.
+2. Compare the request against existing skill names, descriptions, and headings.
+3. Classify the request into exactly one route:
+   - existing skill fits
+   - existing skill needs patching
+   - new skill warranted
+   - missing tool or permission
+   - one-off task
+4. Write `agent-state/PROBLEM_TRIAGE.md` with confidence, rationale, top matches, and next steps.
+
+## Outputs
+
+- `agent-state/PROBLEM_TRIAGE.md`
+- A route decision with confidence, rationale, and top skill matches
+- Suggested next steps for the next ACE module or skill-building pass
+
+## Validation
+
+- Run the `problem_triage` MCP tool with a known request and verify that it writes `agent-state/PROBLEM_TRIAGE.md`.
+- Verify that requests mentioning client overlays or portability do not require `agents/openai.yaml` to classify correctly.
+- Check that repeated-workflow requests route to either `existing skill needs patching` or `new skill warranted`, never silently to one-off when reusable signals are strong.
+
+## Compatibility
+
+- `SKILL.md` is the canonical portable source of truth.
+- Any files under `agents/` are optional client overlays only and must not redefine the core route semantics.
+- The skill should remain understandable and executable in Claude, Cursor, Codex, Antigravity, and similar environments even when no adapter file exists.
+
+## Failure Policy
+
+- If catalog evidence is weak or ambiguous, lower confidence and surface the ambiguity explicitly.
+- If a tool, permission, or credential blocker is present, route to `missing tool or permission` instead of recommending skill creation.
+- Do not create a new skill when an existing skill can be patched to cover the request.

package/assets/.agents/skills/problem-triage/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: "Problem Triage"
+short_description: "Classify whether a request fits, patches, or warrants a skill."
+default_prompt: "Use the problem-triage skill to classify this request and write agent-state/PROBLEM_TRIAGE.md."

package/assets/.agents/skills/skill-auditor/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: skill-auditor
+description: 
+  Audit discoverable ACE skills against the portable skill contract, validation expectations, and progressive-disclosure rules. Use when the user asks which skills are production-ready, what is missing from the skill catalog, or how to verify portability across Claude, Cursor, Codex, Antigravity, and similar clients.
+---
+
+# Skill Auditor
+
+Use this skill to inspect the current ACE skill catalog before a remediation pass, release gate, or new skill rollout. Its job is to turn vague quality concerns into a concrete audit report and prioritized backlog.
+
+## Canonical Use Cases
+
+1. A user asks which existing skills are not yet production-ready.
+2. The team needs a readiness rubric before hardening trigger metadata or validation canaries.
+3. A portability change lands and someone needs to verify that `SKILL.md` remains canonical while any client overlays stay optional.
+
+## Inputs
+
+- The discoverable skill catalog from workspace and package-default skills.
+- Each skill's `SKILL.md`, optional `agents/` overlays, and supporting `references/` directory if present.
+- The current readiness criteria for trigger descriptions, core sections, validation, and portability.
+
+## Workflow
+
+1. Enumerate the discoverable skills and inspect each portable skill contract.
+2. Check frontmatter, trigger-aware description quality, canonical use cases, inputs/workflow/outputs/failure sections, validation surface, portability notes, and progressive-disclosure discipline.
+3. Record per-skill findings as pass, warn, or fail, keeping optional adapter overlays as neutral inventory rather than required readiness.
+4. Write `agent-state/SKILL_AUDIT_REPORT.md` with summary counts, per-skill findings, and rollout backlog items.
+
+## Outputs
+
+- `agent-state/SKILL_AUDIT_REPORT.md`
+- Per-skill pass/warn/fail findings with concrete remediation notes
+- A rollout backlog for validation, portability, and progressive-disclosure gaps
+
+## Validation
+
+- Run the `skill_audit` MCP tool and verify that it writes `agent-state/SKILL_AUDIT_REPORT.md`.
+- Confirm that a skill missing required sections is flagged as `fail`.
+- Confirm that a skill with optional client overlays but no portability note is flagged as `warn`, not as a hard failure for missing `openai.yaml`.
+
+## Compatibility
+
+- `SKILL.md` is the canonical source of truth for the audit.
+- Files under `agents/` are optional overlays only and should be audited for parity, not treated as mandatory.
+- The audit must stay meaningful even if no client-specific adapters exist at all.
+
+## Failure Policy
+
+- If the catalog cannot be read, stop and surface the specific filesystem problem.
+- If a skill is ambiguous, lower confidence through `warn` findings instead of silently passing it.
+- Do not treat the absence of a specific client adapter file as a failure unless the portable contract itself depends on it.

package/assets/.github/hooks/ace-copilot.json

@@ -0,0 +1,68 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "PostToolUse": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "PreCompact": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "SubagentStart": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "SubagentStop": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "timeout": 10
+      }
+    ]
+  }
+}

package/assets/agent-state/ACE_WORKFLOW.md

@@ -0,0 +1,66 @@
+---
+ace_runtime_version: "1.0.0"
+runtime:
+  mode: "interactive"
+  profile_name: "default"
+workspace:
+  root: ".ace/workspaces"
+  retention: "delete"
+  hooks:
+    after_create: null
+    before_run: null
+    after_run: null
+    before_remove: null
+executor:
+  command: null
+  approval_policy: "on-request"
+  thread_sandbox: "workspace-write"
+  turn_sandbox_policy: null
+  max_turns: 6
+  turn_timeout_ms: 300000
+tools:
+  registry_path: "agent-state/runtime-tool-specs.json"
+tracker:
+  kind: "none"
+  config: {}
+observability:
+  http_enabled: false
+  http_port: null
+  vericify_bridge:
+    enabled: false
+    bridge_path: "agent-state/vericify/ace-bridge.json"
+    process_post_path: "agent-state/vericify/process-posts.json"
+---
+# ACE Runtime Prompt Template
+
+Operate under ACE runtime profile `{{runtime.profile_name}}` in `{{runtime.mode}}` mode.
+
+## Task
+{{task}}
+
+## Workspace
+- Managed root: `{{workspace.root}}`
+- Retention: `{{workspace.retention}}`
+
+## Executor
+- Command: `{{executor.command}}`
+- Approval policy: `{{executor.approval_policy}}`
+- Thread sandbox: `{{executor.thread_sandbox}}`
+- Max turns: `{{executor.max_turns}}`
+- Turn timeout ms: `{{executor.turn_timeout_ms}}`
+
+## Runtime Tools
+- Registry: `{{tools.registry_path}}`
+
+## Tracker
+- Kind: `{{tracker.kind}}`
+
+## Sidecars
+- Vericify bridge enabled: `{{observability.vericify_bridge.enabled}}`
+- Vericify bridge path: `{{observability.vericify_bridge.bridge_path}}`
+- Vericify process-post path: `{{observability.vericify_bridge.process_post_path}}`
+
+## Notes
+- Preserve ACE state artifacts as the durable source of truth.
+- Treat Vericify as an optional sidecar, not a required ACE runtime dependency.
+- Treat this template as additive execution guidance for future unattended flows.

package/assets/agent-state/INTERFACE_REGISTRY.md

@@ -6,6 +6,56 @@
 - `MODULES/schemas/STATUS_EVENT.schema.json`
 - `MODULES/schemas/ARTIFACT_MANIFEST.schema.json`
 - `MODULES/schemas/SWARM_HANDOFF.schema.json`
+- `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`
+- `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`
+- `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`
+- `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`
+- `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`
+- `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`
+- `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`
+
+## Runtime Contract
+
+- `ACE_WORKFLOW.md` is the canonical workspace runtime profile artifact.
+- Its YAML front matter must validate against `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`.
+- The markdown body after the closing front matter boundary is the active runtime prompt template.
+
+## Workspace Session Contract
+
+- `runtime-workspaces.json` is the canonical managed workspace/session registry.
+- It must validate against `MODULES/schemas/WORKSPACE_SESSION_REGISTRY.schema.json`.
+- Removal only applies to registry-backed managed workspace paths under the configured runtime root.
+
+## Runtime Tool Contract
+
+- `runtime-tool-specs.json` is the canonical runtime-configured external tool registry.
+- It must validate against `MODULES/schemas/RUNTIME_TOOL_SPEC_REGISTRY.schema.json`.
+- Unattended executor and direct runtime-tool execution must validate input/output payloads against the declared tool schemas.
+
+## Runtime Executor Contract
+
+- `runtime-executor-sessions.json` is the canonical unattended execution session registry.
+- It must validate against `MODULES/schemas/RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json`.
+- Session turns must record request/response paths, summaries, and tool-call outcomes without mutating existing HANDOFF or STATUS_EVENT schema versions.
+
+## Tracker Snapshot Contract
+
+- `tracker-snapshot.json` is the canonical normalized tracker snapshot artifact.
+- It must validate against `MODULES/schemas/TRACKER_SNAPSHOT.schema.json`.
+- Scheduler and future executor consumers must use normalized item/comment fields only; provider-specific detail belongs under `metadata`.
+
+## Vericify Sidecar Contract
+
+- `vericify/ace-bridge.json` is an optional sidecar bridge snapshot for Vericify-style read-model consumers.
+- It must validate against `MODULES/schemas/VERICIFY_BRIDGE_SNAPSHOT.schema.json`.
+- `vericify/process-posts.json` is an optional structured process-post log and must validate against `MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json`.
+- Vericify remains optional; ACE must not require the Vericify package to read or write these artifacts.
+
+## Public Surface Gate
+
+- `audit_public_surface` is the canonical TypeScript public-surface gate for MCP tools, resources, prompts, and registered event names.
+- `PUBLIC_SURFACE_REPORT.md` is the durable audit artifact written by that gate.
+- `MODULES/gates/gate-typescript-public-surface.json` is the executable gate manifest for CI or operator use.
 
 ## Provenance Contract
 

package/assets/agent-state/MODULES/gates/gate-typescript-public-surface.json

@@ -0,0 +1,7 @@
+{
+  "id": "gate-typescript-public-surface",
+  "type": "executable",
+  "invariant": "Exported MCP tools, resources, prompts, and public status events stay registered, described, schema-backed where required, and covered by the audit gate",
+  "command": "node --input-type=module -e \"import('./dist/public-surface.js').then(async (m) => { const result = await m.auditPublicSurface({ write_artifact: false }); if (!result.ok) { console.error(result.failures.join('\\n')); process.exit(1); } console.log(JSON.stringify(result.summary)); })\"",
+  "evidence_requirement": "PUBLIC_SURFACE_REPORT.md + passing public-surface audit"
+}

package/assets/agent-state/MODULES/registry.json

@@ -23,11 +23,19 @@
     "gate-autonomy",
     "gate-security",
     "gate-operability",
-    "gate-evaluation"
+    "gate-evaluation",
+    "gate-typescript-public-surface"
   ],
   "schemas": [
     "STATUS_EVENT.schema.json",
     "HANDOFF.schema.json",
-    "ARTIFACT_MANIFEST.schema.json"
+    "ARTIFACT_MANIFEST.schema.json",
+    "ACE_RUNTIME_PROFILE.schema.json",
+    "WORKSPACE_SESSION_REGISTRY.schema.json",
+    "RUNTIME_TOOL_SPEC_REGISTRY.schema.json",
+    "RUNTIME_EXECUTOR_SESSION_REGISTRY.schema.json",
+    "TRACKER_SNAPSHOT.schema.json",
+    "VERICIFY_BRIDGE_SNAPSHOT.schema.json",
+    "VERICIFY_PROCESS_POST_LOG.schema.json"
   ]
 }

package/assets/agent-state/MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "ace://schemas/runtime-profile/1.0.0",
+  "title": "ACE Runtime Profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "ace_runtime_version",
+    "runtime",
+    "workspace",
+    "executor",
+    "tracker",
+    "observability"
+  ],
+  "properties": {
+    "ace_runtime_version": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode",
+        "profile_name"
+      ],
+      "properties": {
+        "mode": {
+          "type": "string",
+          "enum": [
+            "interactive",
+            "unattended"
+          ]
+        },
+        "profile_name": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "root",
+        "retention",
+        "hooks"
+      ],
+      "properties": {
+        "root": {
+          "type": "string",
+          "minLength": 1
+        },
+        "retention": {
+          "type": "string",
+          "enum": [
+            "delete",
+            "archive"
+          ]
+        },
+        "hooks": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "after_create",
+            "before_run",
+            "after_run",
+            "before_remove"
+          ],
+          "properties": {
+            "after_create": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "before_run": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "after_run": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "before_remove": {
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          }
+        }
+      }
+    },
+    "executor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command",
+        "approval_policy",
+        "thread_sandbox",
+        "turn_sandbox_policy"
+      ],
+      "properties": {
+        "command": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "approval_policy": {
+          "type": [
+            "string",
+            "object"
+          ]
+        },
+        "thread_sandbox": {
+          "type": "string",
+          "minLength": 1
+        },
+        "turn_sandbox_policy": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "max_turns": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "turn_timeout_ms": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "tools": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "registry_path": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "tracker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "config"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "none",
+            "memory",
+            "external"
+          ]
+        },
+        "config": {
+          "type": "object"
+        }
+      }
+    },
+    "observability": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "http_enabled",
+        "http_port"
+      ],
+      "properties": {
+        "http_enabled": {
+          "type": "boolean"
+        },
+        "http_port": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "vericify_bridge": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": {
+              "type": "boolean"
+            },
+            "bridge_path": {
+              "type": "string",
+              "minLength": 1
+            },
+            "process_post_path": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}