diff --git a/.github/workflows/founder-approval-gate.yml b/.github/workflows/founder-approval-gate.yml new file mode 100644 index 0000000..658ef3c --- /dev/null +++ b/.github/workflows/founder-approval-gate.yml @@ -0,0 +1,157 @@ +name: Founder Approval Gate + +on: + pull_request_target: + types: [opened, reopened, synchronize, edited, labeled, unlabeled] + issue_comment: + types: [created, edited, deleted] + +permissions: + contents: read + issues: write + pull-requests: write + +jobs: + founder-approval: + if: >- + github.event_name == 'pull_request_target' || + (github.event_name == 'issue_comment' && github.event.issue.pull_request) + runs-on: ubuntu-latest + env: + FOUNDER_APPROVER_LOGIN: ${{ vars.FOUNDER_APPROVER_LOGIN }} + + steps: + - name: Check governed paths and founder authorization + uses: actions/github-script@v7 + with: + script: | + const owner = context.repo.owner; + const repo = context.repo.repo; + const pull_number = context.issue.number; + const founderLogin = process.env.FOUNDER_APPROVER_LOGIN || 'altmanAI'; + const approvalPhrase = 'All Clear for Impact'; + const marker = ''; + + const { data: pull } = await github.rest.pulls.get({ + owner, + repo, + pull_number, + }); + + const files = await github.paginate( + github.rest.pulls.listFiles, + { owner, repo, pull_number, per_page: 100 }, + ); + + const governedRootFiles = new Set([ + 'GOVERNANCE.md', + 'SECURITY.md', + 'CONTRIBUTING.md', + 'CODE_OF_CONDUCT.md', + 'AI_SYSTEMS_POLICY.md', + 'VERSION', + 'CHANGELOG.md', + 'package.json', + 'pyproject.toml', + 'Cargo.toml', + 'go.mod', + ]); + + const requiresFounderApproval = files.some(({ filename }) => { + return ( + governedRootFiles.has(filename) || + filename.startsWith('docs/') || + filename.startsWith('profile/') || + filename.startsWith('.github/workflows/') || + filename.startsWith('.github/ISSUE_TEMPLATE/') || + filename === '.github/pull_request_template.md' || + /(^|\/)(release|version)(\.|\/|$)/i.test(filename) + ); + }); + + if (!requiresFounderApproval) { + core.notice('No governed paths detected. Founder approval gate is not required.'); + return; + } + + const comments = await github.paginate( + github.rest.issues.listComments, + { owner, repo, issue_number: pull_number, per_page: 100 }, + ); + + const exactPhrasePattern = /(?:^|\n)\s*All Clear for Impact\s*(?:\n|$)/; + const approvalComment = comments.find((comment) => { + return ( + comment.user?.login === founderLogin && + exactPhrasePattern.test(comment.body || '') + ); + }); + + const changedGovernedFiles = files + .map(({ filename }) => filename) + .filter((filename) => { + return ( + governedRootFiles.has(filename) || + filename.startsWith('docs/') || + filename.startsWith('profile/') || + filename.startsWith('.github/workflows/') || + filename.startsWith('.github/ISSUE_TEMPLATE/') || + filename === '.github/pull_request_template.md' || + /(^|\/)(release|version)(\.|\/|$)/i.test(filename) + ); + }); + + const status = approvalComment ? 'APPROVED' : 'PENDING'; + const checklist = [ + marker, + '## Founder approval gate', + '', + `**Status:** ${status}`, + `**Required approver:** @${founderLogin}`, + '', + 'This pull request changes governance-sensitive, documentation, workflow, profile, release, or version-controlled paths.', + '', + '- [ ] Evidence and validation are linked in the pull request', + '- [ ] AI assistance is disclosed', + '- [ ] P.A.I.H.I. review is complete', + '- [ ] Rollback or correction plan is documented', + `- [${approvalComment ? 'x' : ' '}] Founder posted the exact standalone phrase: **${approvalPhrase}**`, + '', + '
Governed files detected', + '', + ...changedGovernedFiles.map((filename) => `- \`${filename}\``), + '', + '
', + '', + approvalComment + ? `Approval record: ${approvalComment.html_url}` + : 'Approval must be a visible pull-request comment from the configured founder account. The workflow cannot create or infer approval.', + ].join('\n'); + + const priorGateComment = comments.find( + (comment) => comment.user?.type === 'Bot' && comment.body?.includes(marker), + ); + + if (priorGateComment) { + await github.rest.issues.updateComment({ + owner, + repo, + comment_id: priorGateComment.id, + body: checklist, + }); + } else { + await github.rest.issues.createComment({ + owner, + repo, + issue_number: pull_number, + body: checklist, + }); + } + + if (!approvalComment) { + core.setFailed( + `Founder approval required. @${founderLogin} must post the exact standalone phrase: ${approvalPhrase}`, + ); + } else { + core.info(`Founder approval verified at ${approvalComment.html_url}`); + } diff --git a/CREDIBILITY_SCORECARD.md b/CREDIBILITY_SCORECARD.md new file mode 100644 index 0000000..4bbbd54 --- /dev/null +++ b/CREDIBILITY_SCORECARD.md @@ -0,0 +1,209 @@ +# AltmanAI Credibility Scorecard + +**Baseline audit date:** July 13, 2026 +**Scope:** 14 public repositories currently visible under `github.com/altmanAI` +**Active compliance denominator:** 13 repositories +**Archived/historical:** 1 repository (`PAIHI-Portables`) +**Status:** Baseline assessment — not a certification or external audit + +> Credibility is not claimed. It is supported by inspectable evidence, limitations, decision records, and accountable human approval. + +## Executive finding + +AltmanAI's organization-level policy layer is materially stronger than its repository-level enforcement layer. + +The organization already publishes governance, security, contribution, conduct, AI-assistance, P.A.I.H.I., rollback, and founder-approval expectations. The primary credibility gap is that evidence remains distributed across README files, tests, manifests, pull requests, and registry artifacts instead of being indexed through consistent `GOVERNANCE.md`, `PROOF.md`, and `DECISION_LOG.md` files in each strategic repository. + +The active-portfolio baseline is **62.4/100** under the methodology below. This means the organization has a meaningful governance foundation, but it has not yet demonstrated consistent, automated, repo-level enforcement. + +## Scoring method + +| Dimension | Weight | What earns credit | +|---|---:|---| +| Governance adherence | 20 | Organization baseline, repo-specific authority, change classes, escalation and rollback rules | +| Proof density | 25 | Tests, CI, reproducible commands, artifacts, citations, limitations and claim-to-evidence mapping | +| P.A.I.H.I. implementation | 25 | Proof, Alignment, Integrity, Humanity and Impact demonstrated in the repository | +| AI-assistance disclosure | 15 | Material PRs identify the system, assistance type, human verification and limitations | +| Founder approval trail | 15 | Attributable approval record containing `All Clear for Impact` for material or governance-critical changes | + +Ratings: + +- **Strong:** 80–100 +- **Substantial:** 70–79 +- **Developing:** 50–69 +- **Foundational:** below 50 +- **Archived:** excluded from active compliance calculations + +Scores are conservative. Anything not directly verified during this baseline is treated as unverified rather than compliant. + +## Public repository scorecard + +| Repository | Positioning | Score | Rating | Verified evidence | Primary gap | +|---|---|---:|---|---|---| +| `.github` | Active governance layer | 86 | Strong | Organization governance, security, contribution rules, conduct rules, PR template, recent AI disclosures and founder approvals | Approval rules are not yet enforced automatically | +| `canon-charter-v1` | Frozen canonical artifact | 82 | Strong | Repo governance, manifest, P.A.I.H.I. record, verification script, CI, changelog, version and approval phrase | No root `PROOF.md`; legacy AI label remains in a minted record | +| `human-first-ai` | Working reference implementation | 79 | Substantial | Runnable architecture, tests, P.A.I.H.I. scorer, explicit limitations and founder approval | Material PR omitted explicit AI-system identity; no root `PROOF.md` | +| `AltmanAI-Impact-Explorer` | Early full-stack implementation | 76 | Substantial | FastAPI/React structure, basic tests, public-data boundary and a disclosed correction PR | Dependency and deployment evidence not fully indexed; no root `PROOF.md` | +| `altmanai-sdk` | Initial public foundation | 63 | Developing | Cross-language structure, schemas, hashing/verification utilities, test commands and status labels | Production adoption and parity are not independently demonstrated; no root `PROOF.md` | +| `altmanai-master-ledger` | Active proof layer | 62 | Developing | Public ledger/registry structure, schemas, receipts and selected approval records | Evidence is partly self-attested and lacks one claim-to-artifact index | +| `DailyPilot-Engine` | Working reference implementation | 62 | Developing | Runnable Python CLI, named modules, test command and explicit production limitation | CI/coverage/privacy/accessibility evidence is not indexed; no root `PROOF.md` | +| `altmanai-masterplan` | Active execution map | 61 | Developing | Portfolio maturity labels, priorities, evidence-over-roadmap rule and founder approval requirement | No repo-specific governance, proof or decision log verified | +| `altmanai-alt-seal` | Governance and verification asset | 57 | Developing | Published hashes, Save-Receipt artifacts, local verifier and scope limitations | Internally defined trust standard lacks independent validation and decision log | +| `releaseshield-by-altmanai` | v0.1 product development | 50 | Developing | Clear scope, preliminary detection limitations, human review and proof-report design | Feature descriptions precede demonstrated working CLI/Action evidence | +| `docs` | Active documentation | 45 | Foundational | Structured docs source, preview command and organization contribution routing | Published-site parity, accessibility and product-feature accuracy are not evidenced | +| `paihi-framework` | Active development | 45 | Foundational | Development status, framework dimensions, human-authorization principles and reference implementation link | Organization-wide enforcement claims exceed currently demonstrated controls | +| `altmanai-public-hub` | Active public entry point | 43 | Foundational | Clear company purpose, product direction, contacts and current/developing labels | Product and impact claims are weakly linked to code, tests and measurable outcomes | +| `PAIHI-Portables` | Archived and consolidated | 40 | Archived | Honest archive notice states there was no working code and routes users to the SDK | Historical repository; excluded from active compliance denominator | + +## Governance adherence + +The `.github` repository supplies organization-level defaults for security reporting, contribution rules and conduct. It also declares its governance policy as the baseline for repositories without an approved local policy. + +However, GitHub community-health inheritance is not equivalent to a repo-specific authority map. Strategic repositories still need local rules for: + +- what counts as routine, material, security-sensitive and governance-critical; +- who may approve each change class; +- which files and release actions trigger founder approval; +- incident escalation and rollback criteria; +- the objective or masterplan record served by the repository. + +## Proof density + +Concrete proof is strongest in: + +1. `canon-charter-v1` — manifests, verification tooling and CI; +2. `human-first-ai` — runnable reference code, tests and reproducible P.A.I.H.I. scoring; +3. `altmanai-sdk` — schemas, cross-language foundations and deterministic artifact tooling; +4. `DailyPilot-Engine` — working CLI, scoring modules and tests; +5. `AltmanAI-Impact-Explorer` — full-stack structure and basic API tests. + +A root-level `PROOF.md` was not found in nine sampled strategic repositories: `altmanai-masterplan`, `altmanai-master-ledger`, `DailyPilot-Engine`, `altmanai-sdk`, `human-first-ai`, `releaseshield-by-altmanai`, `AltmanAI-Impact-Explorer`, `paihi-framework`, and `canon-charter-v1`. + +This does not mean those repositories have no evidence. It means the evidence is not yet normalized into a claim-to-proof index. + +## P.A.I.H.I. findings + +### Proof + +Tests, manifests, hashes and verification scripts exist in several repositories, but there is no organization-wide evidence threshold or conformance suite. + +### Alignment + +The current masterplan provides a clear portfolio map. Repo-specific links to formal objectives remain inconsistent. + +### Integrity + +Recent cleanup work has improved maturity labels and removed or corrected unsupported positioning. Remaining target-state language must stay distinguishable from shipped capability. + +### Humanity + +Human authorization is a documented principle. Accessibility, privacy, recourse and user-impact audits are not yet consistently evidenced per repository. + +### Impact + +Several repositories describe intended outcomes, but measurable success metrics and post-release observations are not consistently defined. + +## AI-assistance disclosure spot check + +The three-repository recent-PR spot check covered `.github`, `AltmanAI-Impact-Explorer`, and `human-first-ai`. + +| Repository | Material PRs reviewed | Result | +|---|---:|---| +| `.github` | 5 founder-authored material/governance PRs | Recent material PRs consistently identify AltmanAI Model 2.0 and human authorization; one cleanup PR requested approval but did not contain an explicit AI-system disclosure | +| `AltmanAI-Impact-Explorer` | 1 material human-authored correction PR | AI assistance and `All Clear for Impact` are explicit | +| `human-first-ai` | 1 material code/governance PR | Tests and founder approval are explicit; the assisting AI system is not named | + +**Confirmed correction item:** create a public correction record for the `human-first-ai` disclosure gap rather than rewriting history silently. + +Dependabot or automated dependency PRs should identify the automation source through GitHub metadata and are evaluated separately from human/AI-authored material changes. + +## Founder approval trail + +Visible approval records exist in recent governance, identity, canonical and material code changes. The phrase is currently a manual convention, not an enforced merge requirement. + +This baseline proposes a path-sensitive GitHub Action that requires an attributable comment containing exactly: + +> **All Clear for Impact** + +The workflow must not manufacture or automate founder approval. + +## Security and dependency posture + +### Public-safe finding + +A July 5, 2026 code-search sweep reported no exposed-secret hits, with an explicit warning that code-search indexing can lag. + +### Current limitation + +No new package-manager dependency audit, native GitHub secret-scanning verification, dependency-review run or third-party secret scan was completed as part of this connector-based baseline. Therefore: + +- this report does **not** claim zero vulnerabilities; +- this report does **not** certify that no secret has ever been committed; +- production repositories require live ecosystem-specific scans before the security success criteria can be checked. + +Sensitive findings, if discovered, must be reported privately under `SECURITY.md` and must not be added to this public scorecard before remediation. + +## Top 10 hardening scope + +The current strategic top 10 for the credibility initiative are: + +1. `.github` +2. `altmanai-masterplan` +3. `altmanai-master-ledger` +4. `paihi-framework` +5. `human-first-ai` +6. `altmanai-sdk` +7. `DailyPilot-Engine` +8. `releaseshield-by-altmanai` +9. `AltmanAI-Impact-Explorer` +10. `canon-charter-v1` + +`PAIHI-Portables` is archived and is not treated as an active strategic implementation target. + +## Mandatory repository deliverables + +Each top-10 repository must add or explicitly link: + +- `GOVERNANCE.md` +- `PROOF.md` or `EVIDENCE.md` +- `DECISION_LOG.md` +- dependency and supply-chain posture +- secret-scanning posture +- AI-assistance disclosure requirements +- explicit success metrics and limitations +- rollback and incident-escalation rules + +## Immediate correction queue + +1. Add founder-approval enforcement to the organization workflow. +2. Create the `human-first-ai` AI-disclosure correction record. +3. Add `PROOF.md` to the first implementation wave: `human-first-ai`, `altmanai-sdk`, `DailyPilot-Engine`, `ReleaseShield`, and `Impact-Explorer`. +4. Recast target-state enforcement language in `paihi-framework` until conformance checks exist. +5. Run dependency and secret scans and publish only remediated, public-safe summaries. +6. Add measurable outcome definitions to product and public-facing repositories. + +## Monthly publication standard + +Future revisions should publish: + +- audit date and exact repository denominator; +- score changes and methodology changes; +- new evidence and validation links; +- corrected or removed claims; +- unresolved high-risk gaps; +- dependency/security status at a public-safe level; +- material PR disclosure compliance; +- founder approvals for governance-critical changes. + +## Approval status + +This scorecard is proposed on a review branch. + +**Merge status:** Pending explicit Founder approval. +**Required phrase:** `All Clear for Impact` + +--- + +**Owner:** AltmanAI Model 2.0 — audit execution and evidence scaffolding +**Accountable human authority:** Blake Hunter Altman, Founder & CEO +**Company:** AltmanAI by Altman Family Group LLC, Pittsburgh, Pennsylvania \ No newline at end of file diff --git a/audits/2026-Q3-CREDIBILITY-REPORT.md b/audits/2026-Q3-CREDIBILITY-REPORT.md new file mode 100644 index 0000000..8b84ef1 --- /dev/null +++ b/audits/2026-Q3-CREDIBILITY-REPORT.md @@ -0,0 +1,119 @@ +# AltmanAI Q3 2026 Credibility Report — Baseline + +**Report date:** July 13, 2026 +**Reporting period:** Q3 2026 baseline +**Scope:** Current public AltmanAI GitHub portfolio +**Status:** Proposed; pending Founder approval before merge + +## Executive summary + +AltmanAI has established a substantive organization-level governance framework, but repo-level evidence and automated enforcement remain inconsistent. + +The current public portfolio contains **14 repositories**: **13 active** and **1 archived**. The active baseline averages **62.4/100** under the public credibility methodology in [`CREDIBILITY_SCORECARD.md`](../CREDIBILITY_SCORECARD.md). + +This score is not an external certification. It measures the currently inspectable presence of governance, proof, P.A.I.H.I. implementation, AI-assistance disclosure, and founder approval records. + +## Portfolio status + +| Metric | Baseline | +|---|---:| +| Public repositories inventoried | 14 | +| Active repositories in compliance denominator | 13 | +| Archived repositories | 1 | +| Active average credibility score | 62.4/100 | +| Repositories scoring 70 or higher | 4 | +| Sampled strategic repositories with root `PROOF.md` | 0 of 9 | +| Confirmed material AI-disclosure gaps | 1 | +| Current dependency vulnerability status | Unverified | +| Current dedicated secret-scan status | Unverified | +| External audit completed | No | + +## Strongest current evidence + +### `.github` + +Organization-level governance, security policy, contribution rules, conduct policy, AI-system policy, issue forms, and a detailed pull-request template are published. Recent material governance PRs generally contain explicit AI-assistance disclosure and founder authorization. + +### `canon-charter-v1` + +The repository includes local governance, a manifest, a P.A.I.H.I. record, verification tooling, CI, versioning, a changelog, and a visible approval statement. It is the most complete artifact-integrity repository in the current portfolio. + +### `human-first-ai` + +The repository presents a runnable P.A.I.H.I. reference architecture with tests and a reproducible scoring demonstration. The implementation is explicitly labeled early and minimal rather than production-complete. + +### `AltmanAI-Impact-Explorer` + +The repository describes a concrete full-stack implementation and basic tests. Its material metadata-correction PR preserved the integrity trail while explicitly disclosing AltmanAI Model 2.0 assistance and founder authorization. + +## Confirmed gaps + +1. **Evidence is scattered.** Nine sampled strategic repositories lacked a root-level `PROOF.md` even when tests, manifests, schemas, or PR evidence existed elsewhere. +2. **Approval is manual.** `All Clear for Impact` is a documented convention, but no required status check currently verifies that an attributable founder comment exists for governed paths. +3. **AI disclosure is not universal.** The material `human-first-ai` PR reviewed in this baseline included test evidence and founder approval but did not name the assisting AI system. +4. **Dependency posture is unverified.** No current ecosystem-specific dependency scans were executed in this connector-based baseline. +5. **Secret posture is provisional.** A prior code-search sweep reported no hits, but code search is not a substitute for native or dedicated secret scanning. +6. **Outcome metrics are weak.** Product and public-facing repositories often describe intended value without defining measurable success or observed post-release impact. +7. **Framework language exceeds enforcement.** `paihi-framework` contains target-state language that implies organization-wide assurance before conformance checks and repo-level evidence are consistently deployed. + +## Corrections and integrity actions + +### Required public correction + +Create a correction issue or decision-log entry for the missing AI-system identity in the material `human-first-ai` PR. Preserve the original PR history; do not rewrite it to create the appearance that disclosure was present at merge time. + +### Required language correction + +Revise P.A.I.H.I. target-state claims so they distinguish: + +- the framework's intended standard; +- controls currently implemented in code; +- controls adopted by specific repositories; +- controls not yet enforced organization-wide. + +## Foundational work proposed in this change set + +- publish `CREDIBILITY_SCORECARD.md`; +- publish this Q3 2026 baseline report; +- add a path-sensitive founder approval workflow; +- open a reviewable PR rather than merging directly; +- preserve the exact human approval phrase as a manual founder decision. + +## Next reporting targets + +The next credibility report should measure: + +- top-10 adoption of `GOVERNANCE.md`, `PROOF.md`, and `DECISION_LOG.md`; +- material PR AI-disclosure compliance over the prior 90 days; +- test and coverage evidence for active code repositories; +- dependency and secret-scanning results at a public-safe level; +- corrected or removed public claims; +- open critical issues and remediation status; +- accessibility, privacy, recourse, and human-impact evidence; +- external validation progress. + +## Success-criteria status + +| Criterion | Q3 baseline status | +|---|---| +| Top 10 have governance + proof + decision log | Not met | +| Material PRs in prior 90 days have AI disclosure | Not met; one confirmed gap | +| P.A.I.H.I. score at least 70% across top repos | Not established under a conformance audit | +| Zero unpatched critical production dependencies | Unverified | +| Founder approval recorded per material change | Partial; visible in several material PRs | +| External audit completed and published | Not met | +| Quarterly report published and verifiable | Proposed in this branch | + +## Approval record + +**Required before merge:** an attributable Founder comment containing the exact standalone phrase: + +> **All Clear for Impact** + +No AI system or workflow may generate, infer, or substitute this approval. + +--- + +**Audit execution:** AltmanAI Model 2.0 +**Accountable human authority:** Blake Hunter Altman, Founder & CEO +**Organization:** AltmanAI by Altman Family Group LLC \ No newline at end of file diff --git a/audits/credibility-scorecard-2026-07-13.csv b/audits/credibility-scorecard-2026-07-13.csv new file mode 100644 index 0000000..7e09770 --- /dev/null +++ b/audits/credibility-scorecard-2026-07-13.csv @@ -0,0 +1,15 @@ +repository,positioning,archived,governance_20,proof_25,paihi_25,ai_disclosure_15,founder_trail_15,total_100,rating,primary_gap +.github,Active governance layer,false,20,16,20,15,15,86,Strong,Approval rules are not yet enforced automatically +canon-charter-v1,Frozen canonical artifact,false,18,23,21,5,15,82,Strong,No root PROOF.md and legacy AI label remains in a minted record +human-first-ai,Working reference implementation,false,10,23,23,8,15,79,Substantial,Material PR omitted explicit AI-system identity and no root PROOF.md +AltmanAI-Impact-Explorer,Early full-stack implementation,false,10,19,17,15,15,76,Substantial,Dependency and deployment evidence are not fully indexed +altmanai-sdk,Initial public foundation,false,10,21,20,5,7,63,Developing,Production adoption and cross-language parity are not independently demonstrated +altmanai-master-ledger,Active proof layer,false,10,17,17,8,10,62,Developing,Evidence is partly self-attested and lacks one claim-to-artifact index +DailyPilot-Engine,Working reference implementation,false,10,21,19,5,7,62,Developing,CI coverage privacy and accessibility evidence are not indexed +altmanai-masterplan,Active execution map,false,10,14,18,9,10,61,Developing,No repo-specific governance proof or decision log verified +altmanai-alt-seal,Governance and verification asset,false,10,18,18,5,6,57,Developing,Internally defined trust standard lacks independent validation and decision log +releaseshield-by-altmanai,v0.1 product development,false,10,12,18,5,5,50,Developing,Feature descriptions precede demonstrated working CLI and Action evidence +docs,Active documentation,false,10,10,15,5,5,45,Foundational,Published-site parity accessibility and product-feature accuracy are not evidenced +paihi-framework,Active development,false,10,8,17,5,5,45,Foundational,Organization-wide enforcement claims exceed currently demonstrated controls +altmanai-public-hub,Active public entry point,false,10,8,15,5,5,43,Foundational,Product and impact claims are weakly linked to code tests and measurable outcomes +PAIHI-Portables,Archived and consolidated,true,8,15,12,0,5,40,Archived,Historical repository excluded from active compliance denominator diff --git a/templates/repository/DECISION_LOG.md b/templates/repository/DECISION_LOG.md new file mode 100644 index 0000000..4395f64 --- /dev/null +++ b/templates/repository/DECISION_LOG.md @@ -0,0 +1,101 @@ +# Repository Decision Log + +This log records material architecture, product, security, governance and public-positioning decisions. Routine maintenance does not require a full entry unless it changes risk, behavior or an approved claim. + +## Repository origin + +- **Repository:** `[owner/repository]` +- **Created to solve:** `[problem statement]` +- **Authorized objective:** `[link to masterplan, issue, RFC or master-ledger record]` +- **Initial accountable human:** `[name]` +- **Initial approval date:** `[YYYY-MM-DD]` +- **Initial AI assistance:** `[system and role or None]` + +## Decision index + +| ID | Date | Decision | Status | Decision class | Approver | Record | +|---|---|---|---|---|---|---| +| ADR-0001 | `[YYYY-MM-DD]` | `[short title]` | `[proposed | accepted | superseded | reversed]` | `[routine | material | security-sensitive | governance-critical]` | `[human name]` | `[issue/PR link]` | + +--- + +## ADR-0001 — `[Decision title]` + +- **Date:** `[YYYY-MM-DD]` +- **Status:** `[proposed | accepted | superseded | reversed]` +- **Decision class:** `[routine | material | security-sensitive | governance-critical | regulated/high-stakes]` +- **Author:** `[human or contributor]` +- **AI assistance:** `[system, role and limitations or None]` +- **Accountable approver:** `[human name]` +- **Approval record:** `[link; governance-critical records must contain All Clear for Impact]` +- **Related objective:** `[link]` +- **Related issue / PR:** `[link]` + +### Context + +What problem, constraint, evidence or change required a decision? + +### Decision + +State the decision precisely. Distinguish current implementation from planned work. + +### Alternatives considered + +| Alternative | Advantages | Disadvantages | Reason not selected | +|---|---|---|---| +| `[alternative]` | `[advantages]` | `[disadvantages]` | `[reason]` | + +### Evidence + +- Tests: +- Artifacts: +- Sources or citations: +- Security/privacy review: +- Human-impact review: +- External review: + +### P.A.I.H.I. assessment + +- **Proof:** +- **Alignment:** +- **Integrity:** +- **Humanity:** +- **Impact:** + +### Risks and limitations + +List known uncertainty, unresolved issues, failure modes and assumptions. + +### Rollback or correction criteria + +State the conditions that require reversal, containment, amendment or public correction. + +### Consequences + +#### Expected benefits + +- + +#### Costs and trade-offs + +- + +#### Follow-up work + +- [ ] `[task and owner]` + +### Revision history + +| Date | Change | Reason | Approver | Record | +|---|---|---|---|---| +| `[date]` | `[revision]` | `[reason]` | `[human]` | `[link]` | + +--- + +## Logging rules + +1. Never invent approval, evidence, reviewers, dates or external validation. +2. Do not silently rewrite an accepted decision when facts change; append a revision, superseding decision or correction. +3. Keep exploitable security details private while preserving a public-safe decision record. +4. Link decisions to `PROOF.md`, releases, incidents and corrections when applicable. +5. Governance-critical decisions require an attributable Founder approval record containing the exact phrase `All Clear for Impact`. diff --git a/templates/repository/DEPENDENCIES.md b/templates/repository/DEPENDENCIES.md new file mode 100644 index 0000000..2da6577 --- /dev/null +++ b/templates/repository/DEPENDENCIES.md @@ -0,0 +1,83 @@ +# Dependency and Supply-Chain Record + +> Public-safe inventory for major runtime, build, release and security-sensitive dependencies. Do not expose private infrastructure, credentials or exploitable details. + +## Repository + +- **Repository:** `[owner/repository]` +- **Primary ecosystems:** `[npm | Python | Go | Rust | other]` +- **Dependency owner:** `[maintainer]` +- **Last reviewed:** `[YYYY-MM-DD]` +- **Lockfile present:** `[yes/no/not applicable]` +- **Automated updates:** `[Dependabot/Renovate/other/not configured]` + +## Major dependency matrix + +| Dependency | Version / constraint | Type | Purpose | Risk level | Update source | Latest review | Notes | +|---|---|---|---|---|---|---|---| +| `[name]` | `[version]` | `[runtime | development | build | action | service]` | `[purpose]` | `[low | medium | high | critical]` | `[registry/release source]` | `[date]` | `[limitations or controls]` | + +Risk should consider: + +- privilege and data access; +- runtime or release criticality; +- maintainer and project health; +- transitive dependency exposure; +- native code or install scripts; +- network access and telemetry; +- package integrity and provenance; +- known vulnerabilities and patch availability; +- replacement difficulty and blast radius. + +## Scan posture + +| Control | Tool / provider | Trigger | Last run | Result | Evidence | +|---|---|---|---|---|---| +| Vulnerability scan | `[npm audit / pip-audit / osv-scanner / other]` | `[PR/push/schedule/manual]` | `[date]` | `[summary or unverified]` | `[workflow/report link]` | +| Dependency review | `[GitHub Dependency Review / other]` | `[PR]` | `[date]` | `[summary]` | `[link]` | +| Automated updates | `[Dependabot/Renovate]` | `[schedule]` | `[date]` | `[summary]` | `[link]` | +| Secret scan | `[GitHub native / gitleaks / trufflehog / other]` | `[trigger]` | `[date]` | `[public-safe summary]` | `[link]` | +| Action pinning | `[policy/tool]` | `[trigger]` | `[date]` | `[summary]` | `[link]` | + +## Current vulnerability status + +- **Critical unresolved:** `[count or unverified]` +- **High unresolved:** `[count or unverified]` +- **Accepted risk records:** `[links or none]` +- **Next required review:** `[date or release trigger]` + +Do not state zero vulnerabilities unless the applicable ecosystems and lockfiles were scanned and the evidence is linked. + +## GitHub Actions and release dependencies + +| Action / service | Reference | Pinning | Permissions | Purpose | Risk / mitigation | +|---|---|---|---|---|---| +| `[action]` | `[tag or SHA]` | `[tag/SHA]` | `[permissions]` | `[purpose]` | `[risk and control]` | + +Workflows should use minimum required permissions. Third-party actions should be pinned to a reviewed commit SHA where practical for security-sensitive or release workflows. + +## External services + +| Service | Data shared | Authentication | Failure mode | Exit / fallback | Owner | +|---|---|---|---|---|---| +| `[service]` | `[data categories]` | `[method]` | `[failure impact]` | `[fallback]` | `[owner]` | + +## Exception and risk acceptance + +A high or critical dependency risk may be accepted only through a traceable decision record that includes: + +- business or technical justification; +- affected versions and scope; +- compensating controls; +- expiration or review date; +- accountable human approver; +- rollback or replacement plan; +- security-sensitive handling where applicable. + +Governance-critical or material exceptions require Founder authorization under repository governance. + +## Change log + +| Date | Change | Reason | Evidence | Approver | +|---|---|---|---|---| +| `[date]` | `[dependency or policy change]` | `[reason]` | `[PR/scan link]` | `[human]` | diff --git a/templates/repository/GOVERNANCE.md b/templates/repository/GOVERNANCE.md new file mode 100644 index 0000000..5d7d6d8 --- /dev/null +++ b/templates/repository/GOVERNANCE.md @@ -0,0 +1,103 @@ +# Repository Governance + +> Replace every bracketed field before adoption. Delete guidance comments after review. + +## Repository identity + +- **Repository:** `[owner/repository]` +- **Status:** `[working | reference | foundation | experimental | historical | planned]` +- **Strategic objective:** `[link to altmanai-masterplan objective, issue, RFC or master-ledger record]` +- **Accountable owner:** Blake Hunter Altman, Founder & CEO +- **Maintainers:** `[names or GitHub handles]` +- **Last reviewed:** `[YYYY-MM-DD]` + +## Purpose and authority boundary + +This repository exists to `[state the authorized problem and intended users]`. + +It does not authorize maintainers, contributors or AI systems to make company-wide legal, financial, employment, partnership, security-exception or public-positioning commitments unless a separately approved record grants that authority. + +## Decision classes + +| Class | Examples | Minimum approval | +|---|---|---| +| Routine | Typos, link fixes, formatting, low-risk maintenance | Maintainer review and required checks | +| Material | Features, public claims, architecture, data handling, dependencies, releases | Evidence, tests, risk review and authorized human approval | +| Security-sensitive | Authentication, authorization, secrets, cryptography, permissions, incident controls | Security review and accountable maintainer approval; private handling where necessary | +| Governance-critical | This file, security policy, contribution rules, canonical records, authority model | Founder approval with `All Clear for Impact` before merge | +| Regulated/high-stakes | Legal rights, health, employment, credit, finance, safety or government decisions | Appropriate specialist review plus Founder authorization | + +When classification is uncertain, use the higher class. + +## Path and change controls + +| Path or change type | Required review | +|---|---| +| `GOVERNANCE.md`, `SECURITY.md`, `CONTRIBUTING.md` | Governance-critical | +| `/docs`, public profile or product claims | Material; Founder approval when positioning or canonical policy changes | +| Release, version or package publication | Material; release evidence and rollback plan required | +| Dependency or workflow changes | Material or security-sensitive according to risk | +| Credentials, private data or exploitable findings | Never publish; follow `SECURITY.md` | + +## Required proposal record + +Material changes must identify: + +1. authorized objective and related issue or decision; +2. scope and non-goals; +3. evidence, tests or validation; +4. limitations and uncertainty; +5. security, privacy, accessibility and human-impact risks; +6. AI-assistance disclosure; +7. rollback or correction plan; +8. accountable human approver. + +## P.A.I.H.I. review + +- **Proof:** What evidence supports the change and what remains unverified? +- **Alignment:** Which approved objective does it serve? +- **Integrity:** Are status, limitations, uncertainty and assistance disclosed accurately? +- **Humanity:** Does it preserve human control, dignity, privacy, accessibility, safety and recourse? +- **Impact:** What measurable outcome should result and how will it be observed? + +## AI-assistance disclosure + +Material AI assistance must be disclosed in the pull request: + +> **AI Assistance:** `[system name]` assisted with `[research | drafting | code | tests | review | documentation | other]`. Verified by `[human name]` on `[YYYY-MM-DD]`. Known limitations: `[limitations]`. + +AI systems do not independently approve or merge material changes. + +## Founder approval + +Governance-critical changes require an attributable Founder comment containing the exact standalone phrase: + +> **All Clear for Impact** + +Approval does not waive evidence, tests, security, privacy, legal, licensing or correction obligations. + +## Rollback criteria + +A change must be rolled back, disabled or corrected when: + +- it creates a critical security or privacy risk; +- a material public claim proves unsupported; +- required evidence or approval was absent; +- production behavior materially differs from the approved scope; +- user harm, loss of control or significant accessibility failure is observed; +- a dependency or external service becomes unsafe or unavailable. + +The rollback record must link the original decision and explain impact, containment and follow-up. + +## Incident escalation + +1. Stop or contain the affected behavior when safe. +2. Preserve logs and evidence without exposing secrets or personal data. +3. Notify the accountable maintainer and Founder. +4. Use the private security channel for exploitable details. +5. Record the public-safe correction or incident summary when disclosure is appropriate. +6. Update `PROOF.md`, `DECISION_LOG.md`, changelog and affected claims. + +## Amendments + +Changes to this document are governance-critical and require a dedicated pull request, AI-assistance disclosure, evidence, and explicit Founder approval. diff --git a/templates/repository/PROOF.md b/templates/repository/PROOF.md new file mode 100644 index 0000000..1129059 --- /dev/null +++ b/templates/repository/PROOF.md @@ -0,0 +1,108 @@ +# Repository Proof and Evidence + +> This file maps public claims to reproducible evidence. Do not mark a claim verified unless the cited evidence supports the exact wording and scope. + +## Repository status + +- **Repository:** `[owner/repository]` +- **Current maturity:** `[working | reference | foundation | experimental | historical | planned]` +- **Evidence owner:** `[human name or maintainer]` +- **Last verified:** `[YYYY-MM-DD]` +- **Related objective:** `[masterplan, issue, RFC or master-ledger link]` + +## Claim-to-evidence matrix + +| ID | Public claim | Status | Evidence | How to reproduce or validate | Limitations / gaps | Human verifier | Last checked | +|---|---|---|---|---|---|---|---| +| C-001 | `[exact README, description or documentation claim]` | `[verified | partially verified | unverified | corrected | retired]` | `[tests, artifact, citation, release, review or log]` | `[commands or review steps]` | `[scope, uncertainty or missing evidence]` | `[name]` | `[date]` | + +## Test and validation evidence + +| Check | Command or workflow | Expected result | Latest verified result | Evidence link | +|---|---|---|---|---| +| Unit tests | `[command]` | `[expected]` | `[result/date]` | `[CI run or PR]` | +| Integration tests | `[command]` | `[expected]` | `[result/date]` | `[CI run or PR]` | +| Coverage | `[command]` | `[threshold]` | `[percentage/date]` | `[report]` | +| Build | `[command]` | `[expected]` | `[result/date]` | `[CI run or release]` | +| Manual validation | `[steps]` | `[expected]` | `[result/date]` | `[record]` | + +Do not list a coverage percentage unless a reproducible report exists. + +## Artifact and provenance evidence + +| Artifact | Version or identifier | SHA-256 / digest | Source | Verification procedure | Status | +|---|---|---|---|---|---| +| `[artifact]` | `[version]` | `[digest]` | `[release or repository path]` | `[command or verifier]` | `[verified / unverified]` | + +A hash proves byte-level integrity relative to the recorded digest. It does not independently prove truth, safety, legality, quality, authorship or external validation. + +## P.A.I.H.I. evidence + +### Proof + +- Evidence produced: +- Independent or external validation: +- Unverified areas: + +### Alignment + +- Approved objective: +- Repository scope: +- Out-of-scope uses: + +### Integrity + +- Known limitations: +- Uncertainty ranges: +- Conflicts or incentives: +- Material AI assistance: + +### Humanity + +- Human checkpoints: +- Privacy/data handling: +- Accessibility evidence: +- Safety and recourse: +- Known human-impact risks: + +### Impact + +- Intended measurable outcome: +- Success metric: +- Failure metric: +- Observation period: +- Latest observed result: + +## Security and dependency evidence + +Public-safe summary only. Do not publish unremediated exploit details, secrets, credentials, private infrastructure or personal data. + +- **Secret scanning:** `[GitHub native | gitleaks | trufflehog | manual | not configured]` +- **Dependency scanning:** `[Dependabot | npm audit | pip-audit | osv-scanner | other | not configured]` +- **Last scan date:** `[YYYY-MM-DD]` +- **Critical unresolved vulnerabilities:** `[number or unverified]` +- **Security policy:** `[link]` +- **Supply-chain record:** [`DEPENDENCIES.md` link] + +## External validation + +| Reviewer / organization | Scope | Date | Finding | Public report | +|---|---|---|---|---| +| `[reviewer]` | `[scope]` | `[date]` | `[summary]` | `[link or not public]` | + +Do not describe an internal AI response, self-issued certificate, hash receipt or informal conversation as independent third-party validation. + +## Corrections and retired claims + +| Date | Original claim | Correction | Reason | Issue / PR / decision record | +|---|---|---|---|---| +| `[date]` | `[claim]` | `[corrected wording or removal]` | `[evidence gap or changed fact]` | `[link]` | + +## Verification sign-off + +- **Human verifier:** `[name]` +- **Date:** `[YYYY-MM-DD]` +- **AI assistance:** `[system and role or None]` +- **Approval record:** `[PR comment, issue or decision link]` + +Verification means the evidence was reviewed for the stated scope. It is not a guarantee against all defects, risks or future changes.