Skip to content

docs: deduplicate normative rules in platform spec - #8

Merged
arDaraz merged 1 commit into
mainfrom
claude/platform-spec-simplify
Aug 10, 2026
Merged

arDaraz merged 1 commit into
mainfrom
claude/platform-spec-simplify

Conversation

@arDaraz

@arDaraz arDaraz commented Aug 10, 2026

Copy link
Copy Markdown
Owner

Summary

Applies a /simplify review of docs/superpowers/specs/2026-08-02-crewboss-platform-design.md (4 parallel review angles: reuse, simplification, reader efficiency, altitude). Every change preserves the spec's normative meaning — this pass removes duplicated rules that had already begun to drift, dead review-round prose, and implementation detail below the doc's contract altitude.

Changes

Duplicated normative rules, now stated once with references:

  • Sandbox denial set was enumerated in five places (15.7, 19.5, 21.2, 21.5, 31.8) with already-diverged lists; 21.2 is now the canonical denial set and the other four sites reference it.
  • Cutover barrier/spool/recovery was fully described in both 14.4 and 25.4; 25.4 now owns it, 14.4 keeps only worker-visible behavior. The emit special case is reformulated into a general rule (worker-evidence mutations are never dropped).
  • Grant consumption/revocation semantics consolidated into 21.6 (was also in 12.1 and 13.6).
  • return_state valid pairs defer to the section 13 state machines instead of being re-listed in the schema; the "never infer from…" enumeration collapsed to the deeper rule.
  • Provider-credential exclusion lists (12.1 vs 21.2) merged into one union in 21.2.
  • 15.7's per-route release schedule removed in favor of section 26's public surfaces; authority notes added so section 3 defers to the 27 matrix and 27 defers to 26.
  • Actionable severities defined once in 14.3; 15.5's prose error-code list that duplicated its own table removed.

Dead prose and altitude:

  • Removed three leftover review-round rebuttal sentences and bare restatements of the terminal-text and zero-idle-cost principles.
  • Section 4 baseline now cites the phase-1 event-log spec as authoritative; config example labeled illustrative; UUID pre-generation mechanics replaced with the atomicity invariant; frozen-Bash-code rationale dropped from the worktree adapter.

Reader efficiency:

  • 25.2 import invariants and 25.4 crash-recovery rules converted from mega-paragraphs to bulleted invariant lists (same sentences).
  • Vocabulary table gains Endpoint, Consumer, Approval, and Grant rows plus the "boss" alias.

Not changed (intentionally)

  • The 17.2 "fair sharing" tie-break remains unspecified — naming a deterministic rule is a design decision, flagged for a future design update.
  • No TOC added (GitHub renders a heading outline automatically) and no egress column added to the 21.2 profile table (would re-duplicate the prose egress rules).

Apply /simplify review findings: canonicalize the sandbox denial set
in 21.2, make 25.4 own cutover recovery, consolidate grant semantics
in 21.6, defer return_state pairs to the section 13 machines, drop
the 15.7 route-to-release schedule in favor of section 26, define
actionable severities once in 14.3, remove leftover review-round
rebuttals, and bullet the migration invariants for scannability.
@arDaraz
arDaraz merged commit d56471c into main Aug 10, 2026
2 checks passed
@arDaraz
arDaraz deleted the claude/platform-spec-simplify branch August 10, 2026 16:29
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.

1 participant