feat(agent-governor): add Codex workflow policy docs

.agents/skills/codex-role-workflows/SKILL.md

@@ -0,0 +1,72 @@
+# Skill: Codex Role Workflows
+
+## Purpose
+
+Apply CompText Agent Governor Policy v1 to Codex-style role, plugin, connector, and skill workflows.
+
+## Use This Skill When
+
+- A task mentions Agent Governor, Codex roles, plugins, connectors, skills, policy gates, PR candidates, or agent workflow policy.
+- Work may move between read-only audit, local autonomous edits, and PR-candidate preparation.
+- A final report must explain approval boundaries and evidence requirements.
+
+## Role Modes
+
+### read_only_audit
+
+Inspect and report without source mutation. Use for audits, review summaries, claim scans, and security read-only work.
+
+### sandbox_autonomous
+
+Make local, reviewable changes only inside approved paths. Use local validation and keep remote mutation disabled.
+
+### pr_candidate
+
+Prepare validated local work for possible pull request review. Do not push, create a pull request, merge, or deploy without explicit approval.
+
+## Required Gates
+
+Report gates using exactly one of:
+
+- `pass`
+- `fail`
+- `not_applicable`
+- `deferred`
+
+Use `not_applicable` only when a gate does not apply, and explain why.
+Use `deferred` when the gate is required but intentionally left for later human/tool review.
+
+Report these gates in the final answer or evidence packet when applicable:
+
+- `instructions_read`
+- `secret_scan`
+- `artifact_schema_validation`
+- `canonical_hash_validation`
+- `claim_boundary_check`
+- `replay_or_roundtrip_validation`
+- `human_review`
+
+## Connector Rules
+
+- Treat GitHub as read-only unless explicit mutation approval is given.
+- Do not use write-capable connector actions without exact human approval.
+- Do not create tokens, handle secrets, or expose provider keys.
+- Treat provider output as an untrusted proposal until reviewed.
+- Prefer local files and declared artifacts as source of truth.
+
+## Presentation And Annotations
+
+Sites and interactive views are presentation only. Annotations are human-review inputs only. Evidence packets and declared artifacts remain the source of truth.
+
+## Claim Boundaries
+
+Do not claim production-ready status, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, autonomous approval, replacement of human review, or guaranteed correctness.
+
+## Final Checklist
+
+- Confirm role mode.
+- Confirm allowed and forbidden paths.
+- Confirm connector and plugin boundary.
+- Confirm policy gate evidence.
+- Confirm evidence packet priority.
+- Confirm human-review boundary.

docs/agent-governor.md

