Skip to content

formwork.md: requirement-quality pass against the authoring style guide - #26

Merged
brianv0 merged 1 commit into
mainfrom
claude/constitution-update-reconcile-pu86y2
Jul 24, 2026
Merged

formwork.md: requirement-quality pass against the authoring style guide#26
brianv0 merged 1 commit into
mainfrom
claude/constitution-update-reconcile-pu86y2

Conversation

@brianv0

@brianv0 brianv0 commented Jul 24, 2026

Copy link
Copy Markdown
Owner

Follow-up to the constitution reconciliation (#25, merged). That work removed banned words and metaphors; this pass audits every requirement in formwork.md against the constitution's Requirements authoring section for quality beyond word-swaps, and fixes the genuine deviations.

Scope of the audit

All 76 FW-<FAMILY>n requirements + 11 invariants were checked against the binding-statement shape (verifiable, single obligation, quantified values, genuine parent) and the prose-style rules (no intensifiers/self-description, bold reserved for defined terms/parameters/table keys). Verdict: conformant after the fixes below.

Changes

  • FW-GW7 — replaced the bare deferring word "minimal" (its own filesystem scope is minimal) with a verifiable bound: access scoped to its policy input and the stdio backends it spawns, not the host at large.
  • FW-XR9 — tightened the in-cell discussion, dropping two real-as-intensifier uses (a wall that isn't real / a feature that isn't real) for what the mechanism does (a wall it cannot install / a feature it cannot deliver).
  • real networkhost network (FW-XR5, FW-GW7, §2) — the precise term; bare "real" is a banned intensifier. The other real X uses (real kernel / Seatbelt / workload / filesystem) keep the genuine-vs-mock sense the constitution's Testing section preserves.
  • Bold discipline — bold is reserved for defined terms, parameter names, and table keys: dropped emphasis-bold from logical and (6×), not create, never, and a whole-clause emphasis; the two safety-critical not negations in §1/§9 became italic, the doc's sanctioned emphasis mechanism.

Verification

  • Every requirement ID resolves in the §10 traceability table (checked programmatically).
  • py/harness/test_requirements.py passes (ID/anchor/link canary).
  • Net diff is 15 lines, wording-only — no requirement IDs, anchors, or semantics changed.

Accepted as conformant (judgment calls, flagged for review)

  • FW-ISO1–9 are terse actorless imperatives (Enforce filesystem read scope…). The §5.3 heading names the confiner as the actor, and the constitution endorses formwork.md's compact table over the heavyweight per-requirement template, so these were left as-is rather than rewritten to The confiner shall….
  • Soft-looking words that resolve to a cited test or the §8 target — equivalent (FW-XR6→E2E-028), permissive enough (FW-ISO8→TRA2), in the common case (FW-TRA2), low-overhead/responsive (FW-TRA6→§8's numeric targets) — left as-is; each has a checkable criterion.

🤖 Generated with Claude Code


Generated by Claude Code

Audited all 76 FW-<FAMILY><n> requirements and the 11 invariants against the
constitution's Requirements authoring section, beyond the earlier banned-word
sweep. Fixes for the genuine deviations found:

- FW-GW7: replace the bare deferring word "minimal" ("its own filesystem scope
  is minimal") with a verifiable bound — access scoped to its policy input and
  the stdio backends it spawns, not the host at large.
- FW-XR9: tighten the in-cell discussion, dropping two "real"-as-intensifier
  uses ("a wall that isn't real" / "a feature that isn't real") for what the
  mechanism does ("a wall it cannot install" / "a feature it cannot deliver").
- "real network" → "host network" (FW-XR5, FW-GW7, §2) — the precise term;
  bare "real" is a banned intensifier. The other "real X" uses (real kernel /
  Seatbelt / workload / filesystem) keep the genuine-vs-mock sense the
  constitution's Testing section preserves.
- Bold is reserved for defined terms, parameter names, and table keys: drop
  emphasis-bold from logical "and" (6x), "not create", "never", and a
  whole-clause emphasis; the two safety-critical "not" negations in §1/§9
  become italic, the doc's sanctioned emphasis mechanism.

Verification: every requirement ID resolves in the §10 traceability table;
test_requirements.py passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011agPfWKjH7H2oDaqiZyvnz
@brianv0
brianv0 merged commit 2f4e2f4 into main Jul 24, 2026
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants