Skip to main content

S4U Methodology — Changelog

All normative changes to the canon are recorded here. The canon had no version identity before 3.0.0 (assessment 2026-06-11, finding PW-5); v2.x history below is reconstructed from downstream pointers.

3.1.2 (2026-06-13)​

Adversarial-review fixes (regressions from the heavy 3.1.x editing + structural hardening):

  • Fan-out regression fixed: the 6→7 Decision-Cost axis change had reached the canon spine but NOT the skills agents load (s4u-lifecycle, s4u-adr) — their Pre-Mortem / Decision-context block formats omitted the Cost: line, so an agent following the skill emitted a 6-axis block. Now seven everywhere; the rule-inventory and CHANGELOG editorial note are aligned too.
  • Fails closed now: check-canon-consistency.sh scans skills/*/SKILL.md + rule-inventory.md (was methodology.md-only — the hole the 6/7 drift fell through), with a pinned-defect on stale axis counts. The meta-gate's "tested" check now requires a non-comment invocation (a false # no-fixture: can no longer hide an untested script).
  • Honesty drift corrected: prose that asserted a blocking doc-staleness gate (§2.5, appendix-h) downgraded to advisory, matching the shipped exit-0 hook; the STATE.md staleness claim is now true — generate-state-md.sh emits a staleness date and check-doc-staleness.sh surfaces a STATE.md >30 days old.
  • Two real script bugs: methodology-health.sh grep -c || echo 0 crash fixed; consolidation-census.sh born-date pickaxe anchored to a word boundary (was matching auth_enabled inside oauth_enabled, inverting the age-rank). Both now invoked by the suite. Harness 92 → 102.
  • New §3.5 Incident-Response Cycle (detect → mitigate via flag-off/revert → root-cause → regression-pin → named-class postmortem → memory+STATE.md) — the missing reverse lever for a production posture. Worked Cost-axis example added.
  • pr-review.yml AI-review re-gated via a needs-output job (the job-level if: secrets.* pattern is unreliable); bootstrap now installs the doc-staleness hook; product-scale-planning skill gains a §5.6 crosswalk.

3.1.1 (2026-06-13)​

Audit-remainder polish (no rule changes; consistency, coverage, and enforcement):

  • Canon links: repointed 18 dead/circular links into the redirect-stub appendices (b/c/f/i/k/n) to their real homes (§5, §13, the relevant skills, showcase.md). §7.1 reframed "Three-Layer Defense" → "Three Core Gates + Optional Security Layer" (count now consistent). §5.2 column rekeyed Model → Capability Tier (tier is the contract; model names are point-in-time bindings). Operating-card budget stated byte-cap-primary (the enforced unit).
  • Skills now carry their mapped procedures: reviewer-dispatch mapping (s4u-code-review); R1–R3 silent-failure discipline + the 90%-in-PoC core floor (s4u-testing-standard); stale-test classification + convergent-design signal + a Superpowers prerequisite line (s4u-lifecycle); always-on subagent-dispatch hygiene + the four-status protocol (s4u-loop-dispatch); single-source pointers fixed to survive a bootstrapped project.
  • Gates that now gate: expect_err test helper (asserts the diagnostic, not just the exit code) + fixtures for previously-untested high-stakes branches; a shipped advisory templates/hooks/check-doc-staleness.sh; CI (canon-ci.yml) now runs the operating-card version header + the adr-register / doc-classification / kit-vs-project integrity gates it previously skipped; canon-consistency gains a redirect-stub-link flag; consolidation-census age-ranks flags by born-date + documents the manual retirement gate (honest over a flaky stateful auto-fail). Harness 77 → 92 checks.
  • Adoption/site: bootstrap writes a .s4u-kit-version stamp (upgrade story)
    • points adopters at .claude/agents/*.md; reviewer-agent frontmatter notes the capability tier above each model: line; the site gains local search (@easyops-cn/docusaurus-search-local) and a navbar version indicator.
  • Mandated STATE.md + memory cadence (explicit): the operating card now carries a crisp rule — every finished branch regenerates STATE.md and updates the relevant memory files in the same commit; memory also updates on any decision/correction/new-pattern mid-session; STATE.md stale >30 days is a defect (flagged by the doc-staleness hook). §3.1 Finish & Merge and the §11.4 documentation-commit pattern (now a 5th required artifact) state it as non-optional, confirmed at review.

3.1.0 (2026-06-13)​

  • §15 "Securing the AI Collaborator" (NEW spine section) — a threat model of the collaborator: 15.1 untrusted-input-is-data (the behavioral rule marked recommended (not yet enforced), with §15.4's permission gate as the enforced backstop), 15.2 secret hygiene (→ check-doc-classification.sh), 15.3 tool/MCP least-privilege + provenance (→ advisory scripts/check-tool-provenance.sh), 15.4 permission-mode tied to blast-radius. Safety sign-off: Tsunami-max, 2026-06-13 — trigger 6 cleared (see specs/2026-06-13-methodology-hardening-design.md).
  • Decision-Cost Rubric → seven axes: added Cost (compute/token spend) to §2.7, the §3.1 Pre-Mortem Block format, templates/spec-template.md, and the rubric diagram. Closes the audit's "no economic axis for subagent-heavy work".
  • Machinery: self-policing meta-gate scripts/check-test-coverage.sh (every shippable script must be tested or carry # no-fixture:); fixtures added for the 5 previously-untested scripts (harness 53→71); new project-agnostic scripts/methodology-health.sh (effectiveness trend instrument, no borrowed metrics) + scripts/adoption-smoke.sh (stack-agnosticism probe). The probe caught and we fixed a real external-validity gap: templates/project-claude.md hard-coded Python/Postgres commands outside the {{...}} placeholders.
  • SETUP-GUIDE.md retired to docs/archive/ (it taught three killed patterns); inbound pointers repointed to bootstrap.sh. setup/ADOPTION-TRIAL.md added (external-validity protocol for outside adopters).

Unreleased — editorial (2026-06-13)​

  • Non-normative: added six Mermaid diagrams to the spine, visualizing existing prose (no rule changes): the documentation knowledge-flywheel (§2.5), the the Decision-Cost Rubric diagram (§2.7), the consolidation/subtraction loop (§2.8), the four memory types feeding session context (§6.2), and — in §3.4 — the skill-chaining pipeline and the subagent orchestration model. Authored for the standalone methodology documentation site; they propagate to all sync targets.
  • Non-normative: de-projecting + readability pass across the canon. Removed all references to specific real projects and their metrics/incidents (Trust Relay, ZOL, MedChat, named framework/incident anecdotes). Every **Evidence:** paragraph that cited a project metric was replaced with a generic, mechanism-based statement (name the enforcing hook/script/gate; reproducible). Each section gained an inverted-pyramid lead (**In one line:** / **Do this:**); body prose tightened. No rules changed; all four canon gates stay green. Rationale: the methodology should read as a reusable, engaging, actionable standard — not a project case-study novel. Evidence is now demonstrated by runnable machinery, not borrowed metrics.
  • Audit-driven finishing pass (multi-agent audit, 57 verified findings). Gates: fixed the BP-5 defect in the blocking pre-push-gate.sh (was ruff check app/ --quiet; now full ruff check . + ruff format --check .), corrected its block exit code (1→2, the only code Claude Code PreToolUse blocks on), added python3 interpreter guards; broadened check-canon-consistency.sh so it actually validates s4u-* skill refs (the old regex excluded the digit 4); boundary-anchored check-adr-register.sh (was a substring match); extended check-doc-classification.sh to catch IPv6 / URL-embedded creds / cloud keys (AKIA/ghp_/glpat-/sk-/AIza), tuned to not false-match ISO-8601 timestamps; re-budgeted context-budgets.tsv onto the actually-loaded files. Test harness grew 40→53 (negative fixtures for each new branch). De-projection completed beyond docs/: README, root CLAUDE.md, the five canon-mirroring skills, and appendix-l/j/a are now project-free (the earlier "removed all references" claim is now true repo-wide); front doors repointed from the superseded SETUP-GUIDE to bootstrap.sh. Spine: removed phantom /designing,/planning skill names, de-duplicated §13, fixed the §4.3 Python-floor contradiction. Site: removed dead Docusaurus scaffold + fixed the broken social-card ref.

3.0.0 (2026-06-12)​

  • Added machine-readable version header + this changelog (PW-5).

  • §2.8 Consolidation Review written as a mechanism (census script + retirement mandate); was a dangling "(planned)" reference; cadence set to monthly (AF-1).

  • Canon consistency check shipped (the "mechanical greps" §5.6/appendix-l promised): phantom skill names fixed (/designing, /planning, /worktree, /finish, /code-review → installed Superpowers names, incl. both mermaid diagrams); freezegun three-way contradiction resolved (§8 defers to §4.5 default); §5.2 model-naming self-contradiction removed; §2.7 case-study timeline de-inflated ("month three"/"for months" → days, matching its own facts); /writing-skills added to the §4.4 table (was listed as 14, contained 13).

  • §3.1: SIXTH Brainstorm-Gate trigger — changes to safety policy / guard / refusal behavior gate hardest and require a literal human sign-off line (assessment meta-pattern C: the jury dosing incident entered through an APPROVED policy relaxation no gate covered).

  • §4.5 rule 1: verbatim-copy mandate REPLACED by single-source-plus-pointers; per-project canon mirrors retired; drift checking is mechanical (CE-5, PW-5).

  • §3.1 lifecycle v3: spec+plan merged into ONE design artifact (templates/spec-template.md); Plan Walkthrough RETIRED (zero recorded completions in 3 months) in favor of a second-party scrutiny threshold (safety path / schema / public API / auth -> fresh-context or human review); §7 gains three wrong-oracle defenses: live contract smoke (I13), migrated- schema oracle (I35), and the name-the-oracle review line (meta-pattern A).

  • §14 rewritten: Core tier = the enforced gates with documented saves (required CI checks, CODEOWNERS safety review, safety-floor evals, R1-R3); Trust Relay specifics demoted to project-specific-with-ADR; permission mode reclassified preference -> security control; NEW §14.1 multi-dev operating model (org repo, deploy lock, generated STATE.md, incident roles) (TA-02/05/06).

  • §7 gate-admission meta-rule: every gate declares cost + enforcement mechanism + retirement condition; enforced via the canon PR template (assessment §6 standing meta-rule).

  • §6 + appendix-d: hub budget restated in BYTES (24,000 — the loader's unit); durable-first section ordering is policy under truncation; advisory memory-budget Stop hook shipped; MEMORY-template reordered (CE-2).

  • Operating card extracted (docs/operating-card.md, ~7.6KB / 42 rules of 119 inventoried in docs/rule-inventory.md) — the only always-loaded surface; methodology.md demoted to reference (CE-1/CE-4/PW-1).

  • Showcase split + appendix dispositions: §12 + appendix-f -> showcase.md; appendix-c merged into §5 (specialists now OPTIONAL — resolves the flagship-forbids-them conflict); appendix-i tables merged into §13; appendices b/k/n retired to skills; appendix-e rewritten — prompt-type blocking Stop hooks REMOVED at all sites (completion-loop failure mode), command-type diff-aware advisory is the standard; appendix-m's false zol-rag Next.js claim corrected (CE-5); a/d/g/l carry superseded-by notes.

  • STATE.md policy: generated from git/gh or absent, never hand-maintained; generator shipped at templates/scripts/generate-state-md.sh (CE-8, TA-05).

2.3 (2026-05-12) — reconstructed​

  • §2.7 Decision-Cost Rubric; §3.1 Brainstorm Gate (Pre-Mortem Block).

2.2 — reconstructed​

  • §2.6 Investigative Discipline; appendix-n Documentation Excellence Passes.

2.1 / 2.1.x — reconstructed​

  • §4.5 canonical tech stack; §5.5 /loop pattern; §5.6 product-scale planning; appendices k/l/m.