From c04d22db92c7fd28c8345e37d34c0354b0909ba0 Mon Sep 17 00:00:00 2001 From: Gemini CLI Date: Mon, 8 Jun 2026 11:12:21 -0400 Subject: [PATCH 1/4] fix(source-limit): skip neko vendored X11 keysym and xorg-deps paths Consumer repos with generated keysymdef.go and vendored xorg-deps trees should not fail the 1600-line source-limit gate. --- rust/task-registry-flow-cli/src/source_limit.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/rust/task-registry-flow-cli/src/source_limit.rs b/rust/task-registry-flow-cli/src/source_limit.rs index b60c9e2..b057c46 100644 --- a/rust/task-registry-flow-cli/src/source_limit.rs +++ b/rust/task-registry-flow-cli/src/source_limit.rs @@ -562,6 +562,7 @@ fn skip_dir(path: &str) -> bool { | "out" | "venv" | "vendor" + | "xorg-deps" ) }) } @@ -586,6 +587,7 @@ fn skip_file(path: &str) -> bool { | "deno.lock" | "flake.lock" | "go.sum" + | "keysymdef.go" ) || path == "docs/task-registry/events.jsonl" || path.starts_with("docs/task-registry/archive/") } From 7d43f8aff77b7043410e059620aab3def1c6fa5a Mon Sep 17 00:00:00 2001 From: Gemini CLI Date: Mon, 8 Jun 2026 19:50:14 -0400 Subject: [PATCH 2/4] feat(governance): harden mutation hook stdout and Cursor gate doctrine Emit codex/claude allow JSON, capture verify-mutation-hook output off the hook pipe, add hook-gate-doctrine Cursor rule template with install wiring, and ship test-mutation-hook-stdout.sh for consumer verification. --- CHANGELOG.md | 19 ++++++++++++++++ MANIFEST.toml | 5 +++++ REQUIREMENTS.toml | 1 + docs/agent-environment-matrix.md | 2 +- scripts/test-mutation-hook-stdout.sh | 20 +++++++++++++++++ .../rules/agent-governance.mdc.template | 2 +- .../rules/hook-gate-doctrine.mdc.template | 22 +++++++++++++++++++ .../pre-tool-use-gap-closure.sh.template | 11 +++++++++- .../pre-tool-use-gap-closure.sh | 11 +++++++++- 9 files changed, 89 insertions(+), 4 deletions(-) create mode 100755 scripts/test-mutation-hook-stdout.sh create mode 100644 templates/.cursor/rules/hook-gate-doctrine.mdc.template diff --git a/CHANGELOG.md b/CHANGELOG.md index 5302bfd..dcfef6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,25 @@ ## Unreleased +### Added + +- Cursor `hook-gate-doctrine.mdc` rule template (`alwaysApply`) with hook gate triage: + invalid JSON vs plan binding vs deterministic path errors. +- `scripts/test-mutation-hook-stdout.sh` to assert the mutation gate emits one JSON object. + +### Changed + +- Mutation hook shell adapter: emit codex/claude allow JSON; capture + `verify-mutation-hook` stdout/stderr off the hook pipe so Cursor receives valid JSON. +- Cursor `agent-governance.mdc` template: hooks are operational directions, not + obstacles to bypass. +- `docs/agent-environment-matrix.md` Cursor row documents hook operational doctrine. + +### Fixed + +- `source-limit check` skips generated `keysymdef.go` and vendored `xorg-deps/` trees + in consumer repositories. + ## 2.1.0 - 2026-06-01 ### Added diff --git a/MANIFEST.toml b/MANIFEST.toml index 23be54b..0b42b82 100644 --- a/MANIFEST.toml +++ b/MANIFEST.toml @@ -86,6 +86,10 @@ config_key = "mutation_gate.hook_script_path" template = "templates/.cursor/rules/agent-governance.mdc.template" destination = ".cursor/rules/agent-governance.mdc" +[[render]] +template = "templates/.cursor/rules/hook-gate-doctrine.mdc.template" +destination = ".cursor/rules/hook-gate-doctrine.mdc" + [[render]] template = "templates/.claude/settings.json.template" destination = ".claude/settings.json" @@ -196,6 +200,7 @@ tracked_for_ci = [ ".agents/skills/task-registry-flow", ".agents/skills/task-registry-flow.md", ".cursor/rules/agent-governance.mdc", + ".cursor/rules/hook-gate-doctrine.mdc", ".cursor/hooks.json", ".cursor/hooks/gap-closure-gate.sh", "AGENTS.md", diff --git a/REQUIREMENTS.toml b/REQUIREMENTS.toml index 93dd72a..8f47b3a 100644 --- a/REQUIREMENTS.toml +++ b/REQUIREMENTS.toml @@ -28,6 +28,7 @@ required = [ ".agents/skills/task-registry-flow", ".agents/skills/task-registry-flow.md", ".cursor/rules/agent-governance.mdc", + ".cursor/rules/hook-gate-doctrine.mdc", ".cursor/hooks.json", ".cursor/hooks/gap-closure-gate.sh", "AGENTS.md", diff --git a/docs/agent-environment-matrix.md b/docs/agent-environment-matrix.md index da147d9..5015efe 100644 --- a/docs/agent-environment-matrix.md +++ b/docs/agent-environment-matrix.md @@ -8,7 +8,7 @@ are guardrails. |-------------|--------------|--------------| | Codex | `AGENTS.md`, `.codex/config.toml`, `.codex/hooks.json`, `.agents/skills//SKILL.md` | `plugins/agent-governance/scripts/status.sh --env codex`; Codex hooks require a trusted project | | Antigravity CLI | `GEMINI.md`, `.agents/hooks.json`, `.agents/skills/*.md`, `.agents/plugins/agent-governance` | `agy --version` must be 1.0.3 or newer; `agy plugin validate plugins/agent-governance` must process hooks | -| Cursor | `.cursor/rules/agent-governance.mdc`, `.cursor/skills//SKILL.md`, `.cursor/hooks.json` | `plugins/agent-governance/scripts/status.sh --env cursor`; `cursor-agent --plugin-dir plugins/agent-governance` can load local plugin code | +| Cursor | `.cursor/rules/agent-governance.mdc`, `.cursor/rules/hook-gate-doctrine.mdc` (always-on gate triage), `.cursor/skills//SKILL.md`, `.cursor/hooks.json` | `plugins/agent-governance/scripts/status.sh --env cursor`; hooks are **operational directions** at mutation time (deny = missing governance step; invalid JSON = gate repair on active hook target, not a new plan); optional user-level governed subagents complement repo-local skills/hooks | | Claude Code | `CLAUDE.md`, `.claude/settings.json`, `.claude/skills//SKILL.md` | `plugins/agent-governance/scripts/status.sh --strict`; `.claude/settings.json` must delegate PreToolUse to the canonical mutation gate | Do not add compatibility shims for old workspace `.gemini/settings.json`, stale `.codex/settings.toml`, or `.codex/hooks/user-plan-approval.toml`. Current install removes those generated paths. diff --git a/scripts/test-mutation-hook-stdout.sh b/scripts/test-mutation-hook-stdout.sh new file mode 100755 index 0000000..0e39acf --- /dev/null +++ b/scripts/test-mutation-hook-stdout.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Assert the canonical mutation gate emits exactly one JSON object on stdout. +set -euo pipefail + +root="$(git rev-parse --show-toplevel)" +cd "$root" + +hook="${MUTATION_HOOK_SCRIPT:-tools/agent-governance/pre-tool-use-gap-closure.sh}" +if [[ ! -f "$hook" ]]; then + echo "FAIL: mutation hook not found: $hook" >&2 + exit 1 +fi + +out="$(printf '{}' | GOVERNANCE_HOOK_FORMAT=cursor bash "$hook" --format cursor)" +if printf '%s' "$out" | grep -q '^TASK_VERIFY'; then + echo "FAIL: verify-mutation-hook leaked to stdout: $out" >&2 + exit 1 +fi +printf '%s' "$out" | python3 -c 'import json,sys; json.load(sys.stdin)' +echo "ok: single valid JSON on hook stdout" diff --git a/templates/.cursor/rules/agent-governance.mdc.template b/templates/.cursor/rules/agent-governance.mdc.template index 4ef5525..e7f1e3d 100644 --- a/templates/.cursor/rules/agent-governance.mdc.template +++ b/templates/.cursor/rules/agent-governance.mdc.template @@ -9,7 +9,7 @@ Use the plugin-owned registry only: `{{TASK_REGISTRY_CLI}} validate`, `status`, Keep source, scripts, configs, docs, templates, and governance files at or below 1600 lines. Treat this as a design-time rule. Before adding behavior to a violating file, run `{{TASK_REGISTRY_CLI}} source-limit plan --path ` and split first. -Cursor hooks live in `.cursor/hooks.json`; they are runtime guardrails, not the source of truth. CI and `{{TASK_REGISTRY_CLI}} source-limit check` are authoritative. +Cursor hooks in `.cursor/hooks.json` enforce repo law at mutation time. Treat hook outcomes as **operational directions** (see `.cursor/rules/hook-gate-doctrine.mdc`): a deny names the missing governance step; **invalid JSON ≠ need another plan** — fix stdout on the existing active hook target. Do not disable hooks or skip the mutation gate. Policy authority remains in `.codex/agent-governance.toml`, `docs/task-registry.toml`, and CI; hooks apply that policy live. Use exact active or planned task targets. Ambiguous shell redirections, compact redirects, and inline write calls without deterministic paths fail closed. A terminal task is immutable after `completed` or `cancelled`; changed follow-up work needs a new `task_id`. diff --git a/templates/.cursor/rules/hook-gate-doctrine.mdc.template b/templates/.cursor/rules/hook-gate-doctrine.mdc.template new file mode 100644 index 0000000..08d1554 --- /dev/null +++ b/templates/.cursor/rules/hook-gate-doctrine.mdc.template @@ -0,0 +1,22 @@ +--- +description: Hook gate triage — invalid JSON vs plan binding vs path errors. +alwaysApply: true +--- + +# Hook gate triage (operational directions) + +Cursor hooks enforce repo law at mutation time. Read `.cursor/rules/agent-governance.mdc` for the full workflow. **Do not disable hooks or use subagents or external terminals to skip registry binding** — except gate self-repair on `{{MUTATION_HOOK_SCRIPT}}` when the hook cannot emit valid JSON. + +## Triage table + +| Symptom | Meaning | Response | +|---------|---------|----------| +| **invalid JSON** from hook | Gate script stdout is polluted (e.g. `TASK_VERIFY_MUTATION_HOOK ok` before JSON) | **Not** “create another plan.” Fix stdout on the **existing active hook target** (capture `verify-mutation-hook` output off the hook pipe). Then retry inside Cursor. | +| **not bound to an active registry task target** | Path not in `[[tasks.targets]]` for an active task | Write/refresh `docs/plans/.md`, run `{{TASK_REGISTRY_CLI}} activate`, edit only listed targets. | +| **did not expose a deterministic target path** | Write/Shell lacked an exact repo-relative path | Use `Write`/`StrReplace` with full path; no vague shell redirects. | + +## When a plan is already active + +Activation unlocks **only** paths in `[[tasks.targets]]`. If those paths still fail with **invalid JSON**, the gate script is broken — repair it first, not the registry. + +Policy authority: `.codex/agent-governance.toml`, `docs/task-registry.toml`, CI. Hooks apply that policy live. diff --git a/templates/tools/agent-governance/pre-tool-use-gap-closure.sh.template b/templates/tools/agent-governance/pre-tool-use-gap-closure.sh.template index dcf5866..9e4fa01 100644 --- a/templates/tools/agent-governance/pre-tool-use-gap-closure.sh.template +++ b/templates/tools/agent-governance/pre-tool-use-gap-closure.sh.template @@ -27,6 +27,7 @@ emit_json() { printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$escaped_reason" ;; codex:allow|claude:allow) + printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n' ;; cursor:deny) printf '{"permission":"deny","user_message":%s,"agent_message":%s}\n' "$escaped_reason" "$escaped_reason" @@ -88,9 +89,17 @@ if [[ "$base_verify_cmd" != "$canonical_verify_cmd" ]]; then exit 0 fi -if output="$(.codex/scripts/task-registry verify-mutation-hook --format "$format" 2>&1)"; then +verify_stderr="$(mktemp)" +verify_stdout="$(mktemp)" +trap 'rm -f "${verify_stderr}" "${verify_stdout}"' EXIT + +if .codex/scripts/task-registry verify-mutation-hook --format "$format" >"${verify_stdout}" 2>"${verify_stderr}"; then emit_json allow else + output="$(tr '\n' ' ' <"${verify_stderr}")" + if [[ -z "${output// }" ]]; then + output="$(tr '\n' ' ' <"${verify_stdout}")" + fi emit_deny "mutation gate failed: ${output}" exit 0 fi diff --git a/tools/agent-governance/pre-tool-use-gap-closure.sh b/tools/agent-governance/pre-tool-use-gap-closure.sh index b788b6f..d78dff2 100755 --- a/tools/agent-governance/pre-tool-use-gap-closure.sh +++ b/tools/agent-governance/pre-tool-use-gap-closure.sh @@ -27,6 +27,7 @@ emit_json() { printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":%s}}\n' "$escaped_reason" ;; codex:allow|claude:allow) + printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}\n' ;; cursor:deny) printf '{"permission":"deny","user_message":%s,"agent_message":%s}\n' "$escaped_reason" "$escaped_reason" @@ -88,9 +89,17 @@ if [[ "$base_verify_cmd" != "$canonical_verify_cmd" ]]; then exit 0 fi -if output="$(.codex/scripts/task-registry verify-mutation-hook --format "$format" 2>&1)"; then +verify_stderr="$(mktemp)" +verify_stdout="$(mktemp)" +trap 'rm -f "${verify_stderr}" "${verify_stdout}"' EXIT + +if .codex/scripts/task-registry verify-mutation-hook --format "$format" >"${verify_stdout}" 2>"${verify_stderr}"; then emit_json allow else + output="$(tr '\n' ' ' <"${verify_stderr}")" + if [[ -z "${output// }" ]]; then + output="$(tr '\n' ' ' <"${verify_stdout}")" + fi emit_deny "mutation gate failed: ${output}" exit 0 fi From dd890e34731172d58fdd6af8dcfe358655c565d9 Mon Sep 17 00:00:00 2001 From: Gemini CLI Date: Mon, 8 Jun 2026 20:06:11 -0400 Subject: [PATCH 3/4] feat(governance): add governed remote PR workflow skill Add a plugin skill that focuses on sorting changes and creating remote PRs with governance evidence, and include it in installer skill projections for Cursor, agents, and Claude paths. --- MANIFEST.toml | 23 ++++++++ scripts/render-from-config.sh | 2 +- skills/governed-pr-flow/PROJECT.md.template | 28 +++++++++ skills/governed-pr-flow/SKILL.md | 63 +++++++++++++++++++++ 4 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 skills/governed-pr-flow/PROJECT.md.template create mode 100644 skills/governed-pr-flow/SKILL.md diff --git a/MANIFEST.toml b/MANIFEST.toml index 0b42b82..3734ce6 100644 --- a/MANIFEST.toml +++ b/MANIFEST.toml @@ -109,6 +109,11 @@ source = "skills/task-registry-flow" destination = ".cursor/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".cursor/skills/governed-pr-flow" +recursive = true + [[copy]] source = "skills/gap-closure-contract" destination = ".agents/skills/gap-closure-contract" @@ -119,6 +124,11 @@ source = "skills/task-registry-flow" destination = ".agents/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".agents/skills/governed-pr-flow" +recursive = true + [[copy]] source = "skills/gap-closure-contract" destination = ".claude/skills/gap-closure-contract" @@ -129,6 +139,11 @@ source = "skills/task-registry-flow" destination = ".claude/skills/task-registry-flow" recursive = true +[[copy]] +source = "skills/governed-pr-flow" +destination = ".claude/skills/governed-pr-flow" +recursive = true + [[generated]] destination = ".agents/skills/gap-closure-contract.md" from = "skills/gap-closure-contract/SKILL.md" @@ -137,6 +152,10 @@ from = "skills/gap-closure-contract/SKILL.md" destination = ".agents/skills/task-registry-flow.md" from = "skills/task-registry-flow/SKILL.md" +[[generated]] +destination = ".agents/skills/governed-pr-flow.md" +from = "skills/governed-pr-flow/SKILL.md" + [[generated]] destination = ".codex/governance-cli.env" from_config = "mutation_gate.verify_hook_command" @@ -199,6 +218,8 @@ tracked_for_ci = [ ".agents/skills/gap-closure-contract.md", ".agents/skills/task-registry-flow", ".agents/skills/task-registry-flow.md", + ".agents/skills/governed-pr-flow", + ".agents/skills/governed-pr-flow.md", ".cursor/rules/agent-governance.mdc", ".cursor/rules/hook-gate-doctrine.mdc", ".cursor/hooks.json", @@ -207,9 +228,11 @@ tracked_for_ci = [ "GEMINI.md", ".cursor/skills/gap-closure-contract/PROJECT.md", ".cursor/skills/task-registry-flow/PROJECT.md", + ".cursor/skills/governed-pr-flow/PROJECT.md", ".claude/settings.json", ".claude/skills/gap-closure-contract/PROJECT.md", ".claude/skills/task-registry-flow/PROJECT.md", + ".claude/skills/governed-pr-flow/PROJECT.md", "docs/task-registry.toml", "docs/task-registry/events.jsonl", ] diff --git a/scripts/render-from-config.sh b/scripts/render-from-config.sh index 1598cbd..6c1ba95 100755 --- a/scripts/render-from-config.sh +++ b/scripts/render-from-config.sh @@ -596,7 +596,7 @@ def render_agy_skill(skill: str) -> str: dest = target_root / ".agents/skills" / f"{skill}.md" return f"{rel(dest)}: {write_file(dest, src.read_text())}" -for skill in ("gap-closure-contract", "task-registry-flow"): +for skill in ("gap-closure-contract", "task-registry-flow", "governed-pr-flow"): actions.append(sync_skill(skill, target_root / ".cursor/skills")) actions.append(sync_skill(skill, target_root / ".agents/skills")) actions.append(sync_skill(skill, target_root / ".claude/skills")) diff --git a/skills/governed-pr-flow/PROJECT.md.template b/skills/governed-pr-flow/PROJECT.md.template new file mode 100644 index 0000000..0a98442 --- /dev/null +++ b/skills/governed-pr-flow/PROJECT.md.template @@ -0,0 +1,28 @@ +# Project extensions for governed-pr-flow + +Optional. Copy to `PROJECT.md` beside the installed skill and edit for your repository. + +## Repository and branches + +- Repository root: `` +- Default PR base branch: `` +- Protected branches: `` + +## Required gates before PR + +- Focused gates: + - `` +- Full gates: + - `` + +## Task-registry mapping + +- Plan location: `docs/plans/.md` +- Activation command: `.codex/scripts/task-registry activate docs/plans/.md` +- Landing command: `.codex/scripts/task-registry verify-landing --plan-id --changed-files ` + +## PR template conventions + +- Title format: `` +- Required body sections: `` +- Required labels/reviewers: `` diff --git a/skills/governed-pr-flow/SKILL.md b/skills/governed-pr-flow/SKILL.md new file mode 100644 index 0000000..f1575a1 --- /dev/null +++ b/skills/governed-pr-flow/SKILL.md @@ -0,0 +1,63 @@ +--- +name: governed-pr-flow +description: Governed workflow for preparing, sorting, and submitting pull requests to remote repositories. Use when the user asks to create a branch, push commits, and open a PR with gh while preserving task-registry validation and proof. +--- + +# Governed PR Flow + +Use this workflow to take already-implemented or staged work to a remote PR under task-registry governance. + +**Project extensions:** when `PROJECT.md` exists beside this skill, load it after this file for repo-specific branch policy, base branch, CI gates, and PR templates. + +## 1) Confirm PR intent and scope + +- Confirm repo root (`git rev-parse --show-toplevel`) matches the intended project. +- Confirm user wants a remote PR (not only local commit). +- Read current project `AGENTS.md` and active plan/task context. + +## 2) Validate governance readiness for PR + +- Ensure the implementation plan has been activated: + - `.codex/scripts/task-registry activate docs/plans/.md` +- Confirm landing and verifier proof are complete for files in scope: + - `.codex/scripts/task-registry verify-landing --plan-id --changed-files ...` +- When registry state changed, verify receipts: + - `.codex/scripts/task-registry verify-chain --format json` + +## 3) Sort changes into coherent buckets + +- Sort changes into coherent buckets by intent (feature, fix, refactor, docs/tests/governance). +- Keep each bucket minimal, reviewable, and tied to task/behavior proof. +- Exclude unrelated dirty files from the PR branch. + +## 4) Stage and commit by bucket + +- Stage only the files for one bucket. +- Commit with message style used by the repository. +- Repeat until all intended buckets are committed. + +## 5) Prepare branch for remote + +- Create or switch to a review branch. +- Confirm branch is correct and ready to publish. + +## 6) Push branch and create remote PR + +- Push and set upstream: + - `git push -u origin HEAD` +- Open PR with GitHub CLI: + - `gh pr create --title "" --body "<body>"` +- Include in PR body: + - Scope summary tied to plan/task. + - Validation commands executed. + - Deferred/blocked tasks with reason, if any. + +## 7) Final PR handoff + +- Run final report for traceability: + - `.codex/scripts/task-registry report <plan_id>` +- Share: PR URL, commands run, outcomes, and remaining risk/deferred items. + +## Example first use + +- Use this skill to submit the `governed-pr-flow` skill addition itself as the first remote PR from the current branch. From f11e05abd32f60a6bbabfd42356a712b3794573d Mon Sep 17 00:00:00 2001 From: Gemini CLI <gemini-cli@example.com> Date: Mon, 8 Jun 2026 20:07:10 -0400 Subject: [PATCH 4/4] Revert "feat(governance): add governed remote PR workflow skill" This reverts commit dd890e34731172d58fdd6af8dcfe358655c565d9. --- MANIFEST.toml | 23 -------- scripts/render-from-config.sh | 2 +- skills/governed-pr-flow/PROJECT.md.template | 28 --------- skills/governed-pr-flow/SKILL.md | 63 --------------------- 4 files changed, 1 insertion(+), 115 deletions(-) delete mode 100644 skills/governed-pr-flow/PROJECT.md.template delete mode 100644 skills/governed-pr-flow/SKILL.md diff --git a/MANIFEST.toml b/MANIFEST.toml index 3734ce6..0b42b82 100644 --- a/MANIFEST.toml +++ b/MANIFEST.toml @@ -109,11 +109,6 @@ source = "skills/task-registry-flow" destination = ".cursor/skills/task-registry-flow" recursive = true -[[copy]] -source = "skills/governed-pr-flow" -destination = ".cursor/skills/governed-pr-flow" -recursive = true - [[copy]] source = "skills/gap-closure-contract" destination = ".agents/skills/gap-closure-contract" @@ -124,11 +119,6 @@ source = "skills/task-registry-flow" destination = ".agents/skills/task-registry-flow" recursive = true -[[copy]] -source = "skills/governed-pr-flow" -destination = ".agents/skills/governed-pr-flow" -recursive = true - [[copy]] source = "skills/gap-closure-contract" destination = ".claude/skills/gap-closure-contract" @@ -139,11 +129,6 @@ source = "skills/task-registry-flow" destination = ".claude/skills/task-registry-flow" recursive = true -[[copy]] -source = "skills/governed-pr-flow" -destination = ".claude/skills/governed-pr-flow" -recursive = true - [[generated]] destination = ".agents/skills/gap-closure-contract.md" from = "skills/gap-closure-contract/SKILL.md" @@ -152,10 +137,6 @@ from = "skills/gap-closure-contract/SKILL.md" destination = ".agents/skills/task-registry-flow.md" from = "skills/task-registry-flow/SKILL.md" -[[generated]] -destination = ".agents/skills/governed-pr-flow.md" -from = "skills/governed-pr-flow/SKILL.md" - [[generated]] destination = ".codex/governance-cli.env" from_config = "mutation_gate.verify_hook_command" @@ -218,8 +199,6 @@ tracked_for_ci = [ ".agents/skills/gap-closure-contract.md", ".agents/skills/task-registry-flow", ".agents/skills/task-registry-flow.md", - ".agents/skills/governed-pr-flow", - ".agents/skills/governed-pr-flow.md", ".cursor/rules/agent-governance.mdc", ".cursor/rules/hook-gate-doctrine.mdc", ".cursor/hooks.json", @@ -228,11 +207,9 @@ tracked_for_ci = [ "GEMINI.md", ".cursor/skills/gap-closure-contract/PROJECT.md", ".cursor/skills/task-registry-flow/PROJECT.md", - ".cursor/skills/governed-pr-flow/PROJECT.md", ".claude/settings.json", ".claude/skills/gap-closure-contract/PROJECT.md", ".claude/skills/task-registry-flow/PROJECT.md", - ".claude/skills/governed-pr-flow/PROJECT.md", "docs/task-registry.toml", "docs/task-registry/events.jsonl", ] diff --git a/scripts/render-from-config.sh b/scripts/render-from-config.sh index 6c1ba95..1598cbd 100755 --- a/scripts/render-from-config.sh +++ b/scripts/render-from-config.sh @@ -596,7 +596,7 @@ def render_agy_skill(skill: str) -> str: dest = target_root / ".agents/skills" / f"{skill}.md" return f"{rel(dest)}: {write_file(dest, src.read_text())}" -for skill in ("gap-closure-contract", "task-registry-flow", "governed-pr-flow"): +for skill in ("gap-closure-contract", "task-registry-flow"): actions.append(sync_skill(skill, target_root / ".cursor/skills")) actions.append(sync_skill(skill, target_root / ".agents/skills")) actions.append(sync_skill(skill, target_root / ".claude/skills")) diff --git a/skills/governed-pr-flow/PROJECT.md.template b/skills/governed-pr-flow/PROJECT.md.template deleted file mode 100644 index 0a98442..0000000 --- a/skills/governed-pr-flow/PROJECT.md.template +++ /dev/null @@ -1,28 +0,0 @@ -# Project extensions for governed-pr-flow - -Optional. Copy to `PROJECT.md` beside the installed skill and edit for your repository. - -## Repository and branches - -- Repository root: `<absolute-path>` -- Default PR base branch: `<branch>` -- Protected branches: `<comma-separated-list>` - -## Required gates before PR - -- Focused gates: - - `<command>` -- Full gates: - - `<command>` - -## Task-registry mapping - -- Plan location: `docs/plans/<slug>.md` -- Activation command: `.codex/scripts/task-registry activate docs/plans/<slug>.md` -- Landing command: `.codex/scripts/task-registry verify-landing --plan-id <plan_id> --changed-files <paths>` - -## PR template conventions - -- Title format: `<convention>` -- Required body sections: `<summary/tests/risk/etc>` -- Required labels/reviewers: `<policy>` diff --git a/skills/governed-pr-flow/SKILL.md b/skills/governed-pr-flow/SKILL.md deleted file mode 100644 index f1575a1..0000000 --- a/skills/governed-pr-flow/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: governed-pr-flow -description: Governed workflow for preparing, sorting, and submitting pull requests to remote repositories. Use when the user asks to create a branch, push commits, and open a PR with gh while preserving task-registry validation and proof. ---- - -# Governed PR Flow - -Use this workflow to take already-implemented or staged work to a remote PR under task-registry governance. - -**Project extensions:** when `PROJECT.md` exists beside this skill, load it after this file for repo-specific branch policy, base branch, CI gates, and PR templates. - -## 1) Confirm PR intent and scope - -- Confirm repo root (`git rev-parse --show-toplevel`) matches the intended project. -- Confirm user wants a remote PR (not only local commit). -- Read current project `AGENTS.md` and active plan/task context. - -## 2) Validate governance readiness for PR - -- Ensure the implementation plan has been activated: - - `.codex/scripts/task-registry activate docs/plans/<slug>.md` -- Confirm landing and verifier proof are complete for files in scope: - - `.codex/scripts/task-registry verify-landing --plan-id <plan_id> --changed-files <path>...` -- When registry state changed, verify receipts: - - `.codex/scripts/task-registry verify-chain --format json` - -## 3) Sort changes into coherent buckets - -- Sort changes into coherent buckets by intent (feature, fix, refactor, docs/tests/governance). -- Keep each bucket minimal, reviewable, and tied to task/behavior proof. -- Exclude unrelated dirty files from the PR branch. - -## 4) Stage and commit by bucket - -- Stage only the files for one bucket. -- Commit with message style used by the repository. -- Repeat until all intended buckets are committed. - -## 5) Prepare branch for remote - -- Create or switch to a review branch. -- Confirm branch is correct and ready to publish. - -## 6) Push branch and create remote PR - -- Push and set upstream: - - `git push -u origin HEAD` -- Open PR with GitHub CLI: - - `gh pr create --title "<title>" --body "<body>"` -- Include in PR body: - - Scope summary tied to plan/task. - - Validation commands executed. - - Deferred/blocked tasks with reason, if any. - -## 7) Final PR handoff - -- Run final report for traceability: - - `.codex/scripts/task-registry report <plan_id>` -- Share: PR URL, commands run, outcomes, and remaining risk/deferred items. - -## Example first use - -- Use this skill to submit the `governed-pr-flow` skill addition itself as the first remote PR from the current branch.