feat(governance): add governed remote PR workflow skill

MANIFEST.toml

@@ -105,6 +105,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"
@@ -115,6 +120,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"
@@ -125,6 +135,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"
@@ -133,6 +148,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"
@@ -195,16 +214,20 @@ 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/hooks.json",
   ".cursor/hooks/gap-closure-gate.sh",
   "AGENTS.md",
   "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",
 ]

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"))

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: `<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>`

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/<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.