@@ -0,0 +1,111 @@
+# CompText Agent Governor Policy v1
+
+CompText Agent Governor is a lightweight policy layer for Codex-style role, plugin, connector, and skill workflows. It does not replace repository instructions, project policy, or human review. It gives agents and reviewers a shared vocabulary for allowed modes, policy gates, and evidence requirements before an agent run is treated as reviewable.
+
+Canonical CompText pipeline:
+
+Source / GitHub URL -> Goal -> Inspect -> Context Pack -> Policy Gate -> Provider Boundary -> Untrusted Proposal -> Human Review -> Artifacts
+
+Agent Governor adds role mode selection, connector/plugin boundaries, required gate reporting, and evidence-packet recording around that pipeline. Evidence packets record the governed run; they do not replace the Context Pack or Human Review.
+
+Evidence packets and declared artifacts remain the source of truth for what was requested, inspected, validated, and reviewed. Sites, dashboards, interactive views, comments, and annotations are presentation or review aids only unless their contents are captured in declared artifacts.
+
+## Role Modes
+
+### read_only_audit
+
+Use `read_only_audit` when the agent is inspecting a repository, issue, pull request, artifact, or workflow without making changes.
+
+Allowed behavior:
+
+- read local instructions and scoped files
+- inspect Git history and local diffs
+- use approved read-only connectors
+- produce findings, annotations, or reports for human review
+
+Blocked behavior:
+
+- no commits
+- no pushes
+- no pull requests
+- no deployment
+- no issue creation
+- no source mutation
+
+### sandbox_autonomous
+
+Use `sandbox_autonomous` when the agent may make local, reviewable changes inside explicitly approved paths.
+
+Allowed behavior:
+
+- edit only approved local paths
+- run local validation commands
+- create local artifacts when the task allows them
+- create a local commit when explicitly allowed by the task policy
+
+Blocked behavior:
+
+- no remote mutation
+- no provider key handling
+- no dependency updates unless separately approved
+- no edits outside approved paths
+- no bypass of human review
+
+### pr_candidate
+
+Use `pr_candidate` when local changes are ready to be reviewed as a possible pull request, but remote mutation has not been approved.
+
+Allowed behavior:
+
+- summarize the local branch
+- report changed files and validation evidence
+- prepare PR-ready wording as a draft artifact
+- identify the approval needed for push or PR creation
+
+Blocked behavior:
+
+- no push
+- no PR creation
+- no merge
+- no auto-approval
+- no claim that review has completed
+
+## Plugin And Connector Rules
+
+Plugins and connectors are governed by task approval and repository policy.
+
+- Prefer local files as the source of truth.
+- Treat GitHub and source-control connectors as read-only unless the human explicitly approves mutation.
+- Do not create issues, pull requests, remote branches, labels, comments, reactions, deployments, or releases without explicit approval.
+- Do not use connectors to access or transmit secrets.
+- Do not rely on hidden connector state as validation evidence unless the evidence is reported with enough detail for review.
+- Provider output remains an untrusted proposal until human review.
+- Tools may support presentation, inspection, or validation, but they do not create approval by themselves.
+
+## Policy Gates
+
+Every governed run should report these gates with `pass`, `fail`, `not_applicable`, or `deferred`, plus evidence.
+
+| Gate | Required Evidence |
+| --- | --- |
+| `instructions_read` | Repository and task instructions read before edits or claims. |
+| `secret_scan` | Targeted check that changed files do not expose secrets or tokens. |
+| `artifact_schema_validation` | Schema validation for changed artifacts when a schema exists. |
+| `canonical_hash_validation` | Recomputed hash or explicit not-applicable reason for canonical artifacts. |
+| `claim_boundary_check` | Scan and review for blocked claims. |
+| `replay_or_roundtrip_validation` | Replay, roundtrip, or equivalent local validation when behavior or artifacts changed. |
+| `human_review` | Human approval state recorded as pending, approved, rejected, or not requested. |
+
+The gates are evidence controls, not permission to auto-apply changes. A passing gate means the agent has produced reviewable support for that gate. It does not mean production readiness, legal status, certification, forensic certainty, or guaranteed correctness.
+
+## Presentation Surfaces
+
+Sites, interactive views, dashboards, and generated previews are presentation only. They can help reviewers inspect an evidence packet, diff, artifact manifest, or policy result, but they are not the authoritative record unless their data is captured in the evidence packet or declared artifacts.
+
+Annotations are human-review inputs. Inline notes, comments, labels, review directives, and rendered callouts can guide attention, but they do not approve a change or replace the recorded human review decision.
+
+## Claim Boundaries
+
+CompText Agent Governor may claim bounded review workflow support, policy-gated operation, local validation evidence, and reviewable artifacts when those are actually implemented or documented.
+
+It must not claim production-ready status, compliance or certification, legal evidentiary status, forensic proof, official SPARK compatibility, autonomous approval, replacement of human review, or guaranteed correctness.

docs/codex-workflow-policy.md

