From 5dd0800e6a904defde4acfe7e5450515e7f619a3 Mon Sep 17 00:00:00 2001 From: Appel420 <201665841+Appel420@users.noreply.github.com> Date: Fri, 10 Jul 2026 21:36:51 -0400 Subject: [PATCH 1/4] docs(template): add rollback certificate template --- docs/templates/rollback.yaml | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docs/templates/rollback.yaml diff --git a/docs/templates/rollback.yaml b/docs/templates/rollback.yaml new file mode 100644 index 0000000..26d5c6b --- /dev/null +++ b/docs/templates/rollback.yaml @@ -0,0 +1,27 @@ +# Rollback Certificate Template +# Copy to `rollback.yaml` for each merge into protected branches. + +rollback: + change_id: "" + merged_pr: null + merged_commit: "" + previous_commit: "" + migration: + required: false + steps: [] + database: + impact: "none" + backup_reference: "" + risk: + level: "low" + rationale: "" + rollback_steps: + - "git revert " + - "re-run CI" + - "validate service health checks" + owner_approval: + contributor_id: "owner-human" + timestamp_utc: "" + integrity: + algorithm: sha512 + digest: "" From e93189bef7e1ffbbdaa36d7ce7739c03ade14ca4 Mon Sep 17 00:00:00 2001 From: Appel420 <201665841+Appel420@users.noreply.github.com> Date: Fri, 10 Jul 2026 21:37:03 -0400 Subject: [PATCH 2/4] chore(policy): add CONTRIBUTORS.ai.yaml manifest for human and GitHub service identities --- CONTRIBUTORS.ai.yaml | 63 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 CONTRIBUTORS.ai.yaml diff --git a/CONTRIBUTORS.ai.yaml b/CONTRIBUTORS.ai.yaml new file mode 100644 index 0000000..ddf35b0 --- /dev/null +++ b/CONTRIBUTORS.ai.yaml @@ -0,0 +1,63 @@ +version: 1 +repository: gateone +generated_at: 2026-07-11T00:00:00Z +policy: + default_trust_level: constrained + require_verified_identity: true + require_signed_commits_on_protected_branches: true + require_human_approval_for_merge: true +contributors: + - id: owner-human + type: human + role: Owner + provider: + name: GitHub + identity: + algorithm: Ed25519 + public_key_fingerprint: "REPLACE_WITH_REAL_FINGERPRINT" + permissions: + create_branch: true + commit: true + open_pr: true + review: true + merge: true + delete_branch: false + approve_release: true + trust_level: high + status: active + + - id: copilot-github + type: ai + role: Coding + provider: + name: GitHub Copilot + identity: + algorithm: Ed25519 + public_key_fingerprint: "REPLACE_WITH_REAL_FINGERPRINT" + permissions: + create_branch: true + commit: true + open_pr: true + review: true + merge: false + delete_branch: false + trust_level: constrained + status: active + + - id: dependabot-github + type: automation + role: DependencyMaintenance + provider: + name: GitHub Dependabot + identity: + algorithm: Ed25519 + public_key_fingerprint: "REPLACE_WITH_REAL_FINGERPRINT" + permissions: + create_branch: true + commit: true + open_pr: true + review: false + merge: false + delete_branch: false + trust_level: constrained + status: active From 2335f1a00c15a4495fe7a75cc59e04ab45025c52 Mon Sep 17 00:00:00 2001 From: Appel420 <201665841+Appel420@users.noreply.github.com> Date: Fri, 10 Jul 2026 21:37:10 -0400 Subject: [PATCH 3/4] docs(template): add provenance manifest template for pull requests --- docs/templates/provenance.yaml | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/templates/provenance.yaml diff --git a/docs/templates/provenance.yaml b/docs/templates/provenance.yaml new file mode 100644 index 0000000..0bb355f --- /dev/null +++ b/docs/templates/provenance.yaml @@ -0,0 +1,30 @@ +# PR Provenance Manifest Template +# Copy to `provenance.yaml` and complete for each pull request. + +provenance: + pr_number: null + title: "" + created_by: + contributor_id: "" + role: "" + reviewed_by: + - contributor_id: "" + role: "" + validated_by: + - contributor_id: "ci-github-actions" + role: "CI" + approved_by: + - contributor_id: "owner-human" + role: "Owner" + timestamp_utc: "" + source_branch: "" + target_branch: "" + source_commits: + - "" + artifacts: + sbom: "" + test_report: "" + security_report: "" + integrity: + algorithm: sha512 + digest: "" From fe6b1a2bc1f5bba3df092a6214b120c94a5284fe Mon Sep 17 00:00:00 2001 From: Appel420 <201665841+Appel420@users.noreply.github.com> Date: Fri, 10 Jul 2026 21:53:07 -0400 Subject: [PATCH 4/4] security(policy): apply local-first owner-controlled collaboration rules --- .../github-tools-collaboration/SKILL.md | 265 +++++++++++------- 1 file changed, 164 insertions(+), 101 deletions(-) diff --git a/.github/skills/github-tools-collaboration/SKILL.md b/.github/skills/github-tools-collaboration/SKILL.md index c260d25..e57c18e 100644 --- a/.github/skills/github-tools-collaboration/SKILL.md +++ b/.github/skills/github-tools-collaboration/SKILL.md @@ -1,121 +1,184 @@ --- -name: GitHub Tools Collaboration -description: Controlled multi-agent software collaboration using GitHub branches, commits, reviews, and audit trails. +name: GitHub Tools Collaboration v2 +description: Owner-controlled, local-first collaboration for human, AI, and automation contributors. --- -# GitHub Tools Collaboration +# GitHub Tools Collaboration v2 — Local-First, Owner-Controlled ## Purpose -Enable controlled multi-agent software collaboration using GitHub as the source of truth. All agents, automation, and human contributors operate through accountable branches, commits, reviews, and audit trails. - -## Core Principles - -### Branch Isolation -- Never push directly to main. -- Every agent must work from a dedicated branch. -- Branch names must identify ownership and purpose. - -### Pull Request Workflow -1. Issue / Task -2. Create Branch -3. Implement Change -4. Run CI Validation -5. Create Pull Request -6. Review -7. Merge -8. Audit Record - -### Agent Accountability -Every contributor must provide: -- Branch identity -- Commit history -- Change summary -- Test results -- Security impact -- Rollback path - -### Required Commit Style -Use: `type(scope): description` + +GitHub is used as a review and source-control record. It does not replace the repository owner's local development, CI, infrastructure, or authority. + +The repository owner controls policies, credentials, CI providers, data sharing, approvals, and merges. Agents and automation are contributors with limited permissions, not autonomous owners. + +## Local-First Policy + +- Local CI is the primary validation authority. +- Cloud CI and hosted scanners are optional and require explicit owner approval. +- Core validation must work offline or with locally controlled tools whenever practical. +- No policy may require GitHub Actions, SaaS scanners, hosted SBOM services, telemetry, or third-party artifact upload unless the owner enables it in a reviewed change. +- No source code, prompts, logs, test artifacts, secrets, or build outputs may be exported to a third party automatically. +- A contributor must not change CI providers, required checks, network access, or data-export behavior without an owner-approved PR. +- PRs must distinguish local checks from optional cloud checks. +- Locally produced, reproducible validation evidence is acceptable when cloud services are unavailable. +- The policy defines required outcomes, not a vendor-specific implementation. + +## Explicit Controls + +- All material decisions and approvals must be recorded in repository artifacts such as commits, PRs, reviews, or ADRs. +- Every merge to a protected branch must include a documented rollback path. +- Protected branches require explicit human approval; AI and bot identities cannot self-merge. +- No hidden service, credential, network callback, telemetry collector, or automatic remote upload may be introduced by this policy. + +## Contributor Identity + +Every human, AI, and automation contributor must have a distinct repository identity and declared permissions. Anonymous or shared bot identities are not permitted for accountable changes. + +Example: + +```yaml +id: copilot-github + type: ai + role: Coding + provider: GitHub Copilot +permissions: + create_branch: true + commit: true + open_pr: true + review: true + merge: false + delete_branch: false +status: active +``` + +Maintain identities in `CONTRIBUTORS.ai.yaml`. Public-key fields are declarative metadata until the repository owner configures actual signing and verification infrastructure; placeholders must not be treated as verified keys. + +## Branch Convention + +Never write directly to a protected default branch. Use a dedicated branch named: + +```text +// +``` + +Allowed types: `feat`, `fix`, `security`, `docs`, `refactor`, `research`, and `collab`. Examples: + +- `collab/github-services` +- `feat/copilot/identity-vault` +- `security/dependabot/dependency-update` + +## Workflow + +1. Issue or task +2. Dedicated branch +3. Implementation +4. Local CI validation +5. Pull request +6. Required review +7. Human approval +8. Merge by an authorized human or explicitly authorized mechanism +9. Audit and rollback record + +## Commit Requirements + +Use `type(scope): description`, for example: + - `feat(gateway): add JWT validation middleware` - `fix(trust): quarantine invalid CA fingerprints` -- `test(attestation): add PQC verification tests` -- `security(policy): enforce RBAC boundary checks` - -### GitHub Tool Permissions -Allowed operations: -- Read repositories -- Inspect branches -- Read issues -- Create branches -- Modify files on feature branches -- Create pull requests -- Comment on reviews -- Run CI workflows -- Inspect security findings - -Restricted operations: -- Direct main branch writes -- Destructive repository changes -- Removing audit history -- Bypassing required reviews - -### Collaboration Roles -- **Architect Agent**: system design, interfaces, dependency decisions, security boundaries -- **Coding Agent**: implementation, tests, documentation, commit hygiene, security -- **Security Agent**: vulnerability review, cryptographic validation, supply-chain checks -- **Judge Agent**: final quality review, risk scoring, merge recommendation - -## Required PR Template -```md -## Summary -What changed? +- `docs(policy): document local CI requirements` -## Motivation -Why is this required? +Commits must identify the contributor, summarize changes, report tests actually run, state security impact, and identify a rollback path. Never claim tests or scans that were not executed. -## Security Impact -Does this affect: -- Authentication -- Authorization -- Cryptography -- Data handling -- Supply chain +## Provenance and Decision Records -## Testing -Tests executed: +Each PR should include `docs/templates/provenance.yaml` or equivalent metadata identifying: -## Rollback -How to revert safely: +- creator +- reviewers +- validator +- human approver +- source branch and commits +- local checks and optional cloud checks +- integrity digest, if configured + +Significant architectural or security decisions should use an ADR in `docs/adr/`, recording context, alternatives, selected solution, rationale, risks, and approval. + +## Review Matrix + +| Reviewer | Responsibility | +|---|---| +| Architect | Architecture and boundaries | +| Coding | Implementation and tests | +| Security | Secrets, cryptography, dependencies, and supply chain | +| Judge | Quality and risk synthesis | +| Human owner | Final authority and merge approval | + +No contributor may be the sole approver of its own work. Security review is required for security-sensitive changes. + +## Local Security Gate + +The owner may implement these gates with local tools: + +1. Secret scan +2. Dependency scan +3. SBOM generation +4. License check +5. PQC validation when applicable +6. Unit tests +7. Integration tests +8. Threat-model review +9. Human approval + +A failing required local gate blocks merge. The exact tools and commands belong to the repository owner and must not be silently changed by an agent. + +## Attribution and Audit + +Record meaningful actions through repository-visible commits, PRs, reviews, ADRs, and audit artifacts. Records should include timestamp, contributor, branch, commit, action, result, and digest when configured. + +Line-level or function-level attribution is optional unless required by the owner; ordinary Git history remains the default source of authorship. Do not imply cryptographic verification where only metadata exists. + +## Rollback Certificate + +Every protected-branch merge should record: -## Reviewers -Required: -- Human owner -- Security review -- CI approval +```yaml +rollback: + merged_commit: "" + previous_commit: "" + migration_required: false + database_impact: none + risk: low + rollback_steps: [] ``` -## Audit Requirements -Every meaningful action should produce: -- timestamp -- actor -- branch -- commit -- action -- result -- hash +## Risk Assessment -Example: -```json -{ - "actor": "agent-codex", - "action": "pull_request_created", - "branch": "feat/gateone-ai-control-plane", - "status": "pending_review", - "integrity": "sha512" -} +PRs should assess security, architecture, tests, complexity, dependencies, secrets, supply chain, and documentation. Scores are advisory unless the owner explicitly makes them merge gates. + +## AI and Automation Rules + +Every AI or automation contributor must explain changes, state assumptions and uncertainty, report only tests actually run, identify external references, respect permissions, and never bypass review or self-approve a merge. + +## Repository Memory + +Issues, PRs, ADRs, tests, reviews, provenance, and rollback records provide the repository's durable engineering context. This does not authorize external synchronization or cloud storage. + +## Required PR Sections + +```md +## Summary +## Motivation +## Security Impact +## Local Validation +## Optional Cloud Validation +## Provenance +## Risk Assessment +## Rollback +## Required Reviewers ``` ## Goal -Maintain a transparent, reversible, multi-agent engineering environment where every change is attributable, reviewable, and recoverable. + +Provide transparent, reviewable, owner-controlled collaboration without forced cloud dependencies, hidden execution, automatic data export, or autonomous merge authority.