Collab/GitHub services

.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
+<type>/<contributor>/<issue-or-scope>
+```
+
+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.

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

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