diff --git a/.github/workflows/verify.yml b/.github/workflows/verify.yml index 8bd1ab0..4ca6e95 100644 --- a/.github/workflows/verify.yml +++ b/.github/workflows/verify.yml @@ -7,6 +7,7 @@ on: branches: - main - "agent/**" + - "docs/**" permissions: contents: read diff --git a/CHANGELOG.md b/CHANGELOG.md index 140c943..96d5be1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,21 @@ All material public changes will be recorded here. Published releases are append-only; corrections create a successor release. +## Unreleased + +- Improved the public record's short-form orientation and claim traceability. +- Added a repository social-preview asset with Ata Nasseri's accountable role. +- Added the AEAS visual system, four claim-bounded explanatory diagrams, + audience-specific reading paths, and text fallbacks. +- Added machine-readable visual metadata plus SVG, PNG, accessibility, source, + claim, non-claim, and Markdown-image verification. +- Strengthened the independent technical review scope, object identity, + evidence-handling requirements, and statement template. +- Extended CI verification to documentation branches. +- Left Release `v1.0.0`, its immutable assets, and its DOI unchanged. + ## 1.0.0 - 2026-08-19 - Prepared the initial public technical system record. - Added the publication boundary, evidence index, assurance method, release controls, DOI guidance, and independent-review package. - diff --git a/PUBLICATION_GATE.md b/PUBLICATION_GATE.md index 3939d6c..a7e82c4 100644 --- a/PUBLICATION_GATE.md +++ b/PUBLICATION_GATE.md @@ -1,5 +1,7 @@ # Publication Gate + + > **Repository decision:** AUTHORIZED FOR PUBLIC REPOSITORY DEPLOYMENT > > **Release decision:** APPROVED FOR PUBLICATION OF `v1.0.0` diff --git a/README.md b/README.md index 9ccc3a5..de7f03c 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,55 @@ [![DOI](https://zenodo.org/badge/1339810888.svg)](https://doi.org/10.5281/zenodo.22019207) - + > **Governance, Auditability, and Release Integrity for AI-Assisted Software Engineering** -The Agentic Engineering Assurance System is a governed approach to long-running, -AI-assisted software delivery. It separates implementation, technical review, -human authority, evidence, and release so that important decisions remain -traceable after the conversation that produced them has ended. +The Agentic Engineering Assurance System is a governed system for long-running, +AI-assisted software delivery. It keeps implementation, read-only technical +audit, human authority, evidence, and release distinct so that material +decisions remain attributable and reviewable after the conversation that +produced them has ended. -This repository is the public technical system record. It explains the design, -the implemented control model, the recorded outcomes, and the known limits in a -form that can be reviewed without exposing the private operating environment or -its sealed evidence archive. +This repository is the bounded public technical record. It documents the +design, implemented control model, recorded outcomes, release evidence, and +known limitations without disclosing the private operating environment or its +sealed evidence archive. + +## In 30 seconds + +| Question | Short answer | +| --- | --- | +| **What is this?** | A governed system for long-running, AI-assisted software delivery, documented as a public technical record. | +| **What does it separate?** | Human authority, implementation, read-only technical audit, durable evidence, and release. | +| **How is it controlled?** | Bounded work packages, pinned source, explicit finding disposition, owner gates, and a separate release step. | +| **What can a reader inspect?** | [Public claims and their boundaries](docs/04-public-evidence-index.md), [Release v1.0.0](https://github.com/Atanasseri/agentic-engineering-assurance-system/releases/tag/v1.0.0), [publication metadata](evidence/publication.json), and the [version DOI](https://doi.org/10.5281/zenodo.22019208). | +| **Who is accountable?** | **Ata Nasseri, System Designer and Assurance Owner.** | +| **What is the current boundary?** | Evidence-backed and publicly released; independent technical review has not yet been performed, and no external certification is claimed. | + +## Choose your reading path + +| If you are… | Start here | Then inspect | Primary question answered | +| --- | --- | --- | --- | +| A product or system leader | This README and the [System Overview](docs/01-system-overview.md) | [Limitations and Reassessment](docs/05-limitations-and-reassessment.md) | What is governed, who decides, and where are the boundaries? | +| A technical reviewer | [Implementation Record](docs/02-implementation-record.md) | [Assurance Method](docs/03-assurance-method.md) and [Public Evidence Index](docs/04-public-evidence-index.md) | What was recorded, how was it reviewed, and how strong is each claim? | +| A risk, governance, or assurance reader | [Assurance Method](docs/03-assurance-method.md) | [Public Evidence Index](docs/04-public-evidence-index.md) and [Limitations](docs/05-limitations-and-reassessment.md) | Which decisions remain human, and what is explicitly not established? | +| A release or provenance specialist | [Current assurance status](#current-assurance-status) | [Signing and Release](release/SIGNING_AND_RELEASE.md), [publication metadata](evidence/publication.json), and [DOI guidance](release/DOI_AND_ARCHIVAL.md) | Which exact public object is citable, persistent, and integrity-bound? | +| A prospective independent reviewer | [Independent Review Brief](review/REVIEW_BRIEF.md) | [Review Checklist](review/REVIEW_CHECKLIST.md), [review status](docs/06-independent-review.md), and the immutable [`v1.0.0` GitHub Release](https://github.com/Atanasseri/agentic-engineering-assurance-system/releases/tag/v1.0.0) with its signed Git objects | What must be independently checked before any external conclusion is published? | + +## Professional accountability + +**Ata Nasseri, System Designer and Assurance Owner** + +The accountable scope represented here includes translating objectives and +constraints into bounded acceptance criteria; defining authority boundaries; +authorizing audit rounds; deciding criteria changes and residual risk; and +governing release. AI implementation and audit roles operated within those +human-defined boundaries. + +This describes accountable system and assurance leadership. It does not claim +sole authorship of every implementation artifact or independent certification +of one's own work. ## Why it exists @@ -34,23 +70,24 @@ records, evidence-qualified claims, and controlled release. ## System at a glance -```mermaid -flowchart TD - O["Owner authority"] --> W["Bounded work package"] - W --> I["Implementation"] - I --> P["Pinned source and handoff"] - P --> A["Read-only technical audit"] - A --> D["Resolution and owner gate"] - D --> R["Controlled release"] -``` +![AEAS system map showing human authority above a bounded implementation, read-only audit, disposition, approval, and separate release lifecycle, with durable records below](assets/visuals/system-map.svg) + +[Open the full-size system map](assets/visuals/system-map.svg). The owner defines objectives, acceptance criteria, continuation authority, residual-risk decisions, and release approval. The implementation role changes the system. The audit role inspects a pinned source position without modifying -it. Git provides the durable evidence surface connecting all three. +it. Git provides the durable evidence surface connecting all three. In text, +the governed sequence is: bounded work package → implementation → exact source +checkpoint and integrity-bound handoff → read-only audit → finding disposition +→ owner decision → terminal approval → separate release action. ## Recorded outcomes +![AEAS recorded outcomes showing bounded report, review, finding, disposition, correction, and per-tier test counts with evidence-class labels](assets/visuals/recorded-outcomes.svg) + +[Open the full-size recorded-outcomes visual](assets/visuals/recorded-outcomes.svg). + The sealed private evidence baseline supports the following public statements: - seven audit reports were preserved across three governed reviews; @@ -59,6 +96,8 @@ The sealed private evidence baseline supports the following public statements: with no CRITICAL finding recorded; - resolution records mark 32 findings as fixed and one as settled through an owner-ratified criteria revision; +- each of the six substantive audit reports recorded a changes-required + verdict; - the final delivery review used two authorized rounds and reported eleven MEDIUM findings; - three final-round findings were defects introduced by earlier corrective @@ -97,6 +136,8 @@ constitute external certification. | [Independent Review](docs/06-independent-review.md) | Scope and status of third-party review | | [References](docs/07-references.md) | External standards and platform mechanisms used by the public release process | | [Publication Charter](PUBLICATION_CHARTER.md) | Public/private disclosure boundary | +| [Visual System](assets/VISUAL_SYSTEM.md) | Semantic color, typography, connector, accessibility, and change-control rules for public visuals | +| [Visual Manifest](assets/visuals/manifest.json) | Machine-readable claims, sources, dimensions, non-claims, and approval status for every visual asset | Release and external-review materials are kept separate from the system description: @@ -104,12 +145,31 @@ description: | Package | Purpose | | --- | --- | | [Publication Gate](PUBLICATION_GATE.md) | Separate repository-deployment, Release, archival, and review gates | -| [Signing and Release](release/SIGNING_AND_RELEASE.md) | Signed commit, annotated tag, immutable release, and provenance process | +| [Signing and Release](release/SIGNING_AND_RELEASE.md) | Signed release commit, signed annotated tag, immutable GitHub Release, and provenance process | | [DOI and Archival](release/DOI_AND_ARCHIVAL.md) | Zenodo and persistent citation process | | [Independent Review Brief](review/REVIEW_BRIEF.md) | Scope for a qualified external reviewer | -| [Assurance Statement Template](review/ASSURANCE_STATEMENT_TEMPLATE.md) | Required structure of the signed external conclusion | +| [Independent Review Checklist](review/REVIEW_CHECKLIST.md) | Evidence, identity, method, and conclusion checks for the reviewer | +| [Independent Technical Review Statement Template](review/ASSURANCE_STATEMENT_TEMPLATE.md) | Required structure of the signed external conclusion | + +## Evidence and release chain + +![AEAS evidence and release chain separating public claim discipline, the later public release record, and independent scrutiny](assets/visuals/evidence-release-chain.svg) + +[Open the full-size evidence-and-release visual](assets/visuals/evidence-release-chain.svg). + +The visual deliberately shows three separate groups rather than one unbroken +proof chain: + +1. a public claim is bounded by its identifier, evidence class, source, and + explicit non-claims; +2. the later publication record identifies the signed release commit and + signed annotated tag for `v1.0.0`, the immutable GitHub Release, checksums + and provenance workflow, and persistent version DOI without changing those + released objects; and +3. independent scrutiny remains `NOT_PERFORMED` until a qualified reviewer + publishes a scoped conclusion under their own control. -## Evidence relationship +## Private evidence relationship This public record derives from a sealed private baseline identified as `PTE-2026-08-19-v1.0.1`. The baseline manifest is committed here only by its @@ -123,21 +183,21 @@ The digest is a commitment to a specific private manifest. It does not reveal the manifest, independently validate its contents, or grant public access to the underlying evidence. -## Professional accountability - -**Ata Nasseri — System Designer and Assurance Owner** - -Accountability included objectives, constraints, acceptance criteria, -authority boundaries, audit authorization, owner decisions, residual-risk -acceptance, and release governance. AI implementation and audit roles operated -within those human-defined boundaries. - -## Assurance statement - -This repository is evidence-backed but is not yet externally certified. The -independent-review package is prepared so that a qualified reviewer can assess -a precise signed release and publish a scoped assurance statement without -overstating what was examined. +## Current assurance status + +Release `v1.0.0` has verified signed Git objects and an immutable GitHub +Release. Its release assets have SHA-256 checksums and GitHub artifact +attestations; Zenodo provides a separate persistent version DOI. Independent +technical review has not yet been performed, and no external certification is +claimed. The [independent-review package](review/REVIEW_BRIEF.md) is prepared +so that a qualified reviewer can assess that precise release commit, signed +annotated tag, and immutable GitHub Release, then publish a scoped conclusion +tied to them. + +The immutable `v1.0.0` GitHub Release remains the citable release object, bound +to a signed release commit and signed annotated tag. The default branch +contains later publication-record and documentation refinements; they do not +alter those signed Git objects, the Release assets, or the DOI. ## Use and citation diff --git a/assets/README.md b/assets/README.md index 11359bb..6381161 100644 --- a/assets/README.md +++ b/assets/README.md @@ -1,16 +1,38 @@ # Visual Assets -This directory is reserved for the approved public visual system. +This directory contains the repository's public visual assets. -The planned visual set is: +## Repository social preview -1. system context and responsibility boundary; -2. work-to-release evidence chain; -3. audit state and owner gates; -4. trust and assurance boundaries; and -5. outcomes and engineering lessons. +[`visuals/social-preview.png`](visuals/social-preview.png) is the primary +1280×640 social preview for the repository. It presents the system's governance, +audit, evidence, and release flow as a conceptual visual; it is not evidence and +does not reconstruct the private operating topology. -Markdown diagrams in the current documents are structural working visuals. The -final branded assets will be produced only after the written system record is -approved, so design does not outrun evidence. +The composition identifies the accountable professional role used throughout +the public record: +> **Ata Nasseri, System Designer and Assurance Owner** + +To activate it on GitHub, upload the PNG under **Settings → General → Social +preview** after the signed documentation change is merged. + +## Implemented explanatory visuals + +| Asset | Purpose | Primary placement | +| --- | --- | --- | +| [`visuals/system-map.svg`](visuals/system-map.svg) | Governed work-to-release lifecycle and durable-record spine | Repository README | +| [`visuals/recorded-outcomes.svg`](visuals/recorded-outcomes.svg) | Bounded recorded outcomes with evidence-class labels and visible non-claims | Repository README | +| [`visuals/evidence-release-chain.svg`](visuals/evidence-release-chain.svg) | Separation of claim discipline, the later public release record, and independent scrutiny | Repository README and Assurance Method | +| [`visuals/authority-matrix.svg`](visuals/authority-matrix.svg) | Decision rights, role limits, and durable controls | System Overview | + +The [AEAS Visual System](VISUAL_SYSTEM.md) defines the semantic palette, +typography, connector grammar, accessibility contract, and change controls. +The machine-readable [`visuals/manifest.json`](visuals/manifest.json) registers +every PNG and SVG with its dimensions, claim identifiers, sources, explicit +non-claims, independent-review status, and owner-approval status. + +Each explanatory visual has adjacent Markdown text or a table as a fallback. +New visuals enter the manifest as `DRAFT`. Only the Assurance Owner may change +their status to `OWNER_APPROVED` after reviewing the exact renders in an +authorized change. diff --git a/assets/VISUAL_SYSTEM.md b/assets/VISUAL_SYSTEM.md new file mode 100644 index 0000000..42c2fac --- /dev/null +++ b/assets/VISUAL_SYSTEM.md @@ -0,0 +1,175 @@ +# AEAS Visual System + +## Purpose + +The AEAS visual system makes the public technical record faster to understand +without making its claims broader, stronger, or less qualified. Visuals are +editorial explanations of approved public content. They are not evidence, +runtime topology, external certification, or a substitute for the claim +register. + +The visual language is designed around four ideas: + +1. human authority remains visible and attributable; +2. implementation, audit, evidence, and release remain distinct; +3. the main reading path is clear before supporting detail is introduced; and +4. limitations remain visible wherever a visual could otherwise overstate the + record. + +## Design principles + +### Meaning before decoration + +Every node, connector, number, color, and annotation must explain a supported +relationship. Decorative infrastructure, invented topology, generic AI +imagery, and unreferenced metrics are excluded from explanatory diagrams. + +### One focal decision + +Each visual should use the authority accent for no more than one or two focal +elements. Color identifies semantic role; it is never applied merely to make +peer elements look different. + +### Static first + +Repository visuals are static, self-contained SVG files with a complete first +frame. They use no script, remote font, external stylesheet, embedded raster +image, or network dependency. Motion belongs only on the separate AEAS website +and must preserve an equivalent static state. + +### Claim-governed visuals + +Every public visual is registered in +[`visuals/manifest.json`](visuals/manifest.json) with: + +- a stable visual identifier; +- its public claim identifiers; +- the public documents from which it is derived; +- concise non-claims; +- accessible alternative text; +- its approval status; and +- its intrinsic dimensions and view box. + +Visual metadata records provenance and review boundaries. It does not turn an +illustration into evidence. + +## Semantic color roles + +The palette aligns with the existing AEAS social identity while using a quieter +editorial treatment for technical reading. + +| Role | Light surface | Light ink/stroke | Dark surface | Dark ink/stroke | Meaning | +| --- | --- | --- | --- | --- | --- | +| Paper | `#F6F8FB` | `#101828` | `#07111F` | `#F2F4F7` | Canvas and primary text | +| Raised paper | `#FFFFFF` | `#344054` | `#0D1A2B` | `#D0D5DD` | Bounded nodes and tables | +| Muted | `#EEF1F5` | `#5F6B7A` | `#162337` | `#AEBAC9` | Supporting context | +| Structure | transparent | `#475467` | transparent | `#98A2B3` | Neutral implementation flow | +| Human authority | `#FFF3D6` | `#9A5B00` | `#2B2110` | `#F2B84B` | Owner decisions and authority gates | +| Audit | `#E7F8FB` | `#08798B` | `#0B2831` | `#45D3E8` | Read-only technical audit | +| Evidence | `#EAF1F8` | `#264B6B` | `#10283D` | `#88B8E0` | Durable records and evidence classes | +| Release | `#EDF1FF` | `#3548B5` | `#171F46` | `#9BACFF` | Release identity and archival path | +| Limitation | `#FFF0EE` | `#B42318` | `#351818` | `#FF8A80` | Qualification, exclusion, or unresolved boundary | + +Color must always be paired with visible text, a line style, or a role label so +that meaning does not depend on color perception. + +## Typography + +- Primary family: `Segoe UI`, `Inter`, `Arial`, sans-serif. +- Technical labels: `SFMono-Regular`, `Consolas`, `Liberation Mono`, monospace. +- Maximum weights: 400, 600, and 700 for large numeric outcomes only. +- Sentence case is used for titles and labels. +- Acronyms and status vocabulary retain their canonical uppercase form. +- Text must remain readable when a wide visual is displayed at 720 CSS pixels. + +No remote font is required. This removes a network dependency and keeps each +SVG self-contained. + +## Geometry + +- Base spacing unit: 8 pixels. +- Standard gaps: 16, 24, 32, 48, and 64 pixels. +- Standard node radius: 12 pixels. +- Structural border: 1.5 pixels. +- Primary connector: 2 pixels, solid. +- Evidence or reporting connector: 2 pixels, dashed. +- Maximum target density: approximately four out of ten. +- The normal repository view box is 960 units wide with height determined by + the content. +- Explanatory layouts use no more than two content columns. Dense comparison + structures must include a nearby Markdown table or list as a mobile and + assistive-technology fallback. + +Main flows read left to right and then top to bottom. Node titles are normally +22–26 SVG units and supporting copy 18–20 units at a 960-unit view box. +Vertical space is reserved for authority, evidence, qualifications, and +legends rather than for decorative whitespace. + +## Connector grammar + +| Connector | Meaning | +| --- | --- | +| Solid arrow | Authorized process or execution sequence | +| Dashed arrow | Reporting, recording, qualification, or evidence relationship | +| Amber line | Human authority entering a decision boundary | +| Cyan line | Read-only audit or evidence inspection | +| Neutral line | Implementation or structural flow | + +Arrows never imply that approval automatically performs merge, publication, +deployment, or release. Those actions remain distinct. + +## Status vocabulary + +Visuals use the same bounded language as the public record: + +- `SUPPORTED` +- `QUALIFIED` +- `DESIGN-CONTRACT` +- `COMMITTED-RECORD` +- `BASELINE-GIT-VERIFIED` +- `OWNER-CONFIRMED` +- `LIMITATION` +- `NOT_PERFORMED` + +The words *certified*, *formally verified*, *fully secure*, *zero risk*, and +*fully isolated* are not used unless the corresponding claim is established by +an authorized independent source within an explicit scope. + +## Accessibility contract + +Every SVG must: + +- declare `role="img"` and a resolving `aria-labelledby` value; +- begin with a non-empty `` and `<desc>`; +- preserve a logical reading order in the document tree; +- use text labels in addition to color; +- avoid text smaller than 15 SVG units in a 960-unit view box; +- contain no flashing, autoplay, or time-dependent content; and +- remain understandable when printed in grayscale. + +The Markdown page embedding the image must also provide concise alt text. + +## Registered visual set + +| Visual | Primary job | Default placement | +| --- | --- | --- | +| System map | Show the governed work-to-release path and evidence spine | Repository README | +| Recorded outcomes | Present bounded recorded results and their limitations | Repository README | +| Evidence and release chain | Separate claim discipline, release identity, persistence, and independent scrutiny | Repository README and Assurance Method | +| Authority matrix | Make non-interchangeable roles and decision rights explicit | System Overview | +| Social preview | Identify the work and accountable professional role when a repository link is shared | GitHub repository settings | + +## Review and change control + +1. Draft the visual only from approved public sources. +2. Register its claims, sources, non-claims, and alt text. +3. Run the publication verifier and visual-specific tests. +4. Render the complete SVG and inspect it at desktop and reduced width. +5. Obtain owner review before changing the metadata status to + `OWNER_APPROVED`. +6. Treat a material visual correction as a new public change. Never rewrite the + immutable `v1.0.0` Release or its archived assets. + +The exact `v1.0.0` Release, signed release commit, signed annotated tag, +checksums, provenance, DOI records, and private evidence remain outside this +visual update. diff --git a/assets/visuals/authority-matrix.svg b/assets/visuals/authority-matrix.svg new file mode 100644 index 0000000..f3a40e9 --- /dev/null +++ b/assets/visuals/authority-matrix.svg @@ -0,0 +1,183 @@ +<svg xmlns="http://www.w3.org/2000/svg" width="960" height="2380" viewBox="0 0 960 2380" role="img" aria-labelledby="authority-matrix-title authority-matrix-desc"> + <title id="authority-matrix-title">AEAS authority and control matrix + Seven action rows distinguish the Assurance Owner, implementation role, read-only audit role, and durable control output. The owner decides objectives, criteria, continuation, risk, completion, and release authorization. Implementation performs bounded work. Audit reports findings without changing source or substituting owner authority. Durable records and automation preserve status but cannot approve. Operational separation is not institutional independence. + + + + + AEAS · AUTHORITY BOUNDARIES + Authority and control matrix + Roles cooperate, but their authority is not interchangeable. + Durable controls record or report; they do not make human decisions. + + + + OWNER · DECIDES + + IMPLEMENTATION + + AUDIT · REPORTS + + CONTROL · RECORDS + + + + + 01 · SCOPE + Objectives, constraints, and acceptance criteria + + ASSURANCE OWNER + DECIDES + + IMPLEMENTATION ROLE + WORKS WITHIN DECLARED BOUNDARY + + READ-ONLY AUDIT + ASSESSES AGAINST CRITERIA + + DURABLE OUTPUT + WORK PACKAGE RECORD + + + + + 02 · IMPLEMENTATION + Source, tests, handoff, and remediation + + ASSURANCE OWNER + DEFINES WORK BOUNDARY + + IMPLEMENTATION ROLE + PERFORMS + + READ-ONLY AUDIT + NO SOURCE MODIFICATION + + DURABLE OUTPUT + EXACT-SOURCE + HANDOFF RECORD + + + + + 03 · AUDIT ROUND + Authorized inspection of a pinned source position + + ASSURANCE OWNER + AUTHORIZES BOUNDED ROUND + + IMPLEMENTATION ROLE + PINNED HANDOFF + REMEDIATION + + READ-ONLY AUDIT + REPORTS ONLY · FINDINGS + SEVERITY + + DURABLE OUTPUT + AUDIT RECORD + + + + + 04 · FINDING DISPOSITION + Correction, criteria, continuation, and residual risk + + ASSURANCE OWNER + DECIDES CRITERIA, CONTINUATION, RISK + + IMPLEMENTATION ROLE + CORRECTS WITHIN AUTHORIZED SCOPE + + READ-ONLY AUDIT + CANNOT REPLACE OWNER AUTHORITY + + DURABLE OUTPUT + RESOLUTION RECORD + + + + + 05 · COMPLETION APPROVAL + Terminal approval is a separate owner decision + + ASSURANCE OWNER + DECIDES SEPARATELY + + IMPLEMENTATION ROLE + CANNOT ISSUE APPROVAL + + READ-ONLY AUDIT + CANNOT ISSUE APPROVAL + + DURABLE OUTPUT + TERMINAL APPROVAL RECORD + + + + + 06 · RELEASE AUTHORIZATION + Approval does not itself merge, tag, publish, or release + + ASSURANCE OWNER + DECIDES SEPARATELY + + IMPLEMENTATION ROLE + CANNOT ISSUE RELEASE AUTHORITY + + READ-ONLY AUDIT + CANNOT ISSUE RELEASE AUTHORITY + + SEPARATE RELEASE CONTROL + MERGE / TAG / RELEASE IDENTITY + + + + + 07 · AUTOMATION STATUS + Automation reports status; it grants no authority + + ASSURANCE OWNER + RETAINS OWNER APPROVAL AUTHORITY + + IMPLEMENTATION ROLE + CANNOT ISSUE OWNER APPROVAL + + READ-ONLY AUDIT + CANNOT ISSUE OWNER APPROVAL + + AUTOMATION + REPORTS · NO OWNER AUTHORITY + + + + ASSURANCE BOUNDARY + Operational separation is not institutional independence. + Read-only audit, durable records, and automation cannot independently certify or approve. + + AEAS · AUTHORITY MATRIX + Ata Nasseri · System Designer and Assurance Owner + diff --git a/assets/visuals/evidence-release-chain.svg b/assets/visuals/evidence-release-chain.svg new file mode 100644 index 0000000..3182b73 --- /dev/null +++ b/assets/visuals/evidence-release-chain.svg @@ -0,0 +1,133 @@ + + AEAS evidence and release boundaries + Three visibly separate groups explain AEAS claim discipline, the later public release record, and the current independent-review status. Public claims are tied to evidence classes, sources, and explicit non-claims. The later record documents owner authorization, the signed release commit and signed annotated tag, an immutable GitHub Release with checksums and an artifact-attestation workflow, and a version DOI. Independent review remains not performed. The diagram states that integrity, provenance, and persistence are not correctness; a DOI is not certification or proof of byte equality; and the later publication record is distinct from the v1.0.0 Release and its signed Git objects. + + + + + + + + + + + + + PUBLIC TECHNICAL RECORD · EVIDENCE BOUNDARIES + Claims, release identity, + and scrutiny stay distinct + Three related assurance surfaces, never one uninterrupted proof chain. + + + + A · CLAIM DISCIPLINE + Bound every public statement before presenting it + + + PUBLIC STATEMENT + Precise claim + stable ID + One attributable proposition + + + + + QUALIFICATION + Evidence class + status + What kind of support is actually present + + + Public source + explicit non-claims + Readers can locate the statement and see what it does not establish. + + + Opaque private baseline commitment: anchors a controlled private manifest. + It does not provide public access to, or independently validate, the private contents. + + + + B · LATER PUBLIC RELEASE RECORD + Authorization and observed publication are separate facts + + + HUMAN AUTHORITY + Owner release + authorization + Version-bound decision + with stated conditions. + Approval is not release. + + + + + OBSERVED PUBLICATION SEQUENCE + + 01 + Release commit + annotated tag + Both Git objects signed; identifiers omitted here + + + 02 + Immutable GitHub Release + Checksums + artifact-attestation workflow + + + 03 + Version DOI · persistent citation for v1.0.0 + + + v1.0.0 remains unchanged. + Observed Release and DOI facts · separate from the signed release commit. + + + + C · INDEPENDENT SCRUTINY + External assurance remains a separate future step + + + CURRENT STATUS + NOT_PERFORMED + + + No external reviewer appointed. + No independent conclusion issued. + No external certification claimed. + + + + ASSURANCE BOUNDARIES + + Integrity, provenance, and persistence are not correctness. + + A DOI is not certification and does not establish byte equality. + + Later record ≠ v1.0.0 Release or its signed Git objects. + + AEAS · EVIDENCE & RELEASE + Ata Nasseri · System Designer and Assurance Owner + diff --git a/assets/visuals/manifest.json b/assets/visuals/manifest.json new file mode 100644 index 0000000..331f781 --- /dev/null +++ b/assets/visuals/manifest.json @@ -0,0 +1,140 @@ +{ + "schema_version": "1.0.0", + "record_id": "AEAS-VISUAL-MANIFEST-POST-RELEASE-001", + "record_scope": "POST_RELEASE_DOCUMENTATION_REFINEMENT", + "release_boundary": "This manifest and the registered visuals are later default-branch documentation refinements; they do not alter the v1.0.0 Release, its signed release commit and signed annotated tag, assets, checksums, provenance, or DOI archive.", + "independent_review_status": "NOT_PERFORMED", + "visuals": [ + { + "id": "authority-matrix", + "file": "assets/visuals/authority-matrix.svg", + "title": "AEAS authority and control matrix", + "description": "Seven action rows distinguish the Assurance Owner, implementation role, read-only audit role, and durable control output. The owner decides objectives, criteria, continuation, risk, completion, and release authorization. Implementation performs bounded work. Audit reports findings without changing source or substituting owner authority. Durable records and automation preserve status but cannot approve. Operational separation is not institutional independence.", + "width": 960, + "height": 2380, + "view_box": "0 0 960 2380", + "claim_ids": [ + "BND-001", + "GOV-001", + "REL-001", + "SYS-001" + ], + "public_sources": [ + "PUBLICATION_GATE.md", + "README.md", + "docs/01-system-overview.md", + "docs/03-assurance-method.md" + ], + "does_not_establish": [ + "External institutional independence or certification.", + "That records or automation possess human decision authority." + ], + "approval_status": "OWNER_APPROVED" + }, + { + "id": "evidence-release-chain", + "file": "assets/visuals/evidence-release-chain.svg", + "title": "AEAS evidence and release boundaries", + "description": "Three visibly separate groups explain AEAS claim discipline, the later public release record, and the current independent-review status. Public claims are tied to evidence classes, sources, and explicit non-claims. The later record documents owner authorization, the signed release commit and signed annotated tag, an immutable GitHub Release with checksums and an artifact-attestation workflow, and a version DOI. Independent review remains not performed. The diagram states that integrity, provenance, and persistence are not correctness; a DOI is not certification or proof of byte equality; and the later publication record is distinct from the v1.0.0 Release and its signed Git objects.", + "width": 960, + "height": 1540, + "view_box": "0 0 960 1540", + "claim_ids": [ + "ARC-001", + "BND-001", + "GOV-001", + "REL-001", + "REL-003", + "REV-001" + ], + "public_sources": [ + "README.md", + "docs/03-assurance-method.md", + "docs/04-public-evidence-index.md", + "docs/06-independent-review.md", + "evidence/publication.json", + "review/REVIEW_BRIEF.md" + ], + "does_not_establish": [ + "Software correctness, defect-free operation, completed independent review, or certification.", + "Byte identity between distinct archives or public access to the sealed private baseline." + ], + "approval_status": "OWNER_APPROVED" + }, + { + "id": "recorded-outcomes", + "file": "assets/visuals/recorded-outcomes.svg", + "title": "AEAS recorded assurance outcomes", + "description": "A bounded summary of retained records: seven preserved reports across three governed reviews, six substantive audit rounds and one attempted round recorded as not auditable; all six substantive reports recorded changes-required verdicts; thirty-three findings split into eleven high and twenty-two medium with no critical finding recorded; thirty-two findings marked fixed and one settled through an owner-ratified criteria revision; three final-round findings recorded as defects introduced by earlier corrections; a final governed review with two owner-authorized rounds and eleven medium findings, six in the first round and five in the final round; and 1,111 tests reported green in each of the hermetic and explicit live-host tiers, shown as separate counts and never totaled. The revised criterion is not presented as originally met, and final-round corrections did not receive a third audit round within the same review.", + "width": 960, + "height": 1960, + "view_box": "0 0 960 1960", + "claim_ids": [ + "AUD-001", + "AUD-002", + "AUD-003", + "AUD-004", + "AUD-005", + "GOV-002", + "TST-001" + ], + "public_sources": [ + "README.md", + "docs/02-implementation-record.md", + "docs/03-assurance-method.md", + "docs/04-public-evidence-index.md" + ], + "does_not_establish": [ + "The absence of undiscovered defects or equal operational impact across findings.", + "Independent replay of the reported tests or external certification.", + "That the revised criterion was originally met.", + "That final-round corrections received a third audit round within the same review." + ], + "approval_status": "OWNER_APPROVED" + }, + { + "id": "social-preview", + "file": "assets/visuals/social-preview.png", + "title": "Agentic Engineering Assurance System social preview", + "description": "Repository social preview identifying Agentic Engineering Assurance System, its governance, auditability, and release-integrity focus, and Ata Nasseri as System Designer and Assurance Owner.", + "width": 1280, + "height": 640, + "view_box": null, + "claim_ids": [ + "SYS-001" + ], + "public_sources": [ + "README.md" + ], + "does_not_establish": [ + "Runtime topology, independent review, external certification, or software correctness." + ], + "approval_status": "OWNER_APPROVED" + }, + { + "id": "system-map", + "file": "assets/visuals/system-map.svg", + "title": "AEAS governed work-to-release system map", + "description": "A conceptual control model. A bounded work package moves through implementation, an exact source checkpoint and handoff, read-only technical audit, finding disposition, an owner decision, terminal approval, and a separate release action. Human authority is shown above the process and durable records are shown separately below it.", + "width": 960, + "height": 1500, + "view_box": "0 0 960 1500", + "claim_ids": [ + "BND-001", + "GOV-001", + "REL-001", + "SYS-001" + ], + "public_sources": [ + "README.md", + "docs/01-system-overview.md", + "docs/03-assurance-method.md" + ], + "does_not_establish": [ + "Private operating topology, external institutional independence, or certification.", + "That terminal approval itself performs merge, tag, publication, deployment, or release." + ], + "approval_status": "OWNER_APPROVED" + } + ] +} diff --git a/assets/visuals/recorded-outcomes.svg b/assets/visuals/recorded-outcomes.svg new file mode 100644 index 0000000..d023873 --- /dev/null +++ b/assets/visuals/recorded-outcomes.svg @@ -0,0 +1,116 @@ + + AEAS recorded assurance outcomes + A bounded summary of retained records: seven preserved reports across three governed reviews, six substantive audit rounds and one attempted round recorded as not auditable; all six substantive reports recorded changes-required verdicts; thirty-three findings split into eleven high and twenty-two medium with no critical finding recorded; thirty-two findings marked fixed and one settled through an owner-ratified criteria revision; three final-round findings recorded as defects introduced by earlier corrections; a final governed review with two owner-authorized rounds and eleven medium findings, six in the first round and five in the final round; and 1,111 tests reported green in each of the hermetic and explicit live-host tiers, shown as separate counts and never totaled. The revised criterion is not presented as originally met, and final-round corrections did not receive a third audit round within the same review. + + + + AEAS · BOUNDED PUBLIC RECORD + Recorded assurance outcomes + What the retained records report, and no more. + + + Review record + + BASELINE-GIT-VERIFIED + + 7 + preserved + reports + 3 + governed + reviews + 6 + substantive + audit rounds + 1 + attempted round + recorded not auditable + + 6 OF 6 SUBSTANTIVE REPORTS · CHANGES REQUIRED + + + + Findings in retained reports + + BASELINE-GIT-VERIFIED + + 33 + findings + across the retained reports + 11 + HIGH + 22 + MEDIUM + No CRITICAL finding recorded + + RECORDED DISPOSITION + + COMMITTED-RECORD + + + 32 + marked fixed + in resolution records + 1 + owner-ratified + criteria revision + + FINAL-REVIEW RECORD + + COMMITTED-RECORD + + + Corrective-work finding + 3 + final-round findings + recorded as defects introduced + by earlier corrections + Final governed review + 2 + owner-authorized + rounds + 11 + MEDIUM + 6 first · 5 final + + + Tests reported green in each tier + + COMMITTED-RECORD + + 1,111 + hermetic tier + 1,111 + explicit live-host tier + Same reported count in each tier · not a combined total + + + ASSURANCE BOUNDARY + Retained records do not prove the absence of undiscovered defects, + equal impact across findings, independent replay of the final tests, + or external certification. + The revised criterion is not presented as originally met; + final-round corrections did not receive a third audit round within this review. + + ATA NASSERI · SYSTEM DESIGNER AND ASSURANCE OWNER + RECORDED OUTCOMES + + diff --git a/assets/visuals/social-preview.png b/assets/visuals/social-preview.png new file mode 100644 index 0000000..4cdbad7 Binary files /dev/null and b/assets/visuals/social-preview.png differ diff --git a/assets/visuals/system-map.svg b/assets/visuals/system-map.svg new file mode 100644 index 0000000..9215521 --- /dev/null +++ b/assets/visuals/system-map.svg @@ -0,0 +1,128 @@ + + AEAS governed work-to-release system map + A conceptual control model. A bounded work package moves through implementation, an exact source checkpoint and handoff, read-only technical audit, finding disposition, an owner decision, terminal approval, and a separate release action. Human authority is shown above the process and durable records are shown separately below it. + + + + + + + AEAS · CONCEPTUAL CONTROL MODEL + Governed work-to-release lifecycle + Authority, execution, audit, evidence, and release remain distinct. + + + Assurance owner + Defines scope and criteria · authorizes bounded audit rounds · decides criteria + changes, continuation, residual risk, completion, and release authorization + HUMAN AUTHORITY + + + + + + + + + + + + 01 · SCOPE + Bounded work package + Objectives, constraints, and + acceptance criteria + + + + 02 · BUILD + Implementation role + Source, tests, handoff preparation, + and remediation + + + + 03 · PIN + Exact source checkpoint + and integrity-bound handoff + A stable, reviewable source identity + + + + 04 · INSPECT + Read-only technical audit + Reports findings and severity; + does not change reviewed source + + + + 05 · DISPOSE + Finding disposition + Correction, criteria revision, + or explicit qualification + + + + 06 · DECIDE + Explicit owner decision + Criteria, continuation, and residual + risk remain human decisions + + + + 07 · APPROVE + Terminal approval + A distinct recorded decision, + not a release action + + + + 08 · RELEASE + Separate release action + Merge, tag, publish, and verify + release identity + + + DURABLE RECORDS · NOT DECISION AUTHORITY + + + + FROM 01 + Scope and acceptance record + Objectives · constraints · criteria + FROM 03–04 + Source identity and audit record + Pinned source · handoff · findings · severity + FROM 05–07 + Disposition and decision record + Corrections · revisions · risk · approval + FROM 08 + Release identity + Merge · tag · publication record + + + ASSURANCE BOUNDARY + Conceptual model, not private topology or external certification. Approval is not release. + + ATA NASSERI · SYSTEM DESIGNER AND ASSURANCE OWNER + SYSTEM MAP + diff --git a/docs/01-system-overview.md b/docs/01-system-overview.md index b0368c9..64fcb86 100644 --- a/docs/01-system-overview.md +++ b/docs/01-system-overview.md @@ -1,6 +1,6 @@ # System Overview - + ## Purpose @@ -49,13 +49,19 @@ approve completion, or authorize release. ## Authority boundaries -```mermaid -flowchart LR - O["Owner"] -->|defines and decides| C["Control boundary"] - I["Implementation"] -->|changes source| C - A["Audit"] -->|reports only| C - C -->|records| G["Git evidence"] -``` +![AEAS authority matrix showing decision rights, implementation duties, read-only audit limits, and the durable record for seven governed actions](../assets/visuals/authority-matrix.svg) + +[Open the full-size authority matrix](../assets/visuals/authority-matrix.svg). + +| Governed action | Assurance owner | Implementation role | Read-only audit role | Durable output or control | +| --- | --- | --- | --- | --- | +| Objectives, constraints, and criteria | **Decides** | Works within the boundary | Assesses against the boundary | Bounded work package | +| Source, tests, handoff, and remediation | Defines the boundary | **Performs** the change | **No source modification** | Exact-source checkpoint and handoff | +| Audit round | **Authorizes** the round | Supplies pinned handoff and remediation | **Reports only** findings and severity | Audit record tied to exact source | +| Finding disposition | **Decides** criteria, continuation, and risk | Corrects or records response | Cannot substitute for owner authority | Resolution and decision record | +| Completion approval | **Decides separately** | Cannot issue owner approval | Cannot issue owner approval | Terminal approval record | +| Release authorization | **Decides separately** | Cannot issue release authority | Cannot issue release authority | Separate merge, tag, and release identity | +| Automation status | Retains owner approval authority | Cannot issue owner approval | Cannot issue owner approval | Automation **reports status and cannot issue owner authority** | Operational separation is not the same as institutional independence. The audit role is technically separated and read-only inside the designed diff --git a/docs/03-assurance-method.md b/docs/03-assurance-method.md index 46eec25..083ee7c 100644 --- a/docs/03-assurance-method.md +++ b/docs/03-assurance-method.md @@ -1,6 +1,6 @@ # Assurance Method - + ## Objective @@ -23,17 +23,20 @@ the reviewed source. Approval does not itself merge or release anything. ## Evidence chain -```mermaid -flowchart TD - S["Authorized scope"] --> C["Exact source checkpoint"] - C --> H["Integrity-bound handoff"] - H --> F["Audit findings"] - F --> D["Disposition and decision"] - D --> R["Signed release identity"] -``` +![AEAS evidence and release chain separating public claim discipline, the later public release record, and independent scrutiny](../assets/visuals/evidence-release-chain.svg) -Each link establishes a different fact. The chain is credible only when those -differences remain visible. +[Open the full-size evidence-and-release visual](../assets/visuals/evidence-release-chain.svg). + +| Group | Sequence | Boundary preserved | +| --- | --- | --- | +| Public claim discipline | Precise claim and ID → evidence class and status → public source and explicit non-claims | An opaque private-baseline digest is a commitment, not public access or independent validation. | +| Later public release record | Owner authorization → signed release commit and signed annotated tag → immutable GitHub Release, checksums, and artifact-attestation workflow → version DOI | Approval is not release; the later publication record does not alter the `v1.0.0` Release or its signed Git objects. | +| Independent scrutiny | Qualified external reviewer → independently controlled conclusion | Current status is `NOT_PERFORMED`; no external conclusion or certification is claimed. | + +These groups establish different kinds of facts and must not be collapsed into +one unbroken proof chain. Integrity, provenance, and persistence strengthen +object identity; they do not establish software correctness. A DOI does not +establish certification or byte identity between distinct archives. ## Public evidence classes @@ -99,8 +102,8 @@ The public system record adds a separate assurance layer: 2. allow-list derivation; 3. prohibited-content scan; 4. machine-readable claims; -5. signed commit and annotated tag; -6. immutable GitHub release; +5. signed release commit and signed annotated tag; +6. immutable GitHub Release; 7. SHA-256 release manifest; 8. GitHub artifact attestation; 9. DOI-backed archival; and diff --git a/docs/04-public-evidence-index.md b/docs/04-public-evidence-index.md index 0be22c2..8454747 100644 --- a/docs/04-public-evidence-index.md +++ b/docs/04-public-evidence-index.md @@ -1,6 +1,6 @@ # Public Evidence Index - + ## Purpose @@ -36,6 +36,9 @@ private manifest or prove its substantive accuracy. | `OPS-002` | The owner separately confirmed the final application-visible state. | `OWNER-CONFIRMED` | Human observation is not cryptographic remote attestation. | | `REL-001` | Approval and release were modeled as separate controlled actions. | `DESIGN-CONTRACT` | Approval alone does not prove that a release occurred. | | `REL-002` | The completion record reports a versioned correctness release. | `COMMITTED-RECORD` | The public repository does not independently reproduce the private release. | +| `REL-003` | The later publication record records the signed release commit, signed annotated tag, immutable GitHub Release, checksums, and artifact-attestation workflow for `v1.0.0`. | `COMMITTED-RECORD` | These controls establish identity, integrity, and provenance, not software correctness or independent review. | +| `ARC-001` | The later publication record identifies the version and concept DOI for this public record. | `COMMITTED-RECORD` | DOI persistence is not certification or proof that distinct archives are byte-identical. | +| `REV-001` | Independent technical review has not been performed and no external certification is claimed. | `LIMITATION` | A prepared review package is not a completed review or a predicted reviewer conclusion. | | `BND-001` | The implemented assurance has explicit isolation, liveness, evidence, and review limits. | `LIMITATION` | The system is not presented as fully isolated, formally verified, or defect-free. | | `SYS-002` | The completion record reports the capability categories summarized here. | `COMMITTED-RECORD` | The summary is not a public reconstruction of the private implementation. | diff --git a/docs/06-independent-review.md b/docs/06-independent-review.md index aa5ed7e..2754b31 100644 --- a/docs/06-independent-review.md +++ b/docs/06-independent-review.md @@ -1,13 +1,29 @@ # Independent Review -> **Current status:** Not yet performed + -## Intended assurance level +> **Current status:** `NOT_PERFORMED` +> +> No external reviewer has been appointed, no independent conclusion has been +> issued, and this repository makes no claim of certification. + +## Purpose -The planned review is an **Independent Technical Assurance Review** of a -specific signed public release and selected supporting private evidence. +The planned engagement is a scoped independent technical review of Release +`v1.0.0`, selected supporting private evidence, and the later public record that +documents the observed Release and DOI. -It is not automatically: +The signed release commit and the later post-release publication-record commit +are different objects. The reviewer must bind the technical conclusion to the +commit reached by the signed `v1.0.0` tag and identify the later record only as +post-release evidence. Release and archival identities are recorded in +[`evidence/publication.json`](../evidence/publication.json); that file does not +identify the later publication-record commit, which the reviewer must derive +independently from Git history. + +## Intended assurance level + +The review is not automatically: - an ISO certification; - a SOC examination; @@ -25,7 +41,8 @@ The reviewer will assess whether: 2. aggregate findings and dispositions are accurately represented; 3. evidence qualifications and non-claims are preserved; 4. the public repository avoids prohibited private detail; -5. the signed release, digest manifest, and DOI identify the reviewed object; +5. the signed release commit, signed annotated tag, Release, digest manifest, + and DOI identify the reviewed object; and 6. the limitations are sufficient for a reasonable reader to understand the assurance boundary. @@ -46,20 +63,38 @@ The public report must identify: - reviewer name, organization, role, and relevant qualifications; - conflict-of-interest declaration; -- exact repository, commit, signed tag, release, and DOI; +- exact repository, release commit, signed tag, tag object, Release, and + version DOI; +- the later post-release publication-record commit as a separate object; - review dates and methods; -- evidence sampled; +- evidence inspected and independently selected samples; - findings and qualifications; - excluded scope; - conclusion; and -- reviewer signature or independently verifiable digital approval. +- reviewer-controlled signature or independently verifiable digital approval. + +The conclusion vocabulary is: + +- `CONFIRMED`: sufficient evidence was obtained and no unresolved material + inconsistency was identified within scope. +- `CONFIRMED WITH QUALIFICATIONS`: the core conclusion is supportable, but + stated evidence or scope limitations materially narrow reliance. +- `NOT CONFIRMED`: evidence was insufficient or an unresolved material + inconsistency was identified. -The expected conclusion vocabulary is: +## Publication rule -- `CONFIRMED`; -- `CONFIRMED WITH QUALIFICATIONS`; or -- `NOT CONFIRMED`. +The reviewer controls the wording and conclusion of the final statement. The +owner may publish an unmodified copy and a clearly separated owner response, +but may not edit the reviewer's report. -Until that report exists, the repository will not describe itself as -independently reviewed or certified. +The public statement must have a stable URL and a reviewer-controlled signature +or independently verifiable approval. Its SHA-256 digest must be published +outside the report itself in a signed checksum, Git, release-manifest, detached +signature, or equivalent verification record. If a confidential annex affects +the conclusion, the public statement must disclose its existence and effect +without exposing sensitive evidence. +Only after that statement has been verified may a successor commit change the +machine-readable status from `NOT_PERFORMED`. Release `v1.0.0` remains +unchanged. diff --git a/docs/07-references.md b/docs/07-references.md index 9158867..9e66627 100644 --- a/docs/07-references.md +++ b/docs/07-references.md @@ -19,9 +19,8 @@ release. They do not imply endorsement, conformity, or certification. ## Standards context -- [ISO/IEC 42001 — AI management systems](https://www.iso.org/standard/42001) -- [ISO/IEC 27001 — information security management systems](https://www.iso.org/standard/27001) +- [ISO/IEC 42001: AI management systems](https://www.iso.org/standard/42001) +- [ISO/IEC 27001: information security management systems](https://www.iso.org/standard/27001) The system record does not claim conformity with either ISO standard. They are listed only as future organizational governance context. - diff --git a/evidence/public-claims.json b/evidence/public-claims.json index 46f0f21..8a87d0e 100644 --- a/evidence/public-claims.json +++ b/evidence/public-claims.json @@ -8,12 +8,30 @@ "does_not_establish": "The digest does not disclose or independently validate the private baseline." }, "claims": [ + { + "id": "ARC-001", + "statement": "The later public publication record identifies 10.5281/zenodo.22019208 as the version DOI for Release v1.0.0 and 10.5281/zenodo.22019207 as the concept DOI.", + "evidence_class": "COMMITTED-RECORD", + "status": "QUALIFIED", + "public_sources": [ + "README.md", + "docs/03-assurance-method.md", + "docs/04-public-evidence-index.md", + "evidence/publication.json", + "review/REVIEW_BRIEF.md" + ], + "does_not_establish": [ + "Certification, correctness, or independent technical review.", + "Byte identity between Zenodo's generated source archive and the attested GitHub release bundle." + ] + }, { "id": "AUD-001", "statement": "Seven audit reports were preserved across three governed reviews.", "evidence_class": "BASELINE-GIT-VERIFIED", "status": "SUPPORTED", "public_sources": [ + "README.md", "docs/02-implementation-record.md", "docs/04-public-evidence-index.md" ], @@ -58,6 +76,7 @@ "evidence_class": "COMMITTED-RECORD", "status": "QUALIFIED", "public_sources": [ + "README.md", "docs/02-implementation-record.md", "docs/04-public-evidence-index.md" ], @@ -86,6 +105,8 @@ "evidence_class": "LIMITATION", "status": "QUALIFIED", "public_sources": [ + "README.md", + "docs/01-system-overview.md", "docs/05-limitations-and-reassessment.md" ], "does_not_establish": [ @@ -98,6 +119,7 @@ "evidence_class": "DESIGN-CONTRACT", "status": "QUALIFIED", "public_sources": [ + "README.md", "docs/01-system-overview.md", "docs/03-assurance-method.md", "docs/04-public-evidence-index.md" @@ -113,6 +135,7 @@ "evidence_class": "COMMITTED-RECORD", "status": "QUALIFIED", "public_sources": [ + "README.md", "docs/03-assurance-method.md", "docs/04-public-evidence-index.md" ], @@ -154,6 +177,8 @@ "evidence_class": "DESIGN-CONTRACT", "status": "QUALIFIED", "public_sources": [ + "PUBLICATION_GATE.md", + "README.md", "docs/01-system-overview.md", "docs/03-assurance-method.md", "docs/04-public-evidence-index.md" @@ -176,6 +201,40 @@ "That the public technical record has itself been released." ] }, + { + "id": "REL-003", + "statement": "The later public publication record records the signed release commit, signed annotated tag, immutable GitHub Release, SHA-256 release checksums, and GitHub artifact-attestation workflow for v1.0.0.", + "evidence_class": "COMMITTED-RECORD", + "status": "QUALIFIED", + "public_sources": [ + "README.md", + "docs/03-assurance-method.md", + "docs/04-public-evidence-index.md", + "evidence/publication.json", + "review/REVIEW_BRIEF.md" + ], + "does_not_establish": [ + "Software correctness, defect-free operation, or independent technical review.", + "That the later default-branch publication record is part of the v1.0.0 Release or its signed Git objects." + ] + }, + { + "id": "REV-001", + "statement": "The later public record states that independent technical review has not been performed and that no external certification is claimed.", + "evidence_class": "LIMITATION", + "status": "QUALIFIED", + "public_sources": [ + "README.md", + "docs/03-assurance-method.md", + "docs/04-public-evidence-index.md", + "docs/06-independent-review.md", + "evidence/publication.json" + ], + "does_not_establish": [ + "That the prepared review package constitutes a completed review.", + "Any predicted conclusion of a future independent reviewer." + ] + }, { "id": "SYS-001", "statement": "The system design separates owner authority, implementation, read-only audit, durable evidence, and release.", diff --git a/review/ASSURANCE_STATEMENT_TEMPLATE.md b/review/ASSURANCE_STATEMENT_TEMPLATE.md index 5c1e6a2..d9f77b1 100644 --- a/review/ASSURANCE_STATEMENT_TEMPLATE.md +++ b/review/ASSURANCE_STATEMENT_TEMPLATE.md @@ -1,38 +1,54 @@ -# Independent Technical Assurance Statement +# Independent Technical Review Statement + +> This is a scoped independent technical review statement. It is not a +> certification, audit opinion, penetration test, legal opinion, or warranty. ## Identification -**System record:** Agentic Engineering Assurance System -**Repository:** `https://github.com/Atanasseri/agentic-engineering-assurance-system` -**Release:** `[exact release]` -**Commit:** `[full commit SHA]` -**Signed tag:** `[exact annotated tag]` -**DOI:** `[version DOI]` -**Review period:** `[start date]` to `[end date]` +| Field | Value | +| --- | --- | +| System record | Agentic Engineering Assurance System | +| Repository | `https://github.com/Atanasseri/agentic-engineering-assurance-system` | +| Release | `v1.0.0` | +| Reviewed Release commit | `[full commit SHA]` | +| Post-release publication-record commit | `[full commit SHA]` | +| Signed tag | `v1.0.0` | +| Tag object SHA | `[full tag-object SHA]` | +| Version DOI | `10.5281/zenodo.22019208` | +| Review period | `[start date]` to `[end date]` | +| Report version | `[report version]` | +| Public report URL | `[stable URL]` | +| External checksum or verification record | `[stable URL or signed manifest]` | ## Reviewer -**Name:** `[reviewer name]` -**Organization:** `[organization]` -**Role:** `[role]` -**Relevant qualifications:** `[qualifications and experience]` +- **Name:** `[reviewer name]` +- **Organization:** `[organization]` +- **Role:** `[role]` +- **Relevant qualifications:** `[qualifications and experience]` ## Independence declaration -`[Describe any financial, professional, personal, authorship, or implementation -relationship relevant to the review. State whether the reviewer had any role in -designing or implementing the reviewed system.]` +`[Describe any financial, professional, personal, authorship, implementation, +or compensation relationship relevant to the review. State whether the +reviewer had any role in designing or implementing the reviewed system.]` + +## Evidence and method -## Scope and method +- **Public materials inspected:** `[list]` +- **Private evidence categories inspected:** `[non-sensitive identifiers]` +- **Quantitative claims independently recalculated:** `[list or all]` +- **Reviewer-selected samples:** `[selection method]` +- **Evidence unavailable or withheld:** `[none or list]` +- **Automated or AI assistance used:** `[none or disclosure]` -`[Describe the public release inspected, the private evidence sampled, the -verification methods used, and any limits on evidence access.]` +`[Describe the verification methods used and any limits on evidence access.]` ## Findings -| ID | Severity | Finding | Evidence | Disposition | +| ID | Classification | Observation | Evidence reference | Status at report date | | --- | --- | --- | --- | --- | -| `[ID]` | `[severity]` | `[finding]` | `[public or confidential reference]` | `[open, corrected, accepted, or qualified]` | +| `IR-v1.0.0-001` | `MATERIAL / LIMITED / OBSERVATION` | `[text]` | `[public or blinded confidential reference]` | `[open, acknowledged, or corrected in successor release]` | ## Qualifications and exclusions @@ -41,21 +57,23 @@ on owner-confirmed or committed-record evidence.]` ## Conclusion -Select exactly one: +Select exactly one using the definitions in +[`docs/06-independent-review.md`](../docs/06-independent-review.md): - `CONFIRMED` - `CONFIRMED WITH QUALIFICATIONS` - `NOT CONFIRMED` -`[Provide a concise conclusion limited to the stated scope. Do not use the word -certified unless the reviewer is acting through a recognized certification -scheme that covers the exact claim.]` +`[Provide a concise conclusion limited to the stated object, evidence, scope, +and review dates. Do not describe the system as certified.]` ## Signature -**Reviewer:** `[name]` -**Date:** `[UTC date]` -**Signature method:** `[qualified electronic signature, document signature, or -verifiable signed Git object]` -**Verification reference:** `[public verification method or fingerprint]` +- **Reviewer-controlled signature method:** `[signed Git commit, detached + digital signature, or reputable document-signing service]` +- **Signature fingerprint or verification URL:** `[value]` +- **UTC issue date:** `[YYYY-MM-DD]` +The final report's SHA-256 digest must be published outside the report itself +in a signed Git record, release manifest, detached signature record, or other +independently verifiable checksum record. diff --git a/review/REVIEW_BRIEF.md b/review/REVIEW_BRIEF.md index e76540e..d5d0a63 100644 --- a/review/REVIEW_BRIEF.md +++ b/review/REVIEW_BRIEF.md @@ -1,4 +1,6 @@ -# Independent Technical Assurance Review Brief +# Independent Technical Review Brief + + ## Commissioning objective @@ -7,7 +9,42 @@ System is materially consistent with selected sealed private evidence and whether its claims, qualifications, and limitations are professionally supportable. -## Intended reader +## Engagement record + +| Field | Value | +| --- | --- | +| Commissioner | Ata Nasseri, Solofounders | +| Target Release | `v1.0.0` | +| Expected effort | To be agreed after conflict and evidence-access review | +| Commercial basis | `[paid, pro bono, or other; disclose in final report]` | +| Target dates | `[start]` to `[completion]` | +| Contact | Arranged through direct professional outreach | + +## Object identity + +| Object | Canonical reference | +| --- | --- | +| Repository | `https://github.com/Atanasseri/agentic-engineering-assurance-system` | +| Release | `v1.0.0` | +| Immutable GitHub Release | `https://github.com/Atanasseri/agentic-engineering-assurance-system/releases/tag/v1.0.0` | +| Release-evidence workflow | `https://github.com/Atanasseri/agentic-engineering-assurance-system/actions/runs/32308546078` | +| Release bundle SHA-256 | `598ca929037c78b856297143c932b54900cdc02ec99d36fb7dd132be2c7b10a9` | +| `SHA256SUMS` SHA-256 | `bc903bdbd0810e3800e0ebf3762c5a45b6ccfbe5a27380ee220a4e29b8d35d73` | +| Version DOI | `10.5281/zenodo.22019208` | +| Zenodo record | `https://zenodo.org/records/22019208` | +| Concept DOI, all versions | `10.5281/zenodo.22019207` | +| Machine-readable release identities | [`evidence/publication.json`](../evidence/publication.json) | + +The reviewer must independently record the full release commit, annotated-tag +object, and later post-release publication-record commit. These are distinct +objects and must not be substituted for one another. + +Zenodo's automatically generated source ZIP and the attested GitHub release +bundle are also distinct artifacts. The DOI establishes archival identity; it +does not establish that the two archives are byte-identical unless the reviewer +separately demonstrates that fact. + +## Intended reviewer A senior reviewer with relevant experience in at least two of the following: @@ -33,6 +70,35 @@ are more important than credentials alone. consistent? 6. Are limitations adequate for a reasonable technical or professional reader? +## Review method + +The reviewer is expected to: + +1. verify the public object identities and signatures independently; +2. inspect the complete public claim register; +3. independently recalculate every quantitative claim in scope, or identify + each unverified claim as a limitation; +4. select non-quantitative evidence samples independently rather than accept + only owner-selected examples; +5. record unavailable, withheld, substituted, or ambiguous evidence; +6. distinguish the attested GitHub release bundle from Zenodo's generated + source archive; and +7. retain sole control over the final conclusion. + +Owner responses and later corrections may be published separately. They do not +rewrite the reviewed historical Release or the reviewer's conclusion. + +## Independence and tool disclosure + +The reviewer must disclose prior work, personal or commercial relationships, +authorship, implementation involvement, compensation, and any other condition +that could reasonably affect perceived independence. A paid engagement is not +automatically disqualifying, but it must be disclosed. + +Any material use of automated or AI-assisted review tools must be disclosed. +Private evidence must not be submitted to an external AI service or other third +party without explicit written authorization. + ## Out of scope unless separately commissioned - full source-code audit; @@ -47,9 +113,9 @@ are more important than credentials alone. ## Expected deliverables - completed review checklist; -- findings with severity and evidence references; +- findings with classification and evidence references; - independence and conflict-of-interest declaration; -- signed public assurance statement; and +- signed public technical review statement; and - optional confidential annex for sensitive observations. ## Evidence handling @@ -57,4 +123,3 @@ are more important than credentials alone. The reviewer receives the minimum private evidence required for each sampled claim. Access is read-only, confidential, and does not grant reuse or publication rights. Raw evidence should not be copied into the public report. - diff --git a/review/REVIEW_CHECKLIST.md b/review/REVIEW_CHECKLIST.md index bae11a7..8637a86 100644 --- a/review/REVIEW_CHECKLIST.md +++ b/review/REVIEW_CHECKLIST.md @@ -3,23 +3,32 @@ ## Reviewer identity and independence - [ ] Name, organization, role, and relevant qualifications recorded. -- [ ] Commercial, personal, and authorship relationships disclosed. +- [ ] Commercial, personal, authorship, and implementation relationships disclosed. - [ ] Reviewer confirms no implementation responsibility for the reviewed release. - [ ] Any limitation on independence is described. +- [ ] Compensation basis is disclosed. ## Object identity - [ ] Canonical repository confirmed. -- [ ] Full release commit recorded. -- [ ] Signed annotated tag verified. -- [ ] Immutable GitHub release verified. +- [ ] Full release commit independently recorded. +- [ ] Later post-release publication-record commit recorded separately. +- [ ] Signed annotated tag and tag-object identity verified. +- [ ] Immutable GitHub Release verified. - [ ] Release asset SHA-256 values verified. - [ ] Artifact provenance verified. -- [ ] DOI resolves to the reviewed release. +- [ ] Version DOI `10.5281/zenodo.22019208` resolves to the `v1.0.0` record. +- [ ] The concept DOI is treated only as the all-versions identifier. +- [ ] The Zenodo-generated archive and attested GitHub bundle are not presented + as byte-identical unless separately verified. -## Claim sampling +## Claim evaluation -- [ ] All numerical claims sampled against the private baseline. +- [ ] Every quantitative public claim in scope was independently recalculated. +- [ ] Every quantitative exception is listed as an evidence limitation. +- [ ] Non-quantitative samples were selected by the reviewer after reviewing + the complete claim register. +- [ ] Unavailable, withheld, substituted, or ambiguous evidence is recorded. - [ ] Audit-report count and severity totals independently recounted. - [ ] Finding dispositions sampled against resolution records. - [ ] Criteria revision remains distinguishable from a fix. @@ -35,6 +44,17 @@ - [ ] No raw transcript, pane capture, or private decision text is published. - [ ] Diagrams do not reconstruct private topology. +## Evidence handling record + +- [ ] Access method and access dates recorded. +- [ ] Evidence categories inspected are listed using non-sensitive references. +- [ ] Confidentiality, retention, and deletion obligations recorded. +- [ ] No private evidence was uploaded to an external AI or cloud service + without explicit authorization. +- [ ] Material automated assistance is disclosed. +- [ ] The final report SHA-256 is recorded outside the report in a signed or + independently verifiable checksum record. + ## Method and limitations - [ ] Evidence classes are understandable and consistently applied. @@ -43,12 +63,21 @@ - [ ] Operational separation is not presented as institutional independence. - [ ] External certification is not claimed. +## Finding classification + +- `MATERIAL`: could change the conclusion or make a public claim misleading. +- `LIMITED`: requires correction or qualification but does not by itself change + the core conclusion. +- `OBSERVATION`: improvement opportunity without a supported inconsistency. + ## Conclusion +Select exactly one using the definitions in +[`docs/06-independent-review.md`](../docs/06-independent-review.md): + - [ ] `CONFIRMED` - [ ] `CONFIRMED WITH QUALIFICATIONS` - [ ] `NOT CONFIRMED` Every qualification and unresolved finding must be listed in the final statement or its referenced public annex. - diff --git a/schemas/visual-manifest.schema.json b/schemas/visual-manifest.schema.json new file mode 100644 index 0000000..d8a5cfb --- /dev/null +++ b/schemas/visual-manifest.schema.json @@ -0,0 +1,129 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/Atanasseri/agentic-engineering-assurance-system/schemas/visual-manifest.schema.json", + "title": "Agentic Engineering Assurance Visual Manifest", + "type": "object", + "required": [ + "schema_version", + "record_id", + "record_scope", + "release_boundary", + "independent_review_status", + "visuals" + ], + "properties": { + "schema_version": { + "const": "1.0.0" + }, + "record_id": { + "type": "string", + "minLength": 1 + }, + "record_scope": { + "const": "POST_RELEASE_DOCUMENTATION_REFINEMENT" + }, + "release_boundary": { + "type": "string", + "minLength": 1 + }, + "independent_review_status": { + "enum": [ + "NOT_PERFORMED", + "IN_PROGRESS", + "COMPLETED" + ] + }, + "visuals": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "required": [ + "id", + "file", + "title", + "description", + "width", + "height", + "view_box", + "claim_ids", + "public_sources", + "does_not_establish", + "approval_status" + ], + "properties": { + "id": { + "type": "string", + "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" + }, + "file": { + "type": "string", + "pattern": "^assets/visuals/[a-z0-9-]+\\.(svg|png)$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string", + "minLength": 1 + }, + "width": { + "type": "integer", + "minimum": 1 + }, + "height": { + "type": "integer", + "minimum": 1 + }, + "view_box": { + "oneOf": [ + { + "type": "string", + "pattern": "^0 0 [1-9][0-9]* [1-9][0-9]*$" + }, + { + "type": "null" + } + ] + }, + "claim_ids": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "pattern": "^[A-Z]{3}-[0-9]{3}$" + }, + "uniqueItems": true + }, + "public_sources": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + }, + "uniqueItems": true + }, + "does_not_establish": { + "type": "array", + "minItems": 1, + "items": { + "type": "string", + "minLength": 1 + } + }, + "approval_status": { + "enum": [ + "DRAFT", + "OWNER_APPROVED", + "SUPERSEDED" + ] + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +} diff --git a/tests/test_verify_publication.py b/tests/test_verify_publication.py index 82c1bf7..9126145 100644 --- a/tests/test_verify_publication.py +++ b/tests/test_verify_publication.py @@ -237,6 +237,370 @@ def test_disallowed_positioning_phrase_fails(self) -> None: path.write_text(path.read_text(encoding="utf-8") + f"\nA research {phrase}.\n", encoding="utf-8") self.assertTrue(any("disallowed positioning phrase" in error for error in verify(self.root))) + def test_em_dash_character_fails(self) -> None: + path = self.root / "README.md" + prohibited_character = chr(0x2014) + path.write_text( + path.read_text(encoding="utf-8") + + f"\nAuthority {prohibited_character} implementation.\n", + encoding="utf-8", + ) + self.assertTrue(any("prohibited em dash character" in error for error in verify(self.root))) + + def test_missing_visual_manifest_fails(self) -> None: + (self.root / "assets/visuals/manifest.json").unlink() + self.assertTrue( + any( + "missing required file: assets/visuals/manifest.json" in error + for error in verify(self.root) + ) + ) + + def test_unregistered_visual_fails(self) -> None: + source = self.root / "assets/visuals/system-map.svg" + target = self.root / "assets/visuals/unregistered.svg" + shutil.copyfile(source, target) + self.assertTrue(any("unregistered visual asset" in error for error in verify(self.root))) + + def test_visual_unknown_claim_fails(self) -> None: + path = self.root / "assets/visuals/manifest.json" + data = json.loads(path.read_text(encoding="utf-8")) + data["visuals"][0]["claim_ids"].append("ZZZ-999") + path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + self.assertTrue( + any("references unknown public claim" in error for error in verify(self.root)) + ) + + def test_visual_claim_requires_supporting_source(self) -> None: + path = self.root / "assets/visuals/manifest.json" + data = json.loads(path.read_text(encoding="utf-8")) + data["visuals"][0]["public_sources"] = ["docs/02-implementation-record.md"] + path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + self.assertTrue( + any("unsupported by its declared public_sources" in error for error in verify(self.root)) + ) + + def test_visual_requires_nonclaim(self) -> None: + path = self.root / "assets/visuals/manifest.json" + data = json.loads(path.read_text(encoding="utf-8")) + data["visuals"][0]["does_not_establish"] = [] + path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + self.assertTrue(any("visual non-claim" in error for error in verify(self.root))) + + def test_visual_review_status_matches_publication(self) -> None: + path = self.root / "assets/visuals/manifest.json" + data = json.loads(path.read_text(encoding="utf-8")) + data["independent_review_status"] = "COMPLETED" + path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8") + self.assertTrue( + any("differs from publication record" in error for error in verify(self.root)) + ) + + def test_svg_requires_accessible_title_and_description(self) -> None: + path = self.root / "assets/visuals/system-map.svg" + text = path.read_text(encoding="utf-8").replace( + '', + '<metadata id="system-map-title">', + 1, + ).replace("", "", 1) + path.write_text(text, encoding="utf-8") + self.assertTrue(any("begin with title and desc" in error for error in verify(self.root))) + + def test_svg_rejects_script(self) -> None: + path = self.root / "assets/visuals/system-map.svg" + text = path.read_text(encoding="utf-8").replace("", "