The complete guide

Overview

InsanelyGreat's Shippable States Development (SSD) is a pragmatic engineering discipline designed for solo developers and small teams who use AI — specifically Claude Code — to build production software. The system maintains a deployable, production-ready state at all times throughout the development cycle.

The core principle:

SSD synthesizes lessons from continuous deployment, trunk-based development, feature flags, and decades of software engineering failures where "90% done" meant "months from shipping." It was designed from the ground up to be operated by one person or a handful of people, with AI as a force multiplier at every step of the workflow.

The methodology is simple: maintain a deployable state at all times. The discipline is hard: no shortcuts, no "we'll fix it later," no broken code on main. The payoff is enormous: no death marches, predictable delivery, high quality, low stress — without needing a 10-person eng team to enforce it.

Why It Matters

The "90% Done" Problem

Traditional development creates a predictable trap:

Week  1–8:  "Making good progress!"
Week  9:    "We're 90% done!"
Week 10:    "Still 90% done..."
Week 11:    "Uh, still 90%..."
Week 12:    Panic, cut features, ship something broken

Why? The last 10% includes all the work no one budgeted for:

• Integration between components
• Error handling and edge cases
• Performance under real load
• Production deployment and data migration
• Security hardening and cross-browser testing
• Accessibility and documentation

The InsanelyGreat's SSD solution: Do the hard "last 10%" work incrementally throughout development, not as a crisis at the end. Claude Code skills handle the checklist so you stay focused on shipping.

The Iron Law

Every project has exactly three variables:

1. Scope — what features and capabilities ship
2. Time — when it ships
3. Quality — how well it works

Most projects are time-constrained. Declare your constraint at kickoff. Adjusting scope to meet a deadline is not failure — it's engineering judgment.

Principle 1: Constant Production Parity

Your development environment must match production as closely as possible from Day 1.

Why this works: Deployment is never "the hard part" because you do it constantly. Production issues surface immediately when they're easy to fix. You know your deployment budget from Day 1.

Principle 2: The Shippable State Invariant

At the end of each work session, the system must be in a state where:

• All tests pass
• No compilation errors
• No broken user-facing features
• Documentation matches implementation
• Could be deployed to production without embarrassment

Not required: feature-complete or meeting all goals. Just that what exists actually works.

Principle 3: Feature Flags Over Feature Branches

Long-lived feature branches are antithetical to shippable states.

# Problem: Feature branch divergence
Main:    A---B---C---D---E---F---G---H
              \
Feature:       I---J---K---L---M
                                \
                          (days of merge conflicts)

# SSD: All work on main, behind flags
Main:    A---B---C---D---E---F---G---H

Day 1: Add feature code (flag off by default)
Day 2: Expand feature (still flagged off)
Day 3: Feature works, flip flag on

All work happens on main/trunk. The feature exists in production but is invisible until ready.

if feature_flags.is_enabled("new_checkout", user=user):
    return new_checkout_flow(user, plan)
else:
    return legacy_checkout_flow(user, plan)

Principle 4: The Ratchet Principle

Forward progress only. Each commit improves the system in some measurable way.

Banned commits:

• "WIP" or "checkpoint" commits
• "Broken, will fix tomorrow"
• Commented-out code "for later"
• Partially implemented features visible to users

The ratchet mechanism — every commit must:

• Pass CI/CD
• Maintain or improve code coverage
• Be deployable

If you need to save work that's not ready: use local stash (not committed), Draft PR with "DO NOT MERGE" (not on main), or a feature flag (committed, but invisible).

Principle 5: Scope Flexibility Is a Feature

Traditional thinking: "We must deliver all planned features by the deadline."
Result: Deliver nothing on time, or deliver broken features.

SSD thinking: "We deliver whatever is shippable by the deadline."
Result: Deliver working software, adjust scope based on reality.

How to cut scope well:

• Cut entire features, not the quality of existing features
• Cut depth, not breadth (fewer powerful features beats many broken features)
• Hide features behind flags rather than deleting (easy to resurrect)
• Communicate cuts early and often to stakeholders

Pattern 1: Deployed Day One

Before writing any business logic, establish a real deployment to your distribution channel. The specifics vary by platform — pick yours:

This is your MVP. It does nothing useful, but it's real. If deployment takes 2 weeks and you budget 0 weeks, you're starting 2 weeks late on Day 1.

Pattern 2: Walking Skeleton

Build one feature end-to-end before building any feature fully complete.

Never build all UI then all backend/persistence. One complete flow first, then expand breadth. "End-to-end" means different things by platform: on web, UI → API → DB → response. On iOS, View → persist → relaunch → verify. On Android, Compose → Room → relaunch → verify. The principle is the same: one complete flow before breadth.

Pattern 3: Dark Launching

Launch features in production before they're visible to users. The pattern works across all platforms:

if feature_flags.new_dashboard and user.is_internal_tester:
    return render_new_dashboard(user)
return render_old_dashboard(user)

if featureFlags.isEnabled("newDashboard", user: user) {
    return NewDashboardView()
}
return OldDashboardView()

if (featureFlags.isEnabled("newDashboard", user)) {
    NewDashboardScreen()
} else {
    OldDashboardScreen()
}

Benefits:

• Test in production without risk
• Gradual rollout (internal → beta → everyone)
• Easy rollback: flip flag
• Development never blocks deployment

Pattern 4: Timebox with Eject

For risky or exploratory work, timebox it with a pre-committed eject plan.

"We'll spend 3 days exploring this approach.
On day 3, we decide:
  - Ship it
  - Iterate it (extend timebox)
  - Abandon it (revert to last shippable state)"

This prevents:

• Sunk cost fallacy ("we've invested so much...")
• Endless exploration without shipping
• Half-finished experiments in the codebase

Pattern 5: The Nightly Ritual

End each day with a shippable state. Spend the last 30 minutes on this checklist:

• All tests pass locally
• Code committed and pushed
• CI/CD pipeline green
• Feature flags set appropriately
• Documentation updated if APIs changed
• Tomorrow's first task identified

Your future self (or your teammate) should be able to pick up exactly where you left off, with no confusion about what state things are in.

Decision Framework

Choosing Your Constraint

At project kickoff, declare your primary constraint and communicate it explicitly.

When to Cut Scope

Scope cuts should happen early and often, not as last-minute panic.

Cut scope now if you see these signals:

• It's Wednesday and you're not confident about Friday's shippable state
• You're accumulating technical debt faster than paying it off
• Tests are being skipped "temporarily"
• "We'll clean it up after shipping" is appearing in conversations

Metrics That Matter

Deployment Frequency

This is the single most important SSD metric:

• Once per month — Traditional waterfall
• Once per week — Decent
• Once per day — Excellent
• Multiple times per day — World-class

Common Objections

"This sounds like more work"

You're doing the work either way. Option A: days 1–85 ignore deployment, days 86–100 frantic debugging, ship broken. Option B: do the hard parts incrementally every day, day 90 ship the fully-working subset you completed. Same total effort, drastically different stress and quality.

"Our stakeholders need to see progress"

SSD gives better demos. Traditional: "Here's a mockup... this button doesn't work yet... imagine when this is connected to the backend..." SSD: "Here's the actual working product. Press any button." Which demo builds more confidence?

"We need to iterate quickly"

False dichotomy. Shippable states don't slow iteration — they enable it. Every iteration is testable by real users. No integration phase blocking feedback. Pivots are cheap because sunk cost is always minimal.

"My team isn't disciplined enough"

This is exactly why you need this. Discipline problems are solved with systems, not willpower. CI/CD forces tests to pass. Can't commit broken code. Daily deployments force completion. Visible production state keeps everyone honest. SSD creates discipline through automation and forcing functions.

"This doesn't work for mobile apps"

It works. You cannot deploy to the App Store daily (review takes 1-3 days). But you CAN deploy to TestFlight / Play Internal Testing daily. SSD targets the internal deployment pipeline, not the store review process. TestFlight is your "production" for SSD purposes until you cut a release.

Feature flags on mobile use an SDK (Firebase Remote Config, LaunchDarkly). Flag changes take effect on next app launch, not instantly. When you cut a store release, it should be a non-event — you've been shipping to testers daily. For macOS desktop: notarization is your deployment gate. Automate it in CI from Day 1.

Getting Started

Four weeks to establish the SSD rhythm. Success criteria: on day 30, deploy to production with confidence in under 10 minutes.

Day 0: Bootstrap

• Install the skills: git clone https://github.com/AlexHorovitz/skills ~/.claude/skills
• Run /ssd-init once at the project root — creates the .ssd/ working directory (selective .gitignore: design docs committed, machine state ignored), writes .ssd/project.yml (detected stack/framework/platform), creates docs/decisions/, docs/runbooks/, docs/architecture/, and runs prerequisite checks
• All /ssd phases refuse to proceed until init has run

Week 1: Foundation

• Set up CI/CD pipeline
• Deploy "Hello World" to your distribution channel (production server, TestFlight, Play Internal, notarized build)
• Configure automated testing
• Establish feature flag system (server-side for web, SDK-based for mobile/desktop)
• Invoke /ssd start to run the Walking Skeleton playbook

Week 2: First Feature

• Build one feature end-to-end
• Deploy to production behind flag
• Verify in production
• Enable for internal users

Week 3: Rhythm

• Deploy to production daily
• Every commit passes CI
• All incomplete features behind flags
• Documentation current

Week 4: Optimization

• Reduce deploy time to under 10 minutes
• Increase test coverage
• Remove old feature flags
• Retrospective: what's working?

Platform-specific Day 1 checklists for iOS, Android, macOS, Web, and Headless are in Pattern 1: Deployed Day One above.

SSD 3.0

Agentic coding moved from prompt engineering to harness engineering. SSD 2.x put the rail in the skill text and asked the model to follow it. SSD 3.0 runs the rail. The default is still propose. Shipping stays a human action. There is no --force.

The harness is concrete. Grants for consequential actions live outside the repository, one use, bound to a snapshot, and a worker cannot mint one. Gate rules and schemas execute. .ssd/ keeps the record, doctor reads it, and resume continues it without restoring a grant. Three role files describe design, code, and review so the reviewer cannot edit the diff. A host has not dispatched them. Hooks reinforce that wall in process tests. They are not the authority, and a Claude Code session has not delivered an event. The offline eval harness records what ran. The live driver is wired and has not called a model. The clone install stays, and a plugin manifest sits beside it. AGENTS.md carries the contributor guide. A user project receives instructions only with consent. A session load of that file was not measured.

The rail, as AGENTS.md and the project-instruction block state it, is brief → design → code → review → gate → ship. ssd/rails.md still lists deploy, rollout-advance, and flag-removal after the gate. Those steps, and ship, sit outside an unattended run. Live model comparisons, the five-user pilot, and in-session instruction loading are NOT_RUN. A result that was not produced is not a pass. That is the same demand as True As Of: name the regime, the test, and the date. The short argument is on the SSD page. The exact boundary is what’s in 3.0, and what is not.

Install

Clone installation is kept:

git clone https://github.com/AlexHorovitz/skills ~/.claude/skills
cat ~/.claude/skills/VERSION

That clone follows main. main is library 3.0.0, so VERSION prints 3.0.0. The tag and the GitHub release are still unpublished. The tree this page describes is commit d6f23bd, which matches main as of 12 October 2026.

The same tree carries a plugin manifest. .claude-plugin/marketplace.json names the marketplace ssd. .claude-plugin/plugin.json names the plugin ssd at version 3.0.0, lists the skill directories, and has no bin/. The Claude Code commands that match those names are:

/plugin marketplace add AlexHorovitz/skills
/plugin install ssd@ssd

The release record does not include those two commands being run. Marketplace submission and a clean-host install were not run. The owner ran claude plugin validate . on a Mac with Claude Code installed. The result was “Validation passed with warnings.” Both warnings are addressed in the tree: the marketplace has a top-level description, and checkout memory lives at .claude/CLAUDE.md (@../AGENTS.md) because a CLAUDE.md at the plugin root is not loaded as plugin context. The implementation environment had no claude binary and did not re-run the command. Until you install the plugin yourself, use the clone path. Record: plugin-validate.md.

On a host that namespaces plugin skills, names look like /ssd:coder. The clone path keeps the short names (/coder). Both installs can be present. Deleting one is not required to finish the other.

AGENTS.md is the contributor guide for the skills repository. A checkout of that repository loads it from .claude/CLAUDE.md. Plugin users get the rail from the skills, especially ssd/SKILL.md. The block a user’s project receives, and only with consent, is ssd-init/references/project-instructions.md, inside a managed block. Whether a session actually loaded AGENTS.md was not measured.

Every library SKILL.md starts with Agent Skills frontmatter: name matches the directory, and description is at most 1,024 characters. The title and the **Version:** banner follow that block. ssd-init, feynman, software-standards, and codebase-skeptic set disable-model-invocation: true. A person invokes them by name. The portable export strips that field; the body sentences stay. The skill-metadata gate rule runs the checker only inside this library and SKIPs everywhere else (ADR-0021).

From 2.x

Bare /ssd still reads state and proposes the next action. An absent autonomy: block still makes no extra call. There is still no --force.

/ssd upgrade can apply the format-marker migration. It writes .ssd/format containing 3 when that file is absent, and it refuses to overwrite a marker that is not major 3. An absent marker means an older project is left unchanged. Libraries released before 3.0.0 do not read the file, so a v2.14 binary will not refuse on its own. Rollback is the backup migrate.sh writes before it mutates state. The migration does not rewrite workstreams, store links, or records (ADR-0024).

Optional v3 frontmatter fields (reviewed_snapshot, execution_method, result_status, provenance) are optional. Historical artifacts that omit them stay valid.

Doctor and resume

/ssd doctor is read-only. From the library root:

python3 methodology/ssd_cli.py doctor

Resolve that script from the SSD library, not by searching the project for a copy. Doctor reports the installation source and version, duplicate skills, the library, project, worktree, and storage roots, state health (missing, valid, corrupt, or unreadable), required dependencies, and a capability report of supported, unsupported, or unknown. Each capability names its evidence. Doctor does not install dependencies, edit permissions, repair state, or open a network connection. A corrupt state file is corrupt. It is not an empty project. A requested run mode the report cannot support is reported as effective mode propose. The configuration file is left as you wrote it.

/ssd resume <run-id> continues the same autorun record:

bash methodology/autorun.sh resume --run-id <YYYY-MM-DDTHHMMSSZ>-run.md

Resume does not reset consumed transitions, does not restore a shipping grant, and does not invent a finish when stop_reason is null. A worker that may still be alive is FM-2. A conflicting fingerprint stops with STOP-4. Clearing the lock and starting /ssd run again is a new run with fresh budgets, not a resume.

Setup, managed blocks, and removal

/ssd-init inspects before it writes. The plan command is:

python3 methodology/ssd_cli.py setup-plan --project <root>

The plan lists files that would be created or kept, the storage mode, discovered test commands, and optional permissions that stay off until you consent (git hook, GitHub issue mirror, private mode). It returns writes: 0. A discovered test command is named. It is not executed. Writing happens after you approve the list.

Text SSD adds to AGENTS.md or CLAUDE.md sits in a managed block:

<!-- ssd:managed id=project-instructions -->
… SSD text …
<!-- /ssd:managed -->

A merge replaces only the named block. Existing text outside it stays. An unclosed block is refused rather than guessed. Removal strips those blocks and deletes .git/hooks/pre-commit only when that hook is a symlink to methodology/hooks/pre-commit-no-leaky-state.sh. Removal keeps .ssd/, your source, and a foreign hook or a regular-file hook.

Roles, delegation, and hooks

Three role files describe subagents. The host did not dispatch them in the release checks, so observed delegation is NOT_RUN.

The delegation envelope schema matches only a file named delegation-envelope.yml. It is not a rail artifact. A schema-valid envelope is not authorization and is not a gate result (ADR-0022). Tests that must run go through methodology/ssdlib/executor.py: unshare user, mount, and net namespaces, then chroot. If that mechanism is missing, the result is NOT_RUN and strong-assurance review is unsupported. Inline review is labeled inline.

hooks/hooks.json calls methodology/hooks/ssd_hook.py for PreToolUse on Bash, PostToolUse on Write, Edit, and Bash, and for SessionStart, Setup, and Stop. The hook is an adapter around the authorization boundary. An empty or malformed payload grants nothing. A PreToolUse command-hook timeout does not block, which is why the control directory remains the authority. Post-tool output is feedback. Process tests of empty, malformed, deny, post-tool, and stop payloads passed. Claude Code did not deliver an event, so host delivery is NOT_RUN. The older git pre-commit script under methodology/hooks/ is a separate opt-in symlink. It is not this adapter.

Shipping grants

The default autonomy mode is still propose. /ssd ship is the human’s command. There is no --force flag. A missing autorun lock is not approval.

Grants for ship, deploy, publish, release, tag-default, rollout-advance, and flag-removal live outside the repository: SSD_CONTROL_DIR, or ~/.ssd-control/ plus the first 16 hex characters of the SHA-256 of the project path. The control directory must be outside the project. A grant is bound to the action, the repository path, and the snapshot. One use is the default. A different snapshot does not match. SSD_WORKER=1 cannot create a grant and cannot consume one. An in-repo file that says approved: true, including .ssd/control/grants.yml, is not consulted. If the guard is missing, the check fails closed (ADR-0023).

Unattended run is certified only for that jail plus the external control directory, on the Linux host that ran the suite. On any other path, doctor reports the gap and the effective mode stays propose. Your configuration is not rewritten to hide that. --until ship is still FM-4.

What was actually checked

These commands were run while preparing the release. The record is docs/releases/3.0.0/evidence.md.

Commit d6f23bd is the CI follow-up from pull request #61, and it changes only the workflow and the way a failed unit test is printed. The v3 suite job checks the repository out with fetch-depth: 0. A depth-1 checkout omits the pinned arm A baseline e732a93, and scripts/live_eval_test.py then fails real-baseline-is-present. A missing baseline stays NOT_RUN and is not copied from HEAD. When that unit-test process fails, scripts/v3_suite.py prints the lines that start with FAIL and SUMMARY. On d6f23bd all four checks completed successfully: SSD gate rules, shellcheck, gate-rules parity test, and the SSD v3 deterministic suite. The workflow still reports. It does not add required status checks. The counts in the table are the ones written in evidence.md. That file was not edited by the CI commit, and this page did not re-run the suite.

The three suite rows that are NOT_RUN are in-session instruction loading, live model repetitions, and the five-user pilot. The pilot protocol is written in usability.md. No pilot session was held.

scripts/eval_driver.py live can call Claude Code headlessly (claude -p, non-bare, so skills, hooks, and project memory can load) or the Anthropic Messages API. It checks SSD_EVAL_SPEND_CEILING before each call and during a Claude Code stream. Unknown cost stays unknown, and later calls do not start. --dry-run prints the plan and does not call a model. Held-out fixtures are not planned. Arm A stays on baseline e732a93 and is not replaced with HEAD. No live model was called while preparing this release. The runbook is live-evals.md.

Deferred: T26–T33

These optional packages were not started. They are not registered as tools, and this page does not describe them as present (tasks.md, ADR-0024).

Tagging, a GitHub release, marketplace directory listing, a clean-host plugin install, the five-user pilot, and the live eval baseline are not done yet. No --force, no automated ship, and CI stays informational: those three are excluded by design. The full inventory, with each item in one of those categories, is what’s not in 3.0. Owner actions are listed in owner-actions.md.

Claude Code Skills

InsanelyGreat's SSD is implemented as a set of orchestrated skills for Claude Code — this is what makes the methodology practical for a single developer or small team. The /ssd orchestrator sequences the right sub-skills for each development phase. Bare /ssd reads state and proposes the next action. It does not implement, and it does not start an audit. The full skill set is free for personal and internal organizational use — github.com/AlexHorovitz/skills.

Skill Taxonomy

Step 1: /ssd-init — Project Bootstrap

Run once per project before any /ssd phase. First-run housekeeping: creates .ssd/ (working directory with a selective .gitignore — design docs committed, machine state ignored), writes .ssd/project.yml (detected language, framework, platform, distribution channel), writes .ssd/gate.yml (committed gate inputs — see below), creates .ssd/current.yml (active workstreams pointer), creates docs/decisions/ / docs/runbooks/ / docs/architecture/ (committed decision records), and runs SSD prerequisite checks.

Idempotent — safe to re-run. It never overwrites existing files, never deletes anything, and appends to .ssd/init-log.md on each run.

Gate Readiness Since v2.5

Init now leaves the gate functional, not merely present. Two gate rules — tests-pass and feature-flag-present — need inputs (test_command, feature_flag_marker) to do anything. Before v2.5 nothing wrote them, so both rules SKIPped in every project SSD had ever initialized, and because the inputs would have lived only in gitignored project.yml they could not travel to a second clone or a CI runner. Step 6.5 closes both holes.

/ssd-init detects your test command most-specific-first — a project's own declared entry point beats a language default:

Note that a bare tests/ directory is not a pytest signal on its own — Rust keeps integration tests in tests/ beside Cargo.toml, and Go and JS projects use the name too, so inferring pytest from the directory alone would write a confidently wrong test_command into exactly the projects ADR-0015 exists to protect. A pytest detection requires one of the Python marker files above.

A genuinely polyglot repo with two top-of-table signals prompts rather than guessing. If nothing is detected the key is written commented out with a one-line explanation — the reader skips comment lines, so it degrades to the old SKIP with no regression, while making the missing piece visible in the file you'll actually open. An undetected or ambiguous test command is logged at MAJOR so it never sits silently inert.

The result lands in .ssd/gate.yml — the one committed .ssd/* config file, carrying only portable gate inputs:

# .ssd/gate.yml — committed gate inputs (ADR-0015). Portable across clones and CI runners.
# Machine-specific state stays in .ssd/project.yml (gitignored). gate-rules.sh reads project.yml
# first (local override), then this file (the committed floor).
test_command: pytest
# feature_flag_marker: <regex>   # set once a flag mechanism exists (see the flag BLOCKER)
# production_runtime: true       # v2.12+ — does this project have a real production runtime?

production_runtime (v2.12.0) is declared, not inferred. Rail step 2 (systems-designer) applies “for projects with real production runtime”, and for years that judgment lived nowhere, so projects it did not apply to filed thirteen near-identical paragraphs under Rail deviations — each one citing the document that sanctioned the skip. A step that never applied is scope, not a deviation. Declaring it here (committed, so it reaches CI and a second clone) is what lets deviations-recorded tell the two apart. Absent, it is assumed true: a project that has not said otherwise is treated as having users.

feature_flag_marker can't be detected before a flag mechanism exists. It's written when a known library is present (unleash, launchdarkly, growthbook — their documented call markers) and otherwise left commented, tied to the feature-flag BLOCKER that init already reports: whoever establishes the flag mechanism sets the marker.

Step 2: /ssd — The Orchestrator

SSD has one surface, progressively disclosed (SSD 2.0). The everyday path is the bare command: typing just /ssd reads .ssd/current.yml + .ssd/current.notes.yml, surfaces active workstreams, and proposes the next action — naming the explicit step it's taking so you never have to memorize the verb set. The orchestrator never silently advances a phase; it always proposes, and you accept or redirect.

The explicit phase commands below stay a first-class escape hatch — every phase is still directly invokable when you want to force a step. But the command path is a thin alias that lowers into the conversational path: a power-user shorthand, not a co-equal surface with its own state. Everything a command does, bare /ssd can propose; nothing is reachable only by command (ADR-0012).

Parallel Feature Workstreams Since v1.17

The orchestrator now treats multiple in-flight features as first-class. Up to four active workstreams per project (soft advisory limit, no hard cap), each with its own branch and an optional git worktree so two features can be edited side-by-side without checkout churn. The single-feature flow remains the default; parallel is opt-in.

At gate time, /ssd gate intersects the gated workstream's tracked file footprint with every other active workstream's footprint and surfaces overlaps as SUGGESTION-tier findings — never BLOCKER, never MAJOR. Overlap is often intentional (layered features, one workstream extends a file the other added); the orchestrator surfaces, the user judges. Running bare /ssd on any branch auto-resolves to the correct workstream via branch name → recorded mapping → prompt. The Shippable State Invariant still holds per workstream: parallelism reduces switching friction, it does not lower the bar.

Full design notes: ADR-0007 — Parallel features as first-class workstream artifacts.

Iterations Inside a Feature

A feature is one cycle by default (one design → build → review → deploy). Real features sometimes ship as multiple iterations. As of v1.5.0 of /ssd, this is a first-class concept — append #<iter-id> to any phase command:

/ssd code my-feature#3a
/ssd review my-feature#3b
/ssd ship my-feature#3b

Iter-ids match [A-Za-z0-9_-]+. The first #iter reference promotes the feature non-destructively to the multi-iteration layout (iterations/<iter-id>/ under the feature root). Single-cycle features keep the flat layout.

Multi-Round Gates

If /ssd gate fails (BLOCKER or MAJOR found), the workstream returns to coder. Re-running the gate after fixes produces a round-2 review at 04-code-review-round-2.md (or iterations/<iter>/code-review/round-2.md for multi-iter features). The orchestrator auto-numbers rounds, increments current.yml.gate_rounds, and requires closed_from_previous_round discipline on round 2+ — every closure is verified against the code, not copied from coder-status. gate_rounds: 3 on a workstream is a useful budget signal that scope cut may be wiser than another fix attempt.

The Rails — Canonical Opinionated Path

The rail in the 3.0 instructions is brief → design → code → review → gate → ship. That is the sequence in AGENTS.md and in the project-instruction block. ssd/rails.md still lists eight steps, and the three after the gate are deploy, rollout-advance, and flag-removal. Ship and those three are outside the ceiling of an unattended run. A workstream that skips a step records the deviation in current.yml.active[].rail_deviations. Deviations are not failures — they are engineering judgment captured for the record. That last sentence was aspirational until v2.13.0: measured across 15 workstreams, the field had never once been written by anything. methodology/deviation.sh writes it now, and the deviations-recorded gate rule reads it — they shipped together on purpose, because a writer nothing reads decays into the same silence. An auto-run writes zero of them, by construction. Teams with genuinely different needs fork rails.md and point project.yml.rails: at the fork.

Progressive Disclosure Changed in SSD 2.0

SSD 2.0 removed the developer-profile concept. Earlier versions carried a developer_profile field (novice | standard | expert) plus a teaching_mode toggle. One system now serves both the newcomer and the expert through progressive disclosure instead: the bare /ssd reads your state and proposes the next step in plain language, naming the explicit command it's running so you can see what the orchestrator chose and why — while every manual verb stays one hop away for power users (NeXTSTEP: lead the newcomer, never take the Terminal from the expert).

The old keys are no longer read. A pre-2.0 .ssd/project.yml that still carries developer_profile or teaching_mode is simply ignored (no crash); run /ssd upgrade for a guided clean-up that deletes the dead keys. See ADR-0012 for the rationale.

Milestone → Verify Loop

Every milestone takes a before/after snapshot and requires explicit verification:

1. Snapshot: record git SHA and metrics to .ssd/milestones/<topic>/sha-before and metrics-before.yml.
2. Deep audit: codebase-skeptic writes skeptic-before.md.
3. Refactor planning: refactor emits refactor-plan.md — every item cites a specific finding ID from skeptic-before.md. No cite → not in scope.
4. Validate: code-reviewer with remediation_mode: true on each refactor PR.
5. Deploy and confirm production health.
6. Verify (mandatory): re-run codebase-skeptic → skeptic-after.md; diff frontmatter; re-run code-reviewer on the remediation diff. The milestone is complete only when all original BLOCKER/🔴/💀 findings are ✅ closed, no new BLOCKER-severity regression was introduced, and the remediation diff has no BLOCKERs. A refactor that claims to close findings without verification is indistinguishable from wishful thinking.

GitHub Issue Tracking Since v2.3 · opt-in

Your SSD workstream state normally lives in .ssd/current.yml — invisible to anyone who isn't sitting at your checkout. Turn this integration on and the orchestrator mirrors that state to GitHub issues as each feature advances, so a teammate, a reviewer, or future-you can see live progress in the browser without pulling the repo.

It is a one-way mirror: your local .ssd/ is always the source of truth and drives the issues (create → re-label → close). SSD never reads issue state back to change a workstream — edit an issue on GitHub and the next sync simply overwrites the machine-managed block. There is no two-way reconciliation to get wrong.

Two kinds of issue, mapping onto SSD's existing hierarchy:

On every phase advance the orchestrator ensures the epic and feature issues exist, swaps the ssd:phase/* label to the new phase, and refreshes a machine-managed block in the issue body. Sync is idempotent by local title-prefix match, and it deliberately distinguishes a gh failure from a genuine empty result — on failure it refuses to create, so a flaky network can never produce duplicate issues.

An iterated workstream syncs under <slug>#<iter>:, so starting iteration B opens a fresh issue rather than re-opening the one iteration A already closed.

Closing Completed in v2.4

Closing is the only outward-destructive action, so it is double-gated: either auto_close: true or an explicit confirmation must be present. When neither is, the sync helper exits with a distinct needs-confirm status, the orchestrator prompts you, and only then re-runs with confirmation. Closing an already-closed issue is a no-op.

An epic close requires two independent answers, and neither party can close alone:

• "Are all GitHub children closed?" — answered by the sync helper, which discovers children by label query (the ssd:feature issues whose body references Epic: #<n>, matched on word boundaries so #27 never matches #270), not by parsing the epic's task list.
• "Is another iteration planned?" — answered by the orchestrator reading .ssd/current.yml.

That split is why an epic stays open when its first iteration's feature issue closes but iteration B is still queued.

A companion gate rule, issue-sync-current, watches for mirror drift — see the gate enforcement table. It is informational and SKIPs by default; it FAILs only on a hard contradiction, such as a recorded issue closed while its workstream is still active.

Enable it in .ssd/project.yml:

integrations:
  - type: github
    enabled: true
    issue_tracking: on     # default off → dormant, zero network calls
    auto_close: false      # default false → prompt once before closing; true → close automatically

Full design notes: ADR-0014 — GitHub issue state tracking.

Sub-Skill Reference

Review Tier Selection

Four skills do "review" work. Never chain all four — pick the right tier:

• /code-reviewer — every PR, always, no exceptions (≤500 changed lines)
• /codebase-skeptic — milestone reviews and pre-release audits of an owned codebase
• /software-standards — comparative/adversarial evaluation only (vendor selection, legacy onboarding, pre-acquisition)
• /feynman — when the question is not "is this good" but "is what we believe about it true": before a release or a status report that will be believed, after an incident that shouldn't have been possible, or when the build is green and you don't feel safe deploying

The Fifteen Voices Roster expanded in v1.5.0

/codebase-skeptic reviews your codebase through the perspectives of fifteen foundational engineering authorities — but it activates only the ones your code earns. A focused greenfield service might activate 3; a distributed monstrosity might activate all 15. Running an inapplicable voice produces noise, so the skill scores activation before it reviews.

v1.5.0 added the five marked new, taking the roster from ten to fifteen and widening the activation range to 2–15. The additions cover ground the original ten left thin: subtyping contracts (Liskov), coupling and message-passing (Metz), responsibility-driven design (Wirfs-Brock), empirical delivery performance (Forsgren), and organizational scaling / Conway's Law (Fournier).

The SSD Artifact Tree

Every SSD invocation produces artifacts at well-known paths relative to the project root. Sub-skills read from and write to this tree — that is what lets a session resume, a reviewer verify, and a teammate onboard. As of v1.3.0 of the orchestrator, the working directory is hidden (.ssd/) — the visible ssd/ name collided with the orchestrator skill source directory in the SSD skills repo itself.

<project-root>/
├── docs/                                  # committed decision records
│   ├── decisions/                         # ADRs from architect
│   ├── runbooks/                          # runbooks from systems-designer
│   └── architecture/                      # component diagrams, data models
└── .ssd/                                  # working dir — selective .gitignore (see below)
    ├── gate.yml                           # portable gate inputs: test_command, flag marker,
    │                                       #   production_runtime (v2.12+)                     [COMMITTED]
    ├── project.yml                        # language, framework, platform, distribution channel  [ignored]
    ├── current.yml                        # v2 schema: machine-managed workstream state          [ignored]
    ├── current.notes.yml                  # free-form context for next agent / human             [ignored]
    ├── features/
    │   └── <slug>/
    │       ├── 00-brief.md                # epic-level for multi-iter features
    │       ├── 01-architect.md
    │       ├── 02-systems-designer.md
    │       ├── 03-coder-status.md         # — single-cycle features only
    │       ├── 04-code-review.md          # — single-cycle features only
    │       ├── 04-code-review-round-2.md  # — multi-round gate output
    │       ├── 05-deploy.md
    │       ├── auto-runs/                 # — /ssd run + advance records (v2.14+)  [COMMITTED]
    │       │   └── <timestamp>-run.md
    │       └── iterations/                # — multi-iteration features only (opt-in)
    │           └── <iter-id>/             # e.g., 3a, 3b, auth-flow
    │               ├── brief.md
    │               ├── coder-status.md
    │               ├── code-review/
    │               │   ├── round-1.md
    │               │   └── round-2.md
    │               ├── deferred.yml       # carry-over ledger
    │               └── deploy.md
    ├── milestones/
    │   └── YYYY-MM-DD-<topic>/
    │       ├── sha-before
    │       ├── metrics-before.yml
    │       ├── skeptic-before.md
    │       ├── refactor-plan.md
    │       ├── refactor-prs.md
    │       ├── skeptic-after.md
    │       ├── feynman.md                 # — /feynman epistemic audit (also <feature>/feynman.md)
    │       └── verification.md
    ├── audits/                            # [ignored]
    │   └── YYYY-MM-DD-<scope>/
    │       └── standards-report.md
    └── archive/                           # closed feature + milestone directories  [ignored]

Every primary output carries YAML frontmatter (skill, version, produced_at, scope, consumed_by). Review outputs add finding_counts and a computed gate_pass. Design outputs add a deliverables block. This is what makes /ssd gate mechanically checkable and milestone verification a frontmatter diff rather than prose reconciliation.

current.yml v2 carries schema_version: 2 with per-workstream slug, phase, iteration, budget_hours, elapsed_hours, gate_rounds, rail_deviations, and blockers. The free-form sidecar current.notes.yml holds anything that doesn't fit the schema (handoff notes, scope changes, open questions). Legacy v1 files are read in compatibility mode with an opt-in prompted migration that writes current.yml.bak first — no silent rewrites.

Session Continuity

On invocation, /ssd reads .ssd/current.yml + .ssd/current.notes.yml. Each active workstream carries a budget in hours. The orchestrator flags entries that are over budget ("suggest scope reduction, not more work") and entries last-touched more than 3 days ago ("stale work that may need a fresh audit"). Closing a workstream archives its artifacts under .ssd/archive/features/<slug>/; matching notes move to .ssd/archive/features/<slug>/notes.yml so historical context stays with the work.

Private Mode Since v2.8.0 · opt-in

SSD can run with no paper trail in git. For client work, a shared repo where SSD is your personal practice rather than a team standard, an OSS contribution, or a project whose working notes are nobody else's business.

/ssd-init --private

This sets gitignore_mode: private and writes a .gitignore that tracks nothing SSD produces:

Every rail step and every gate rule still runs. Privacy is a storage and visibility posture, never a reduction in rigor. no-leaky-state becomes more load-bearing here than in any other mode, since it is what enforces the boundary.

What "private" does and does not mean

• Untracked, not encrypted. Artifacts sit in plaintext on disk.
• Not anonymous. The attribution footer is deliberately kept — anyone reading commit trailers can still tell SSD was used. Privacy here means no SSD mechanics or documentation in the tree.
• Cannot un-publish history. Switching an existing project stops future tracking. git rm --cached does not rewrite what is already pushed.

Retrofitting an existing project Since v2.9.0

/ssd upgrade --apply private-mode            # DRY RUN — shows everything, changes nothing
/ssd upgrade --apply private-mode --confirm  # applies

This is the only operation in the upgrade engine that can remove anything from git, so it inverts the engine's normal behavior deliberately: --elect mutates nothing and exits 10 (needs-confirm). Only --confirm acts.

The dry run lists every tracked path under .ssd/ and the three SSD docs/ trees — never truncated — and separates files SSD demonstrably produced from files it cannot confirm it produced, so a doc your team owns is never quietly untracked. It states plainly that untracking stops future tracking but does not rewrite published history.

An elective migration — a manifest entry that is not drift

Until v2.9.0 every entry in the migration manifest meant one thing: something this project has drifted past. Private mode is a choice, not a convention, and the manifest had no vocabulary for that. Implemented as an ordinary migration it would have been actively harmful — a mechanical entry would have let a routine /ssd upgrade --apply untrack a team's committed ADRs, and a guided one would have nagged every project forever about a posture most should never take.

The new elective: true field excludes an entry from the default sweep entirely: never listed, never PENDING, never applied by --apply, and not a participant in recorded-version advancement. It is deliberately orthogonal to kind rather than a third kind value — kind answers how an entry is adopted, elective answers whether every project should. Absent means false, so every pre-existing entry is unaffected.

Trade-offs, stated plainly

• Gate config does not travel. No committed .ssd/gate.yml can exist, so test_command and feature_flag_marker live in gitignored project.yml and do not reach a second clone or a CI runner. This knowingly reopens the root cause that gate readiness was built to fix — a cost proportional to your number of collaborators, and private mode's premise is that there are none.
• adr-delta and feynman-clean use a weaker probe. ADRs are untracked, so they cannot appear in a diff. Both rules fall back to inspecting the working tree, and say so in their output. Without that fallback adr-delta would deadlock against no-leaky-state and make the gate unpassable.

selective and blanket projects are unaffected — every change sits behind a private branch in the engine.

The Private Artifact Store Since v2.10.0 · opt-in

Private mode solves visibility — nothing SSD produces appears in the project's git history. It creates a second problem in doing so: your entire methodology record becomes untracked files on one machine. No history, no branches, no backup, one rm -rf from gone. The store solves durability without giving up the privacy.

.ssd becomes an absolute symlink into a per-project subdirectory of one separate private git repository. You keep writing to .ssd/; the bytes land somewhere version-controlled that the project cannot see.

/ssd store status                    # is this project linked? any drift?
/ssd store init  ~/private-ssd       # create/prepare the store repo (idempotent)
/ssd store link  ~/private-ssd       # DRY RUN — lists every file it would move
/ssd store link  ~/private-ssd --confirm
/ssd store commit                    # LOCAL only — never pushes
/ssd store push                      # explicit, outward, never automatic

link is dry-run by default and exits 10 (needs-confirm), because it is the one operation in SSD that moves your artifacts. It prints the complete list first, verifies a moved file reads back correctly through the link before declaring success, and never deletes the source on a cross-device fallback.

The leak the obvious implementation would have shipped

Worth stating because it is a general git fact, not an SSD quirk: a trailing-slash .gitignore pattern matches directories only, and to git a symlink is a file. So the natural .ssd/ ignore line does not match a symlinked .ssd. Git would commit the link as mode 120000 with the absolute target path as its content — publishing your home directory layout into the very repository you were keeping private. The gate's leak detector was blind in the same way, for the same reason.

The fix is three independent layers: a bare .ssd line (no slash) in the private pattern file, an exact-match entry in the gate's deny-list, and the store-link-sane rule below. That bare line must never appear in the selective pattern file — a bare pattern excluding a directory makes every ! re-inclusion beneath it inert, which would silently destroy selective mode's entire allow-list.

The Autonomy Ladder Since v2.14.0 · opt-in

Everything above describes an orchestrator that proposes and waits. That is still the default, and the default is still what most projects should run. As of v2.14.0 (ADR-0020) there are two opt-in rungs above it, in which the orchestrator may execute its own proposal — and a wall above those that is not configurable.

The one-line version: delegate walking the rails between the two decisions that bound a feature — the brief at the start and the ship at the end — with the executable gate as referee and a written record of every step.

With no autonomy: block in .ssd/project.yml, the orchestrator makes no additional call at all — not a call that returns the default, no call. That is what makes “byte-identical to v2.13.0” a property you can check rather than a reassurance you have to accept.

Why the feature has this shape

The highest-frequency, lowest-judgment interaction in a mature SSD project is the coder → reviewer → coder loop until the gate passes. Every ingredient of a safe agent loop already existed: the gate is executable, sub-skill outputs carry machine-readable frontmatter, and the rails are a named canonical sequence. What was missing was a sanctioned posture in which the orchestrator may act on its own, and a durable record of what it did unattended.

A feature is bounded by two decisions that are irreducibly human: the brief — what are we building, and is it worth building — and the ship — is this good enough to put in front of people. Everything between them is mechanical and refereed by a script. Autonomy delegates the middle and neither end. That is the whole design, and the rest of this section is the consequences of taking it seriously.

Rule-zero forbids silence, not autonomy

The one genuinely inviolable rule in the library is that the orchestrator never advances a phase without surfacing the decision. The reading that would forbid this feature entirely is “surfaced” = “a human approved it.” That is not what the rule says, and the distinction is load-bearing. Under a rung, surfaced means announce → log → act, in that order:

1. Announce — the transition is narrated, naming the lowered command (→ /ssd code auth-flow), so an attended user sees it before it happens.
2. Log — the transition is appended to a durable record on disk before the phase runs.
3. Act — and only then.

The ordering is the whole claim. Announce-then-act is a courtesy that evaporates when nobody is watching — which is the only condition under which this feature gets used. Log-then-act means state lags reality by at most one announced step, and that is precisely what makes recovery from an orchestrator death possible at all. The orchestrator acts only on a success response from the logger, so a failed write aborts the act.

The delegation wall

--until accepts design, code, review, gate. ship, deploy, rollout-advance and flag-removal are refusals, not settings, at every rung. There is no configuration key that moves this line.

What an auto-run can and cannot do

Read this before enabling run, because it is the part with real consequences. Under propose, a human reads every proposal before any sub-skill runs. That human has been an unacknowledged security control, and /ssd run removes them for up to budget_transitions consecutive phases. Naming it is the honest way to offer the feature.

None of those refusals has a bypass flag, and the absence of a bypass flag is the feature. This library already shipped one override that existed only in prose — see the correction in gate enforcement below — and a bypass added for convenience is how you get it back.

Why an auto-run records zero rail deviations

A deviation is engineering judgment captured for the record. An agent that can record its own deviations can rationalize its own shortcuts, and a record whose entire value is that a human decided something and wrote down why becomes a log of the agent agreeing with itself.

So needing a deviation is a stop condition, and the enforcement is structural rather than behavioral: the referee validates every transition against the rails successor table and cannot express an off-rails edge, and because the act is conditional on a successful log, a transition it refuses is a phase that does not run. The autonomy script never calls the deviation writer; the two share one lock file and one of them is not reachable from the other.

Configuration

In .ssd/project.yml under ssd:. ssd-init and /ssd upgrade --apply write this block commented out — uncommenting it is the opt-in:

  autonomy:
    mode: propose                # propose | advance | run   (absent block => propose)
    max_review_loops: 3          # coder<->reviewer rounds per gate attempt before STOP-1
    budget_transitions: 12       # phase transitions per invocation before STOP-3
    budget_wall_minutes: 30      # wall-clock cap per invocation; 0 = uncapped
    announce: full               # full | compact

• Exactly three literals are recognized for mode:. An unrecognized value is a refusal that quotes what it found — never a silent default. This follows the gitignore_mode precedent, where a misspelled mode once disabled leak detection without saying so.
• /ssd run works with the block absent, using the defaults above. mode: run only changes what bare /ssd offers.
• budget_wall_minutes bounds starting new work, not the call in flight. It is checked between phases, so one long sub-skill can overrun it. A 30-minute cap is not a 30-minute guarantee.
• announce: compact suppresses the reason line in the terminal only. The record always carries it — a record that is thinnest exactly when something went wrong unattended is not a record.

advance — the low-commitment rung

With mode: advance, bare /ssd executes its top proposal iff the existing decision tree resolves to exactly one unambiguous next action for exactly one workstream. It announces the lowered command, appends a record entry, runs that one phase, and stops. At most one phase per invocation, unconditionally — there is no accumulation.

It falls back to propose behavior verbatim when there are multiple workstreams and no branch resolution, when the proposal is a question rather than a command, when the next step is ship or beyond, or when any stop condition already holds. Fallback is not a failure and not a deviation. In practice this rung means you stop typing the obvious next command while staying in the loop at human speed.

/ssd run — the rung where the character changes

/ssd run [<slug>[#<iter>]] [--until <phase>] [--max-loops N] [--budget-transitions N] [--dry-run]

--until defaults to gate. --dry-run prints the transition plan and exits, writing nothing — the right first invocation on any project. The run resolves the workstream, opens a record and a lock, then loops announce → log → act until a stop condition fires, and hands back with a summary and a handoff note.

Interjection is a pause. Any user message mid-run is a stop. The currently executing sub-skill finishes — never a half-written artifact — and the run hands back. Delegation is revocable mid-flight; re-invoking resumes from recorded state as a fresh invocation with fresh budgets.

A stop reason is not an outcome

This one generalizes well past SSD, and it was found in review rather than in design. The first version of the record had a field for why the run ended and none for how it went — so a run that reached the ceiling with a green gate and a run that reached it with a red one produced byte-identical frontmatter, both reading stop_reason: STOP-7, described in the specification as “normal completion.”

The named consumers of these records are /codebase-skeptic and /feynman, whose shared purpose is catching the sentence “the run completed” standing in for “the run ended.” A record that cannot tell those apart launders the distinction. So a run now records gate_result — the exit status of the gate script, a number from a program rather than a boolean an LLM wrote about its own work — alongside stop_reason, and derives an outcome from the pair:

Running out of budget is not a verdict on the code, which is why exhausting a budget is incomplete and not red. Where the reviewer’s own gate_pass and the executable gate disagree, the hand-back names both referees rather than picking one.

Stop conditions and refusals

Refusals happen before the run starts: an unresolvable workstream, a run already in flight, nothing to do, an out-of-ceiling --until, an unrecognized mode, or closing a gate-phase run with no verdict. Stops happen after it started, and hand back:

The referee

The orchestrator still executes phases in prose, exactly as it does today. A script — methodology/autorun.sh — decides whether it may, because a mechanism described only in prose is a mechanism that does not exist. That is not a general principle borrowed from elsewhere; it is the lesson of this library’s own --force failure, documented in four files for eleven releases while no script accepted the flag.

So every guarantee that could be moved into an exit code has been: the mode literal, the delegation wall, the rails successor table, all three budgets, record-before-act, the lock, and the refusal to close a gate-phase run with no verdict. The subcommands are preflight, status, plan, start, transition, finish and clear. It takes the same .ssd/current.yml.lock the deviation writer takes, so the two writers are mutually exclusive and no new lock file enters your project.

The record lands at .ssd/features/<slug>/auto-runs/<timestamp>-run.md — committed under selective mode, untracked under blanket and private, the same tier as a coder-status report. stop_reason is null while a run is in flight, which is how a crashed run is found.

The failure you will actually hit

An orchestrator death between start and finish leaves the lock held, and every subsequent run refuses while naming it. That is the new operational failure mode this feature introduces, and it is deliberately manual to clear:

bash methodology/autorun.sh status                      # what is held, and its record
bash methodology/autorun.sh clear --slug <slug>         # dry run: prints, changes nothing
bash methodology/autorun.sh clear --slug <slug> --confirm

Read the record first. Its last transition entry names the last phase that was announced, and therefore the last phase that may have run — verify the working tree against it, then clear. Age-based auto-expiry was considered and rejected: a silently-expired lock resumes a run whose working tree nobody checked, and a blocked run is loud and recoverable.

What is not enforced, stated rather than implied

Three things this section would be lying about if it left them out:

• Interruption is best-effort. It depends on the orchestrator noticing your message. There is no signal handler, and prose cannot build one.
• Sub-skills are not atomic. “Finish the current sub-skill” is an instruction, not a guarantee. A phase that half-writes an artifact and then fails leaves that artifact behind; the run hands back rather than retrying.
• advance can act once on misread state. One phase per invocation bounds the damage and the successor table constrains it; nothing prevents it.

One more, on the record itself: gate_result is a script’s exit status relayed by the orchestrator, because the gate script writes no file for anything to read independently. The relay is verifiable after the fact — re-run the gate on the same commit — and capturing the gate’s output to a file is what turns the relay into an artifact.

Should you turn it on?

The useful question is not whether you trust agents in the abstract. It is how executable your gate actually is, because an auto-run inherits the quality of its referee and nothing else.

If tests-pass is a live rule on your project rather than a permanent SKIP, if feature_flag_marker is set, and if your gate census reads mostly PASS rather than mostly SKIP, then the middle of the rails is genuinely mechanical for you and delegating it buys real time. If your gate SKIPs six rules out of ten, a green auto-run means “nothing that ran objected” — a far weaker sentence than it looks, and the census, not the exit code is what tells you which one you have. Finish the gate before delegating to it.

Beyond that, a reasonable progression: run --dry-run first; then live on advance, which never accumulates more than one phase of consequence per invocation; then run with a low budget_transitions on a feature whose brief you are confident in. The brief is the input the ceiling cannot protect you from — the wall stops an agent shipping, it does not stop it building the wrong thing well. That is the decision the design deliberately left with you.

What 3.0 adds on this ladder

The rungs are unchanged. propose is still the default, and the default is still an absent block. 3.0 adds the boundary around them.

• Resume continues the same record. It does not reset the budget and it does not restore a shipping grant. See Doctor and resume.
• Fingerprint replay. The same fingerprint on the same edge returns success and does not append. The same fingerprint on a different edge is STOP-4, the existing stop for “continuing would mean guessing.” There is no new stop number. Child transitions count against the same budget.
• Grants live outside the repo. Ship, deploy, publish, release, tag, rollout, and flag removal need a one-use, snapshot-bound grant in the control directory. A lock is not a grant. See Shipping grants.
• Unattended run is not certified on every host. The certified adapter is the unshare jail plus the external control directory on the Linux host that ran the suite. Elsewhere the effective mode is propose, and the configuration file is not rewritten.

Methodology-Backed Gate Enforcement

As of v1.4.0 of the orchestrator, gate enforcement is an executable shell script, not LLM-internal checks. Before /ssd gate passes, the orchestrator invokes:

bash methodology/gate-rules.sh --base <base-branch> --json

Each rule emits PASS | FAIL | SKIP. Any FAIL exits non-zero and the gate refuses to pass. The same script is invocable from CI for parity.

bash ~/.claude/skills/methodology/gate-rules.sh --base main --json

Two rules read their inputs through a fallback chain (gate_input(), added in v2.5.0): .ssd/project.yml first — your machine-local override — then the committed .ssd/gate.yml, the portable floor every clone and CI runner sees. That is what makes tests-pass and feature-flag-present live rules rather than permanent SKIPs, and what lets the same gate-rules.sh invocation behave identically on your laptop and in CI. See Gate Readiness above.

As of v2.6.0 the gate says that out loud. Reading the exit code alone was the whole problem: a gate exits zero whether every rule passed or half of them passed and half skipped. Every human-readable run now ends with a census, and --json carries the same numbers as pass_count / skip_count alongside the existing fail_count:

# the SSD skills library's own gate on the v2.11.0 release branch
GATE 8 pass · 3 skip · 1 fail — a skip is a check that did not run

Expect skips, and expect more of them in a normal project than in the library repo — a small feature leaves adr-delta below threshold, migration-manifest-current applies only inside the library, and the two validator-backed rules need vendoring. The point of the line is not to drive the skip count to zero; it is that you can no longer read a green gate without seeing how much of it ran.

Turn a permanent skip into a recorded decision. Some rules will never apply to your project, and that is fine — what isn't fine is being unable to tell that case apart from configuration you forgot. The convention (v2.6.0) is to say so in .ssd/gate.yml, next to the key you deliberately left unset:

# feature_flag_marker is intentionally unset. This repo ships markdown skills and
# bash/python enforcement — it has no runtime feature-flag system to grep for, so
# `feature-flag-present` SKIPs by design rather than by omission.
# feature_flag_marker: <marker>

This is a convention, not a mechanism — nothing parses that comment and no rule changes behavior because of it. The census still counts the skip. What changes is that the next person to read a 5 pass · 4 skip line can tell which skips were chosen and which were merely inherited, which is the whole difference between a known gap and an unknown one.

That line, and the per-rule coverage counts above it, came out of a /feynman audit pointed at the SSD library itself. frontmatter-valid reported "51 artifact(s) validated" while 34 artifacts had no matching schema at all; skill-version-sync reported "9 skill example(s) match" while two skills — including /ssd, the orchestrator — were structurally exempt. Neither line was false. Both were misleading, which is the grade that does the most damage precisely because the sentence is true.

Enforcement is warnings, not walls (SSD 2.0, ADR-0012). A "hard rule" means strongly discouraged and loud when broken: the gate surfaces the violation unmissably and exits non-zero, rather than the system physically locking the merge. SSD trusts the developer; it does not lock the door. The one thing it never does silently is advance a phase without surfacing the decision.

See ADR-0005 for why the rules run as a bash script rather than orchestrator-internal LLM checks.

Hard Rules