From f88e48cae6caf80aa24dce634520d39dcd1e2e39 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 17 May 2026 16:17:32 +0000 Subject: [PATCH 1/2] Initial plan From 0ab327645aa4d24885816a8d800026b7f72711d5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 17 May 2026 16:28:32 +0000 Subject: [PATCH 2/2] feat(specs): daily SPDD spec work plan 2026-05-17 - add safeguards, DriftRecord schema, sync notes, conformance tests, and lifecycle sections Agent-Logs-Url: https://github.com/github/gh-aw/sessions/10531a0b-f21b-4ae0-8c29-d02fef519698 Co-authored-by: gh-aw-bot <259018956+gh-aw-bot@users.noreply.github.com> --- specs/aw-harness.md | 27 ++++++++++ specs/awf-config-sources-spec.md | 67 +++++++++++++++++++++++++ specs/compiler-threat-detection-spec.md | 20 ++++++++ specs/safe-output-outcome-evaluation.md | 48 ++++++++++++++++++ specs/security-architecture-spec.md | 26 ++++++++++ 5 files changed, 188 insertions(+) diff --git a/specs/aw-harness.md b/specs/aw-harness.md index 5554a2d537f..3c2e96b7061 100644 --- a/specs/aw-harness.md +++ b/specs/aw-harness.md @@ -1057,6 +1057,18 @@ The following matrix records where each normative harness requirement is enforce | §11.2.2 | MUST hard-abort on budget limit; MUST NOT continue turns after hard limit | `actions/setup/js/aw_harness.cjs` cost-tracker abort gate and post-abort turn guard | Pending (`aw_harness.cjs` not present) | | §11.2.3 | MUST isolate crashing user extensions; built-in extension failures are fatal | `actions/setup/js/aw_harness.cjs` extension loader policy checks | Pending (`aw_harness.cjs` not present) | +### 11.4 Degraded Mode & Safeguards + +This section defines normative safeguard requirements for scenarios where the harness enters a degraded operating mode due to resource exhaustion, infrastructure unavailability, or partial subsystem failure. A conforming implementation **MUST** apply all safeguards numbered below. + +1. **Budget-exhaustion shutdown path**: When the effective token budget is exhausted (hard limit reached), the harness **MUST** execute an orderly shutdown sequence: (a) immediately abort the active `AgentSession` turn via the session abort API; (b) flush all in-progress JSONL events and the step-summary buffer to their respective sinks; (c) emit a `budget_exceeded` event with `forced_termination: true` and the final cumulative token count; and (d) exit with code `1`. The harness **MUST NOT** start a new turn or accept additional tool calls after the hard-limit threshold is crossed, even if the session's internal queue contains pending callbacks. + +2. **Partial observability failure behavior**: When the OTLP exporter or the context-provenance file writer fails (e.g., network unreachable, disk full, OTLP endpoint returns a non-retryable error), the harness **MUST** continue session execution and **MUST NOT** abort the session or exit with a non-zero code solely due to the observability failure. The harness **SHOULD** emit a structured JSONL warning event to stderr identifying the failed observability sink and the error reason. Observability subsystem failures **MUST** be treated as non-fatal degraded-mode conditions; data loss in telemetry **MUST NOT** propagate as a session-level failure. + +3. **Fail-secure exit codes**: The harness **MUST** use the following exit-code contract to ensure downstream consumers can unambiguously detect failure class: exit code `0` — clean session completion with no budget abort and no fatal errors; exit code `1` — session-level failure, including hard-limit budget abort, unrecovered agent error, or failed session finalization; exit code `2` — invocation or infrastructure failure, including Pi SDK load failure, missing required configuration, or fatal built-in extension failure. The harness **MUST NOT** mask an exit code `1` or `2` condition by exiting `0`, even if the step summary was written successfully. + +4. **Degraded-mode marking**: When the harness enters any degraded mode (observability failure, extension skip, or partial artifact flush), it **MUST** annotate the step summary (if `$GITHUB_STEP_SUMMARY` is set) with a visible degraded-mode notice that identifies which subsystem is degraded and what data may be incomplete. This notice **SHOULD** include a remediation hint (e.g., "check OTLP endpoint connectivity" or "extension X was skipped due to error Y"). + --- ## 12. Compliance Tests @@ -1174,3 +1186,18 @@ OpenTelemetry specification for distributed tracing. + +--- + +## Sync Notes + +This section maps normative spec sections to their primary implementation files and directories in the `github/gh-aw` repository. Maintainers **SHOULD** keep this table updated whenever implementation files are added, renamed, or removed. + +| Spec section | Implementation file / directory | Notes | +|---|---|---| +| §5 Harness Invocation Contract; §6 Workflow Definition; §7 Single-Session Execution Model | `actions/setup/js/aw_harness.cjs` | Primary harness entry point. All session lifecycle, config loading, and prompt execution logic lives here. Pending creation (see §11.3). | +| §8 Extensions (provider-setup, cost-tracker, steering, repair, observability) | `actions/setup/js/aw_harness.cjs` (inline extension registrations) | Built-in Pi extensions are implemented as inline factory functions exported from or co-located with the harness. When extracted, each extension SHOULD move to a sibling file named `aw_ext_{name}.cjs`. | +| §10 Build and Deployment; §10.1 esbuild configuration | `actions/setup/js/` (directory); `package.json` build scripts in `github/gh-aw` | JavaScript build toolchain. The harness is compiled with esbuild; build configuration and bundle output paths are tracked here. | +| §9 Model Resolution; §11.1 General Security Requirements (token/credential handling) | `pkg/workflow/` (Go compiler — `aw_engine.go` or equivalent) | The `engine: aw` compilation path in Go generates the `config.json` that specifies the model, provider credentials, and feature flags consumed by the harness at runtime. | +| §11.2 Safeguards; §11.4 Degraded Mode & Safeguards | `actions/setup/js/aw_harness.cjs` | Budget-gating, observability-failure recovery, and fail-secure exit-code enforcement are all implemented inside the harness. | +| §12 Compliance Tests (T-AW-001 through T-AW-007) | `pkg/cli/workflows/` (integration test workflows); `actions/setup/js/*.test.cjs` (unit tests) | Harness lifecycle integration tests live in `pkg/cli/workflows/`. Unit-level tests for harness helpers reside alongside the JavaScript source. | diff --git a/specs/awf-config-sources-spec.md b/specs/awf-config-sources-spec.md index fa6cd464f44..11eabdd16fa 100644 --- a/specs/awf-config-sources-spec.md +++ b/specs/awf-config-sources-spec.md @@ -82,6 +82,8 @@ The key words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** in this section ar **CR-06**: Drift categorized as "missing in gh-aw" or "spec mismatch" MUST be remediated (merged or explicitly waived with rationale) within **5 business days** of detection. For this requirement, business days are Monday-Friday in UTC, excluding weekends. If this SLA is missed, maintainers MUST open (or update) an escalation tracking issue within 1 business day. The escalation issue MUST include an owner, unblock plan, and revised ETA. +**CR-06a (Escalation Owner Assignment)**: When opening or updating an escalation tracking issue under CR-06, the assignee **SHOULD** be determined as follows: (a) the maintainer who merged the last change to the drifted property's corresponding implementation file in `pkg/workflow/` or `actions/setup/` is the **default escalation owner** (implementation guidance: this can be determined via `git log` on the relevant file, or through PR merge history); (b) if no such maintainer is identifiable (e.g., the property has never been implemented), the escalation owner **SHOULD** default to the on-call maintainer for the `github/gh-aw` repository at the time of escalation; (c) the assigned owner **MUST** be recorded in the `Owner` field of the escalation issue template and **MUST** acknowledge the assignment by commenting on the issue within 1 business day of assignment. The escalation issue **MUST NOT** be left unassigned. + --- ## 4. Drift Detection Procedure @@ -190,6 +192,71 @@ To satisfy CR-06 tracking obligations, drift escalation records SHOULD use: The scheduled schema consistency workflow SHOULD open or update one such issue when drift remains unresolved beyond 5 business days. +### 4.5 DriftRecord Entity Schema + +A `DriftRecord` represents a single detected schema drift item produced by the drift detection procedure (Section 4.2, Step 5). All automation and agents that produce or consume drift reports **MUST** use this schema for structured drift output. + +#### 4.5.1 Formal Schema (JSON Schema) + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "DriftRecord", + "description": "A single detected configuration drift item between gh-aw-firewall canonical sources and gh-aw implementation.", + "type": "object", + "required": ["property_path", "drift_category", "suggested_action", "detected_at"], + "properties": { + "property_path": { + "type": "string", + "description": "Dot-notation path to the drifted configuration property (e.g., 'apiProxy.anthropicAutoCache').", + "examples": ["apiProxy.anthropicAutoCache", "container.dockerHostPathPrefix"] + }, + "drift_category": { + "type": "string", + "enum": ["missing_in_ghaw", "missing_in_schema", "spec_mismatch"], + "description": "Classification of the drift condition. 'missing_in_ghaw': property exists in canonical schema but gh-aw has no coverage. 'missing_in_schema': gh-aw generates a field not present in either schema. 'spec_mismatch': CLI mapping in gh-aw disagrees with the normative spec description." + }, + "suggested_action": { + "type": "string", + "description": "Human-readable remediation recommendation for this drift item (e.g., 'Add coverage for apiProxy.anthropicAutoCache in pkg/workflow/ and reconcile with docs/awf-config-spec.md CLI mapping table').", + "minLength": 1 + }, + "detected_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp (UTC) when this drift item was first detected in the current run." + } + }, + "additionalProperties": false +} +``` + +#### 4.5.2 Field Reference + +| Property | Type | Required | Description | +|----------|------|----------|-------------| +| `property_path` | `string` | **MUST** | Dot-notation config property path (e.g., `apiProxy.anthropicAutoCache`) | +| `drift_category` | `enum` | **MUST** | One of `missing_in_ghaw`, `missing_in_schema`, or `spec_mismatch` (see Section 4.2, Step 4) | +| `suggested_action` | `string` | **MUST** | Actionable remediation text; **MUST NOT** be empty | +| `detected_at` | `string` (ISO 8601) | **MUST** | UTC timestamp of detection; filesystem-safe format **SHOULD** use `YYYY-MM-DDTHH:MM:SSZ` | + +#### 4.5.3 Usage + +The drift detection procedure (Section 4.2, Step 5) **MUST** produce a list of zero or more `DriftRecord` objects. When any record has `drift_category` of `missing_in_ghaw` or `spec_mismatch`, the detecting automation **MUST** open a corrective PR (CR-05) and, if the SLA window is exceeded, an escalation issue (CR-06). The corrective PR description **MUST** embed the full `DriftRecord` list as JSON. + +**Example output (Step 5 of the drift detection procedure):** + +```json +[ + { + "property_path": "apiProxy.anthropicAutoCache", + "drift_category": "missing_in_ghaw", + "suggested_action": "Add coverage for apiProxy.anthropicAutoCache in pkg/workflow/ and reconcile CLI mapping in docs/awf-config-spec.md.", + "detected_at": "2026-05-17T16:00:00Z" + } +] +``` + ## 5. Safeguards When canonical sources in `github/gh-aw-firewall` are unavailable (GitHub outage, auth failure, transient fetch errors), agents and automation MUST apply the following safeguards: diff --git a/specs/compiler-threat-detection-spec.md b/specs/compiler-threat-detection-spec.md index 494e03beeab..e4f7c8d2fa7 100644 --- a/specs/compiler-threat-detection-spec.md +++ b/specs/compiler-threat-detection-spec.md @@ -197,6 +197,26 @@ The optimizer MUST produce one of: - A pull request containing required spec and/or implementation updates, or - A noop report explicitly stating no new threat coverage actions were required +### 6.4 False-Positive Handling + +False positives occur when a CTR rule triggers on a workflow input that is not actually unsafe. This section defines normative norms for suppressing, auditing, and resolving false-positive detections. + +1. **Author suppression mechanism**: When a workflow author believes a compiler diagnostic is a false positive, they **MUST** add an inline suppression annotation in the workflow frontmatter using the `threat-detection-suppress` key. The value **MUST** be a list of objects, each with a `rule` field (the `CTR-*` identifier), a `reason` field (human-readable explanation of why the flagged pattern is safe in this context), and an optional `expires` field (ISO 8601 date after which the suppression is no longer valid). A suppression without a `reason` **MUST NOT** be accepted by the compiler; the compiler **MUST** emit a validation error if `reason` is absent or empty. + +2. **Audit trail requirement**: Every active suppression annotation **MUST** be recorded in the compiled lock file (`.lock.yml`) manifest section so that reviewers can audit which rules are suppressed and why. The lock file **MUST** include the full `rule`, `reason`, and `expires` values for each suppression. Suppressions absent from the lock file manifest **MUST** be treated by subsequent compilations as unapproved and re-evaluated against the current CTR rule. + +3. **SLA for resolution**: Suppressions marked as false positives that affect a `MUST`-level security control (as defined in Section 5.1 — specifically those rules whose compiler action is `reject` in non-strict mode) **SHOULD** be resolved within **10 business days** — either by confirming the suppression is correct and updating the rule's detection logic to eliminate the false positive, or by removing the suppression when the workflow is corrected. The daily optimizer **SHOULD** surface unresolved suppressions older than 10 business days in its daily output. A suppression **MUST** be re-evaluated and explicitly renewed if the `expires` date passes; expired suppressions **MUST** be treated by the compiler as if they do not exist. + +### 6.5 Threat Category Lifecycle + +New threat categories do not immediately become normative rules. This section defines the lifecycle stages a threat category **MUST** pass through before it is added to the CTR rule catalog in Section 5.1. + +1. **Experimental stage**: A threat class is identified (via security research, incident analysis, or operational observation) and a tracking issue is opened in `github/gh-aw`. An experimental prototype detection implementation **MAY** be added to the compiler behind a feature flag. The threat class **MUST NOT** appear in the normative CTR catalog while in Experimental stage; it **SHOULD** be documented in a separate scratchpad or issue thread. Experimental detections **MUST NOT** cause compilation failures in production. + +2. **Candidate stage**: The threat class has a concrete detection trigger, an agreed compiler action (reject, rewrite, or warn), a stable diagnostic ID reserved in a draft spec update, and at least one test case demonstrating the detection. A Candidate threat **SHOULD** be deployed behind a feature flag for a minimum of one release cycle. During Candidate stage, maintainers **MUST** collect evidence (false-positive reports, affected workflow patterns) and document findings in the tracking issue. A Candidate threat **SHOULD NOT** be promoted to Normative without at least one successful deployment in a non-strict production workflow. + +3. **Normative stage**: The threat class is formally added to Section 5.1 and Section 8.1 via a pull request that includes: the CTR rule definition, the implementation mapping in Section 7.1, at least one test ID in Section 8.1, and a change-log entry in Section 10. The pull request **MUST** be reviewed by at least one security-focused maintainer. Once merged, the rule **MUST** be enforced by all conforming implementations. Any feature flag used during Candidate stage **MUST** be removed in the same pull request that adds the Normative definition. + --- ## 7. Implementation Mapping diff --git a/specs/safe-output-outcome-evaluation.md b/specs/safe-output-outcome-evaluation.md index 41fefe7790b..498271a351c 100644 --- a/specs/safe-output-outcome-evaluation.md +++ b/specs/safe-output-outcome-evaluation.md @@ -634,3 +634,51 @@ Start with the 5 highest-value, lowest-effort types: 5. `assign_to_agent` — important for delegation workflows These cover the majority of safe output usage. Add the rest incrementally. + +--- + +## Conformance + +### Conformance Test Table + +The table below specifies one conformance test row per safe-output type. Each row defines the expected OTel attribute value emitted by a correct evaluator, the pass condition (what must be true for `accepted`), and the fail condition (what signals `rejected`). Implementations **MUST** satisfy the pass condition and **MUST** not emit `accepted` when the fail condition is observed. + +| Output type | Expected `ghaw.outcome.type` OTel attribute | Pass condition | Fail condition | +|---|---|---|---| +| `create_pull_request` | `create_pull_request` | PR exists in open or merged state; was not closed-as-not-planned or reverted within the evaluation window | PR closed-as-not-planned, reverted, or deleted within the evaluation window | +| `create_issue` | `create_issue` | Issue exists in open state, or was closed by human action (not bot policy) within the evaluation window | Issue closed-as-not-planned by human within the evaluation window, or deleted | +| `add_comment` | `add_comment` | Comment exists on the target object at evaluation time | Comment was deleted or hidden by a human (non-bot) actor within the evaluation window | +| `add_labels` | `add_labels` | At least one of the bot-applied labels is still present on the target object at evaluation time | All bot-applied labels were removed by a human actor within the evaluation window | +| `add_reviewer` | `add_reviewer` | Requested reviewer is still listed as a requested reviewer, or has already submitted a review | Reviewer request was removed by a human actor before any review was submitted | +| `update_issue` | `update_issue` | Updated field(s) (title, body, assignee) match the values the bot submitted at evaluation time | Updated field(s) were reverted to pre-bot values by a human actor within the evaluation window | +| `update_pull_request` | `update_pull_request` | Updated field(s) (title, body, base branch) match the values the bot submitted at evaluation time | Updated field(s) were reverted to pre-bot values by a human actor within the evaluation window | +| `close_issue` | `close_issue` | Issue remains closed at evaluation time | Issue was reopened by a human actor within the evaluation window | +| `close_pull_request` | `close_pull_request` | PR remains closed (not merged) at evaluation time | PR was reopened or merged after the bot closed it within the evaluation window | +| `close_discussion` | `close_discussion` | Discussion remains closed at evaluation time | Discussion was reopened by a human actor within the evaluation window | +| `create_discussion` | `create_discussion` | Discussion exists and has not been deleted or locked within the evaluation window | Discussion was deleted or permanently locked (preventing any responses) within the evaluation window | +| `update_discussion` | `update_discussion` | Updated field(s) (title, body, category) match the values the bot submitted at evaluation time | Updated field(s) were reverted to pre-bot values by a human actor within the evaluation window | +| `create_pull_request_review_comment` | `create_pull_request_review_comment` | Review comment exists on the PR diff at evaluation time | Review comment was deleted by a human actor within the evaluation window | +| `submit_pull_request_review` | `submit_pull_request_review` | PR review record exists with the submitted state (APPROVED, CHANGES_REQUESTED, COMMENT) at evaluation time | Review was dismissed by a human actor within the evaluation window | +| `reply_to_pull_request_review_comment` | `reply_to_pull_request_review_comment` | Reply comment exists in the review thread at evaluation time | Reply comment was deleted by a human actor within the evaluation window | +| `resolve_pull_request_review_thread` | `resolve_pull_request_review_thread` | Review thread remains resolved at evaluation time | Thread was re-opened (un-resolved) by a human actor within the evaluation window | +| `push_to_pull_request_branch` | `push_to_pull_request_branch` | The pushed commit SHA is still present in the PR branch history at evaluation time | The commit was force-pushed out of the branch history by a human actor within the evaluation window | +| `mark_pull_request_as_ready_for_review` | `mark_pull_request_as_ready_for_review` | PR is no longer in draft state at evaluation time | PR was converted back to draft by a human actor within the evaluation window | +| `assign_to_agent` | `assign_to_agent` | Assignment record exists on the target issue/PR at evaluation time | Assignment was removed by a human actor before the assigned agent acted on it | +| `dispatch_workflow` | `dispatch_workflow` | The dispatched workflow run exists and reached a terminal state (success or failure) within the evaluation window | The dispatched workflow run was cancelled before reaching a terminal state; or no corresponding run record is found | +| `autofix_code_scanning_alert` | `autofix_code_scanning_alert` | Code scanning alert is in a fixed or dismissed state at evaluation time | Alert was re-opened or the fix commit was reverted within the evaluation window | +| `create_code_scanning_alert` | `create_code_scanning_alert` | Alert record exists in the repository's code scanning results at evaluation time | Alert was immediately dismissed (within the evaluation window) with no investigation action | +| `link_sub_issue` | `link_sub_issue` | Sub-issue link exists on the parent issue at evaluation time | Sub-issue link was removed by a human actor within the evaluation window | +| `hide_comment` | `hide_comment` | Comment is minimized (hidden) at evaluation time | Comment was un-hidden by a human actor within the evaluation window | +| `assign_milestone` | `assign_milestone` | Milestone assignment is present on the target issue/PR at evaluation time | Milestone assignment was removed by a human actor within the evaluation window | +| `update_project` | `update_project` | Project item field(s) match the values the bot submitted at evaluation time | Project item field(s) were reverted to pre-bot values by a human actor within the evaluation window | +| `update_release` | `update_release` | Release field(s) (name, body, tag, draft status) match the values the bot submitted at evaluation time | Release field(s) were reverted by a human actor, or the release was deleted within the evaluation window | +| `noop` | `noop` | Evaluation is skipped; no outcome is computed | N/A — `noop` always results in `ignored` | +| `missing_tool` | `missing_tool` | Evaluation is skipped; no outcome is computed | N/A — `missing_tool` always results in `ignored` | + +### OTel Backend Unavailability + +When the OTLP exporter is unavailable (e.g., endpoint unreachable, network timeout, authentication failure) during outcome evaluation, the following safeguards **MUST** apply: + +1. **Graceful degradation**: Outcome evaluation workers **MUST** complete their classification logic (determining `accepted`, `rejected`, `ignored`, etc.) regardless of OTLP exporter availability. The computed outcome **MUST** be persisted to a local audit fallback log (e.g., a NDJSON file at a known path such as `/tmp/gh-aw/outcome-audit.ndjson`) before any attempt to export to OTLP. If the OTLP export fails, the local audit log entry **MUST** still be written and **MUST NOT** be discarded. This ensures the outcome is recoverable even when the telemetry backend is down. + +2. **Audit fallback and retry**: When OTLP export fails, the evaluation worker **SHOULD** schedule a retry using an exponential back-off strategy (initial delay: 5 seconds; maximum delay: 5 minutes; maximum attempts: 5). If all retries are exhausted without a successful export, the worker **MUST** record the export failure in the local audit log with a `export_failed: true` flag and the final error reason. A downstream reconciliation process **SHOULD** periodically sweep the local audit log and re-attempt export for any entries marked `export_failed: true`. diff --git a/specs/security-architecture-spec.md b/specs/security-architecture-spec.md index 0ec18c67ebb..66a594aadae 100644 --- a/specs/security-architecture-spec.md +++ b/specs/security-architecture-spec.md @@ -1103,6 +1103,8 @@ A conforming implementation MUST provide a compliance test suite covering all MU - **T-CS-004**: Verify network configuration validation - **T-CS-005**: Verify action pinning enforcement - **T-CS-006**: Verify deprecated feature rejection +- **T-SG07-001**: Verify fail-secure behavior on schema validation error — when `gh-aw compile` processes a workflow containing a schema validation error (e.g., an unrecognized top-level key, a field with a value that violates the JSON Schema type or enum constraint), compilation **MUST** fail with a non-zero exit code and a diagnostic message identifying the invalid field and the violated schema constraint. The output lock file **MUST NOT** be written or updated when compilation fails due to a schema validation error. **Assertion**: `gh-aw compile` exits non-zero; no `.lock.yml` file is created or modified; stderr contains the schema violation description. **Expected result**: compilation failure; no output artifact produced. +- **T-SG07-002**: Verify fail-secure behavior on MUST-level requirement violation — when `gh-aw compile` processes a workflow that violates a MUST-level security requirement (e.g., declaring `permissions: contents: write` without a `safe-outputs` configuration, triggering CTR-001), compilation **MUST** fail with a non-zero exit code and a diagnostic message identifying the violated requirement by its rule identifier (e.g., `CTR-001`) and providing actionable remediation guidance. The output lock file **MUST NOT** be written or updated when compilation fails due to a MUST-level requirement violation. **Assertion**: `gh-aw compile` exits non-zero; no `.lock.yml` file is created or modified; stderr contains the rule identifier and remediation guidance. **Expected result**: compilation failure; no output artifact produced. #### 12.2.8 Runtime Security Tests @@ -1126,6 +1128,7 @@ A conforming implementation MUST provide a compliance test suite covering all MU | Output Isolation | T-OI-001 to T-OI-007 | 1 | Required | | Permission Management | T-PM-001 to T-PM-007 | 1 | Required | | Compilation-Time Checks | T-CS-001 to T-CS-006 | 1 | Required | +| Fail-Secure (SG-07) | T-SG07-001, T-SG07-002 | 1 | Required | | Network Isolation | T-NI-001 to T-NI-009 | 2 | Required | | Sandbox Isolation | T-SI-001 to T-SI-007 | 2 | Required | | Runtime Enforcement | T-RS-001 to T-RS-011 | 2 | Required | @@ -1897,4 +1900,27 @@ roles: [admin, maintainer] # Restrict to trusted roles --- *Copyright © 2026 GitHub, Inc. All rights reserved.* + +--- + +## Sync Notes + +This section cross-references the normative compliance validation document and defines the revalidation cadence for this specification. + +### Validation Document + +The compliance validation pass for this specification is documented in: + +- **`specs/security-architecture-spec-validation.md`** — records the results of the most recent full validation pass against each MUST/SHALL requirement, including test IDs, pass/fail status, and any open findings. All conforming implementations **SHOULD** consult this document to understand the current validation state before making security architecture changes. + +### Revalidation Trigger + +A full revalidation pass **MUST** be triggered and the results in `specs/security-architecture-spec-validation.md` **MUST** be updated whenever: + +1. This specification is incremented to a new minor version (e.g., `1.0.x` → `1.1.0` or higher). +2. A new MUST-level requirement is added or an existing MUST-level requirement is modified or removed in any section. +3. A security incident or CVE is attributed to a control defined in this specification. +4. The reference implementation (GitHub Agentic Workflows) ships a change that affects a control described in Sections 4–11. + +The revalidation cadence **SHOULD** also include a review of `specs/security-architecture-spec-validation.md` on every minor version bump, even in the absence of the above triggers, to ensure the validation summary table remains current. *This specification is provided under the MIT License.* \ No newline at end of file