Skip to content

README.md

Latest commit

 

History

History
184 lines (137 loc) · 7.66 KB

README.md

File metadata and controls

184 lines (137 loc) · 7.66 KB

GitHub Optimization

Status: Active

Shelf version: 1.1.14 (regulation/shelf/SHELF_VERSION.md)

What This Repository Is

Generic regulation shelf for public-repository self-check.

The responsible AI reads this shelf, executes evidence against a target repository, scores 46 gates, and writes results under audits/<repository-slug>/ on disk. This is not a human-operated checklist.

Role Action
Responsible AI read regulation, run scripts, score gates, write audit artifacts
Human optional publication approval; not default command execution

What This Repository Is Not

Not for Reason
audit reports in product repos scored artifacts belong in audits/<slug>/ here
live project examples (VEIL_*, ADOP_*, …) generic shelf only; see domain-option/ templates
copying this folder into public product repos unless the product documents shared governance
filled records under docs/governance/ pointer only; canonical path is audits/<slug>/

Start Here

  1. regulation/REGULATION_SELF_CHECK.md — assignment to the responsible AI
  2. regulation/REGULATION_INDEX.md — required regulation files
  3. regulation/execution/AUDIT_RUNBOOK.md — execution order
  4. regulation/gates/GATE_REGISTRY.md — all 46 judgment items
  5. templates/audit-report.md.template — output skeleton

One-line assignment:

Read $GITHUB_OPTIMIZATION_ROOT (or ../github-optimization relative to the target repo), self-assess whether the target repository complies with this regulation, execute evidence, and complete the audit report.

Execution Pipeline

Run in this order unless RE_AUDIT_POLICY.md limits scope to a delta.

Step Script Purpose
1 scripts/run-full-audit.* shelf validate + scaffold + evidence (orchestrator)
2 scripts/validate-regulation-index.* required-file index check (shelf self-proof)
3 scripts/collect-audit-evidence.* machine evidence bundle
4 scripts/check-tracked-files.* unnecessary tracked-file screening (G-03, G-21)
5 scripts/check-gitignore-consistency.* tracked vs .gitignore consistency (G-04)
6 scripts/run-audit-quickstart.* audit.manifest.yml quickstart (R-08, R-09)
7 scripts/run-delta-audit.* delta re-audit when prior report exists

Script reference and usage examples: scripts/README.md

Regression tests after shelf edits:

.\scripts\tests\run-regulation-tests.ps1
./scripts/tests/run-regulation-tests.sh

Audit Modes And Tiers

Tier Gate file Count When required
1 regulation/gates/PUBLIC_PREP_GATE.md 22 always
2 regulation/gates/RELEASE_QUALITY_GATE.md 14 release, strict-product
3 regulation/gates/PRODUCT_READINESS_GATE.md 10 strict-product only
Audit mode Tiers evaluated
public-prep Tier 1
release Tier 1 + 2
strict-product Tier 1 + 2 + 3

Read: regulation/execution/SCOPE_AND_TIERS.md

Final label: regulation/gates/FULL_AUDIT_VERDICT.md

Repository Layout

README.md, LICENSE, SECURITY.md, CHANGELOG.md, …   # entry and shelf metadata
audit.manifest.yml                                 # shelf self-check quickstart only
regulation/                                        # all regulation text
checklists/  templates/  scripts/
docs/governance/README.md                          # pointer; no filled records
audits/                                            # local audit results (gitignored)
.github/workflows/ci.yml                         # shelf CI
.github/workflows/codeql.yml                     # code scanning (G-18)
domain-option/                                     # copy templates only (excluded from regulation)

Output Locations

The responsible AI writes audit artifacts under audits/<slug>/ in this shelf. Do not write scored audit reports into public product repositories.

Artifact Path
audit report audits/<slug>/audit-report.md
delta audit record audits/<slug>/delta-audit-record.md
publication decision record audits/<slug>/publication-decision-record.md
Tier 2 defer record audits/<slug>/tier2-defer-record.md
accepted risk record audits/<slug>/accepted-risk-record.md
GitHub execution packet audits/<slug>/github-execution-packet.md
audit quickstart manifest <product-repo-root>/audit.manifest.yml (product repos only)
governance pointer docs/governance/README.md (this shelf; not a filled record)

Read: regulation/shelf/OUTPUT_PATHS.md, audits/README.md

Quickstart Contract (R-08, R-09)

Target Quickstart source
Product repository audit.manifest.yml at product root (templates/audit.manifest.yml.template)
No manifest agent derives commands from product README.md and records transcript
This shelf (self-check) root audit.manifest.yml runs validate-index, tracked-file screening, gitignore consistency

Manifest fields: run_windows / run_unix per regulation/reference/AUDIT_MANIFEST_POLICY.md

Regulation Scope

Required files: regulation/REGULATION_INDEX.md

Excluded from self-check unless explicitly assigned:

  • domain-option/**
  • roadmap/**, design/**, tasks/**
  • project-specific execution records

Reference Map

Topic File
Agent execution model regulation/execution/AGENT_EXECUTION_MODEL.md
Validity rules regulation/execution/AUDIT_RULES.md
Audit phase regulation/execution/AUDIT_PHASE_POLICY.md
Re-audit / delta regulation/execution/RE_AUDIT_POLICY.md
Multi-repo batch regulation/execution/MULTI_REPO_ORCHESTRATION.md
Repo classification regulation/reference/REPO_CONTENT_CLASSIFICATION.md
Tracked-file screening regulation/reference/TRACKED_FILE_SCREENING.md
Gitignore consistency regulation/reference/GITIGNORE_CONSISTENCY.md
Tool decisions regulation/reference/TOOL_VERIFICATION_MATRIX.md
Tool review cadence regulation/reference/TOOL_REVIEW_CADENCE.md
Evidence commands regulation/reference/EVIDENCE_COMMANDS.md
Hosted settings regulation/reference/HOSTED_SETTINGS_BOUNDARY.md
Quickstart policy regulation/reference/AUDIT_MANIFEST_POLICY.md
Waivers regulation/reference/WAIVER_POLICY.md
Subjective gates regulation/reference/JUDGMENT_GUIDE.md
Publication responsibility regulation/reference/PUBLICATION_RESPONSIBILITY_MODEL.md
Shelf path regulation/shelf/SHELF_PATH.md
Distribution regulation/shelf/SHELF_DISTRIBUTION.md
Completeness proof regulation/REGULATION_COMPLETENESS.md
Repair starters templates/*.template, checklists/*.md

Completion Standard

Self-check is complete when:

  • every file in regulation/REGULATION_INDEX.md Required set was used
  • every git ls-files entry in the target repo was read or explicitly excepted (G-21)
  • all 46 gate tables (G / R / P) are filled or marked n/a with reason
  • machine evidence is attached
  • waivers follow regulation/reference/WAIVER_POLICY.md
  • subjective gates follow regulation/reference/JUDGMENT_GUIDE.md
  • final label is assigned via FULL_AUDIT_VERDICT.md
  • open Blockers are listed as fix tasks

GitHub Remote Scope

The public remote keeps regulation files only:

  • gates, policies, checklists, templates, scripts, CI
  • not audit results (audits/** is gitignored except audits/README.md)
  • not shelf build history (design/, roadmap/, tasks/)

Shelf self-check: scripts/validate-regulation-index.*, scripts/tests/run-regulation-tests.*

Distribution and versioning: regulation/shelf/SHELF_DISTRIBUTION.md, regulation/shelf/SHELF_CHANGELOG.md