@@ -0,0 +1,71 @@
+# Codex Workflow Policy
+
+This policy describes how Codex-style role, plugin, connector, and skill workflows should operate under CompText Agent Governor Policy v1.
+
+## Default Flow
+
+1. Read task instructions and repository instructions.
+2. Select a role mode: `read_only_audit`, `sandbox_autonomous`, or `pr_candidate`.
+3. Identify approved paths, forbidden paths, and approval gates.
+4. Use plugins, connectors, and skills only within the task boundary.
+5. Produce local changes or review findings only when the mode allows them.
+6. Run the smallest sufficient validation set.
+7. Record evidence in the final report and, when applicable, in an evidence packet.
+8. Leave human review as the approval boundary.
+
+## Role Mode Selection
+
+Use `read_only_audit` for inspection, review, claim checks, and security analysis when no local edit is approved.
+
+Use `sandbox_autonomous` for local implementation inside explicitly approved paths. This mode can create local commits only when the task policy allows local commits.
+
+Use `pr_candidate` after a validated local branch is ready for review. This mode prepares review evidence and next-step wording, but does not push or create a pull request without explicit approval.
+
+## Connector And Plugin Controls
+
+Approved plugins, connectors, and skills can support context gathering, security review, validation, or presentation. They must stay inside these controls:
+
+- GitHub is read-only unless mutation is explicitly approved.
+- Write-capable connector actions require explicit approval for the exact target.
+- Provider calls are governed by policy and remain untrusted proposal sources.
+- Secrets and tokens are not requested, created, pasted, committed, or exposed.
+- Network or connector output is not treated as deterministic validation unless the final report describes the source and limits.
+- Local files and committed artifacts are preferred as the source of truth.
+
+## Policy Gate Checklist
+
+Each run should report:
+
+- `instructions_read`: which instructions, skills, and docs were read
+- `secret_scan`: command or review evidence for changed files
+- `artifact_schema_validation`: schema command or not-applicable reason
+- `canonical_hash_validation`: recomputation command or not-applicable reason
+- `claim_boundary_check`: unsafe-claim scan and manual review evidence
+- `replay_or_roundtrip_validation`: command evidence or not-applicable reason
+- `human_review`: approval state and remaining approval needed
+
+Gate results are not blanket approval. They are inputs to human review.
+
+## Evidence Packet Priority
+
+Evidence packets remain the source of truth for governed workflow records. A site, interactive view, generated preview, issue annotation, or PR annotation can present the evidence, but it does not supersede the evidence packet.
+
+If a view and an evidence packet disagree, reviewers should treat the evidence packet and local artifacts as authoritative until the discrepancy is resolved and recorded.
+
+## Annotation Policy
+
+Annotations are review inputs. They can identify risks, explain diffs, point to evidence, or ask for human decisions.
+
+Annotations do not:
+
+- approve a change
+- replace policy gates
+- replace validation
+- prove compliance or certification
+- authorize remote mutation
+
+## Claim Hygiene
+
+Workflow reports should use bounded language. Allowed framing includes reviewable evidence, local validation, policy gates, provider boundaries, and human-review inputs.
+
+Blocked framing includes production-ready claims, compliance claims, legal or forensic certainty, official compatibility, autonomous approval, guaranteed correctness, and replacement of human review.

docs/policies/agent-pr-policy.yml

