docs: proofread AWF config spec for W3C-style conformance#2757
Conversation
Rewrite the AWF Configuration Specification to follow W3C-style conventions consistently throughout: - Add Abstract section summarizing document purpose and audience - Restructure Status of This Document to distinguish normative from informative content - Expand §1 Conformance with full RFC 2119 keyword list, hyperlinked reference, and definitions for conforming document and conforming implementation - Rewrite §2 Processing Model in formal imperative style with ordered steps and cross-references - Rewrite §3 Precedence Rules using SHALL with highest-wins ordering and informative note - Expand §4 Data Model with a proper table of top-level properties - Normalize §5 CLI Mapping formatting: consistent use of config-only annotations and CLI-only callout - Rewrite §6 and §7 in formal W3C language - Restructure §8 Environment Merge Semantics with tables instead of bullet lists, blockquoted notes, and consistent RFC 2119 usage - Restructure §9 Credential Isolation Semantics with subsection headers matching config values and formal SHALL/MUST/MAY usage - Add Normative References and Informative References sections Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Smoke Test Results✅ GitHub MCP: Retrieved 2 merged PRs Status: PASS
|
🔬 Smoke Test Results
PR: docs: proofread AWF config spec for W3C-style conformance Overall: PARTIAL — MCP confirmed working; pre-step outputs were not injected into agent prompt.
|
🔥 Smoke Test: Copilot BYOK (Offline) Mode
PR: "docs: proofread AWF config spec for W3C-style conformance" — author: @lpcox, reviewers: Overall: PARTIAL — BYOK inference path confirmed working; pre-step smoke data was not injected (template vars unexpanded).
|
|
🔮 Codex smoke: FAIL Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "registry.npmjs.org"See Network Configuration for more information.
|
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — ✅ PASS
|
Smoke Test Results — Service Connectivity
Overall: FAIL — Neither Redis nor PostgreSQL is reachable from this runner. The service containers do not appear to be running or
|
There was a problem hiding this comment.
Pull request overview
This PR rewrites docs/awf-config-spec.md to follow W3C-style specification conventions more consistently, while aiming to preserve the existing normative requirements for AWF configuration, processing, and credential isolation.
Changes:
- Adds W3C-style document structure (Abstract, clearer conformance language, and Normative/Informative References).
- Reformats several sections into more formal, step-based and table-based specification language (processing model, data model, environment semantics).
- Tightens normative phrasing around precedence, environment merge semantics, and credential isolation behavior.
Show a summary per file
| File | Description |
|---|---|
| docs/awf-config-spec.md | Comprehensive rewrite/restructure of the AWF config specification for W3C-style conformance and clearer normative/informative separation. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 3
| ### 8.1 Merge Precedence | ||
|
|
||
| 1. **AWF-reserved variables** — proxy routing, DNS, container paths (always set) | ||
| 2. **`--env-all`** — inherited host environment (when enabled) | ||
| 3. **`--env-file`** — variables read from a file | ||
| 4. **`-e / --env`** — explicit CLI key-value pairs | ||
| Variables from the following sources are merged in order of increasing | ||
| precedence. A value set at a higher level MUST override the same-named | ||
| value from any lower level. | ||
|
|
||
| A value set at a higher level MUST override any value from a lower level. | ||
| | Level | Source | Description | | ||
| |-------|--------|-------------| | ||
| | 1 (lowest) | AWF-reserved | Proxy routing, DNS, container paths | | ||
| | 2 | `--env-all` | Inherited host environment (when enabled) | | ||
| | 3 | `--env-file` | Variables read from a file | | ||
| | 4 (highest) | `-e` / `--env` | Explicit CLI key-value pairs | |
| Placeholder compatibility values (§9.2 item 3) are not secrets and MUST | ||
| NOT be subject to one-shot protection. |
| The following secondary aliases SHOULD also be recognized: | ||
| `OPENAI_KEY`, `CODEX_API_KEY`, `CLAUDE_API_KEY`, | ||
| `COPILOT_PROVIDER_API_KEY`. |
Summary
Comprehensive proofread and rewrite of
docs/awf-config-spec.mdto follow W3C specification conventions consistently throughout.Changes
Structural additions:
Style fixes applied across all sections:
> **Note:**blocksContent preserved:
All normative requirements from the previous version are preserved. No behavioral changes.