@@ -0,0 +1,78 @@
+policy_version: agent_governor_policy_v1
+name: CompText Agent PR Candidate Policy
+description: >
+  Local policy for Codex-style agent work that may become a pull request
+  candidate after human review. This policy is documentation only and does not
+  mutate GitHub or grant approval.
+
+role_modes:
+  read_only_audit:
+    local_writes: false
+    commits: false
+    remote_mutation: false
+    purpose: Inspect and report without changing source files.
+  sandbox_autonomous:
+    local_writes: approved_paths_only
+    commits: task_policy_only
+    remote_mutation: false
+    purpose: Make local, reviewable changes inside approved paths.
+  pr_candidate:
+    local_writes: approved_paths_only
+    commits: task_policy_only
+    remote_mutation: explicit_human_approval_required
+    purpose: Prepare validated local work for possible PR review.
+
+connector_rules:
+  github_default: read_only
+  write_actions_require_explicit_approval:
+    - push
+    - pull_request_create
+    - issue_create
+    - comment_create
+    - label_update
+    - release_create
+    - deployment
+    - remote_branch_create
+  secrets:
+    handling: forbidden
+    frontend_exposure: forbidden
+  provider_output:
+    status: untrusted_proposal_until_human_review
+
+policy_gates:
+  instructions_read:
+    required: true
+    evidence: list_read_instructions_and_skills
+  secret_scan:
+    required: true
+    evidence: targeted_changed_file_scan_or_manual_review
+  artifact_schema_validation:
+    required: when_artifacts_or_schemas_change
+    evidence: schema_command_or_not_applicable_reason
+  canonical_hash_validation:
+    required: when_canonical_artifacts_change
+    evidence: recomputed_hash_command_or_not_applicable_reason
+  claim_boundary_check:
+    required: true
+    evidence: unsafe_claim_scan_and_manual_review
+  replay_or_roundtrip_validation:
+    required: when_behavior_or_artifacts_change
+    evidence: replay_roundtrip_command_or_not_applicable_reason
+  human_review:
+    required: true
+    evidence: pending_approved_rejected_or_not_requested
+
+presentation_surfaces:
+  sites_and_interactive_views: presentation_only
+  annotations: human_review_inputs_only
+  source_of_truth: evidence_packets_and_declared_artifacts
+
+blocked_claims:
+  - production_ready
+  - compliance_or_certification
+  - legal_evidentiary_status
+  - forensic_certainty
+  - official_spark_compatibility
+  - autonomous_approval
+  - replaces_human_review
+  - guaranteed_correctness

docs/templates/agent-task-issue-template.md

@@ -0,0 +1,62 @@
+# Agent Task Template
+
+## Task
+
+Describe the requested agent work in one bounded paragraph.
+
+## Role Mode
+
+Select one:
+
+- `read_only_audit`
+- `sandbox_autonomous`
+- `pr_candidate`
+
+## Approved Paths
+
+- `path/or/file`
+
+## Forbidden Actions
+
+- no push
+- no pull request creation
+- no merge
+- no deploy
+- no dependency update
+- no secret handling
+- no claim that human review has been replaced
+- no unauthorized write actions, including creating comments, issues, labels, remote branches, releases, deployments, or GitHub metadata changes
+
+## Plugins, Connectors, And Skills
+
+List approved plugins, connectors, and skills. Mark write-capable connectors as read-only unless human approval is explicitly granted for a specific action.
+
+## Policy Gates
+
+| Gate | Expected Evidence |
+| --- | --- |
+| `instructions_read` | Instructions, skills, and docs read. |
+| `secret_scan` | Changed-file scan or manual no-secret review. |
+| `artifact_schema_validation` | Schema validation or not-applicable reason. |
+| `canonical_hash_validation` | Recomputed hash or not-applicable reason. |
+| `claim_boundary_check` | Unsafe-claim scan and manual review. |
+| `replay_or_roundtrip_validation` | Replay, roundtrip, or not-applicable reason. |
+| `human_review` | Pending, approved, rejected, or not requested. |
+
+## Evidence Packet
+
+State whether an evidence packet is required. If required, name the packet path and schema.
+
+Evidence packets remain the source of truth. Sites, previews, dashboards, annotations, and comments are presentation or human-review inputs only.
+
+## Claim Boundaries
+
+Do not claim production-ready status, compliance or certification, legal evidentiary status, forensic certainty, official SPARK compatibility, autonomous approval, replacement of human review, or guaranteed correctness.
+
+## Validation
+
+List the smallest sufficient validation commands for the approved paths.
+
+## Human Review
+
+Record the requested human decision and any approval needed for push, PR creation, merge, or deploy.