Throughstone v1.6.0

A release-readiness and operational discipline release for the Throughstone scaffold.

Highlights:

• Adds a structured security review framework: S0 Security Baseline, S1 Security Sweep, S2 Security Audit, registries/security-reviews.yml, and report templates.
• Adds durable report folders for check-ins, incidents, security reviews, and test results.
• Strengthens STEP planning with explicit test plans for code-changing work.
• Adds the doctor.sh dispatcher and local Markdown link checking.
• Improves setup/init behavior around license propagation, trunk branch selection, mono-repo origin reuse, and manual/non-GitHub remotes.
• Improves generated-project onboarding, README/site copy, artifact-trail publishing, and video guidance.

Verification:

• ./doctor.sh check
• ./doctor.sh links
• scaffold regression tests under tests/

See CHANGELOG.md for the full change list.

Throughstone v1.5.0

A risk visibility and release-notes workflow release: it adds a canonical accepted risk /
technical debt register, introduces a reusable release-notes template, and tightens the
architecture-session flow around consciously deferred work before the release is merged or
tagged.

Added

• Accepted risk and technical debt register (registries/risks.yml): a compact,
  machine-readable index for known accepted risks and deferred technical debt, with each row
  pointing to the durable source artifact that carries the full context.
• Release notes template (templates/release-notes.md): a lightweight milestone artifact
  focused on user-visible changes, action required, known issues, documentation, and technical
  references.
• Method and agent guidance requiring accepted risks to stay visible, with a source architecture
  section, ADR, issue/follow-up STEP, incident report, or check-in report created or referenced
  before a risk-register row is added.

Changed

• METHOD.md is now Method version 0.3 (beta).
• Conditional architecture sessions now record Include, Deferred, or N/A with a reason
  and revisit trigger.
• Conditional-session ownership is clearer: Native app is decided by Architecture Overview,
  Privacy/compliance by Data Model or Security, and Identity/auth by Security.
• STEP-1 bootstrap behavior is documented as a special case: init.sh reserves STEP-1, kickoff
  creates the STEP-1 PLAN, then flips it to In progress and uses step-0001-architecture
  wherever branch-per-STEP applies.
• Release/deploy and milestone-doc guidance now points agents to the release-notes template while
  keeping user-facing documentation optional and explicit.
• STEP index path wording now distinguishes workspace-root paths from docs-hub-relative paths.

Fixed

• status.sh now stops resolving STEP-1 when a substep has an unrecognized status or when no
  runnable open substep can be derived.
• Malformed STEP-index state now points users toward scripts/check.sh instead of silently
  skipping ahead.

Throughstone v1.4.0

A scaffold-update process release: it replaces the old "hand-copy upstream improvements" guidance with a conservative update model for bootstrapped projects, and tightens bootstrap and resume behavior before cutting the next tag.

Added

• Throughstone scaffold update guide (UPDATING-THROUGHSTONE.md): an advisory-first process for comparing a project to a newer Throughstone release, classifying files by bucket, reporting risk/implications, and applying only reviewed scaffold/process changes.
• Manifest + catalog model for future updater tooling: project state would live in Code/{{PROJECT}}-docs/.throughstone/manifest.yml; release implications would live in an upstream update catalog; the updater itself stays stateless.
• Three-way comparison rules (base / local / upstream) and classifications: already-current, upstream-only, local-only, diverged, untracked, protected, and manifest-invalid, with baseline-unknown handling for projects that lack a trustworthy install-time manifest.
• Mechanical risk signals for updater reports, including script changes, git/remote-touching commands, CI changes, placeholder handling, status resolver changes, incomplete update groups, and dirty affected repos.

Changed

• METHOD.md is now Method version 0.2 (beta) and points scaffold updates to the new guide instead of suggesting direct hand-copying.
• The docs hub and template README now make clear that Throughstone improvements do not apply automatically after bootstrap, project-owned state is protected, and even script updates need review.
• STEP plans and substep prompts now remind agents to calibrate implementation work to the user's recorded experience level, not only architecture-session interviews.
• README and website quickstarts now lead with the direct clone flow and clarify GitHub template setup.

Fixed

• status.sh now ignores HTML-commented example STEP rows so the next-action resolver does not treat documentation examples as real roadmap state.
• Bootstrap no longer leaves Throughstone's root README and changelog in generated projects.
• Mono-repo bootstrap now reuses a non-Throughstone root origin, while multi-repo workspaces remain detached until the user chooses remotes.
• Successful bootstrap remotes are recorded in repos.yml so setup-workspace.sh can clone sibling repos later.
• The method-check workflow can locate check.sh in both multi-repo and mono-repo layouts.
• Session 1.1's conditional-session summary includes privacy/compliance alongside native app and identity/auth.

Throughstone v1.3.0 — coding standards

A coding-standards release: it reframes the shipped standards as customizable starting points, broadens per-language coverage (adds Java and C#, plus concurrency/async and Python idioms), and introduces three cross-cutting standards — SQL, Shell, and API design — wired into the method so each surfaces at the right moment.

New cross-cutting standards

• SQL (coding-standards/sql.md): naming, formatting (sqlfluff), query practices, parameterized-query safety, schema/DDL, and migrations — secondary to the language docs where they conflict.
• Shell / Bash (coding-standards/shell.md): strict mode, quoting/safety, naming/layout, idioms, and error handling (Google Shell Style Guide + ShellCheck/shfmt); the shebang is framed as an explicit, recorded project decision.
• API design (coding-standards/api.md): an opinionated, customizable house style for REST/HTTP APIs — resource naming, methods/status codes, RFC 3339 UTC timestamps, money as integer minor units, RFC 9457 problem-details errors, idempotency, and rate limits — with three per-project forks flagged (field casing, pagination, versioning), each with an ADR pointer. Complements each API's versioned contract artifact from session 1.3.

Expanded per-language coverage

• Java (java.md) and C# (csharp.md) standards added.
• Concurrency / async sections added to Python, Rust, and TypeScript.
• Python: a Language idioms section.

Customizable by default

• Shipped standards reframed as customizable starting-point drafts — both the per-language headers and the README — so teams treat them as a draft to edit, not law to obey.
• The all-languages documentation rule broadened to fields/properties (docstrings where the language documents them, e.g. Java fields, C# properties), public and private.

Wiring

• The cross-cutting standards are reconciled by session 1.11 (kept only when each applies — a relational DB for SQL, shell scripts for Shell, an HTTP/REST boundary for API), listed in coding-standards/README.md and the METHOD.md hub gloss ("per-language plus cross-cutting"), and templates/substep-prompt.md nudges API-touching substeps to read api.md.

Full changelog: v1.2.0...v1.3.0

Throughstone v1.2.0 — discoverability & docs hygiene

A discoverability & docs-hygiene release: it indexes the runbook and registry folders, adds
the secrets-rotation runbook the operate-time set was missing, makes the session set
flexible for added/conditional sessions, and closes plain-language gaps the method's own L1/L2
standard exposed.

New operate-time runbook

• Secrets rotation (runbooks/secrets-rotation.md): scheduled rotation (inventory, cadence,
  no-downtime overlap, verify-then-revoke) and a revoke-first response to a suspected leak
  that hands off to the incident runbook. Operationalizes the threat-model §5 posture, mirroring
  how the dependency runbook operationalizes §6.

Discoverability & docs hygiene

• README indexes for runbooks/ (all five — purpose, when each fires + trigger phrase,
  governing section; STEP-shaped vs. operational) and registries/ (machine-readable state,
  pointing at repos.yml's own header rather than duplicating the schema); docs-hub rows now link
  both indexes.
• Conditional-session naming is shown, not just described: the by-name → file mapping inline
  in METHOD §4, and a copyable lettered-row example in the STEP-index seed.
• Plain-language glosses for jargon flagged against the method's own L1/L2 standard:
  API / OpenAPI / GraphQL / protobuf (session 1.3) and the RPO/RTO acronyms (session 1.8).

Flexible session set

• Session numbering no longer hardcodes the current set: the conditional-doc rule and
  status.sh review-detection adapt to added sessions; dependency-bearing sessions
  (1.5 / 1.7 / 1.8 / 1.10 / 1.11) read relevant conditional docs when present.
• Glossary session (1.12) harvests terms from every architecture doc (including conditional
  docs 13+), not a fixed range.
• METHOD §4 "Adding a session" recipe — conditional (zero-touch) vs. standard (renumber the
  cross-cutting review) wire-in checklist.

v1.1.0

This release broadens the architecture sessions, adds the operate-time runbooks the method was missing, and introduces a mechanical tooling layer (scripts + CI) that enforces rules the method previously trusted to discipline.

Broader architecture coverage

• Resilience & disaster recovery is now first-class in the Infrastructure session (1.8): failure modes / single points of failure, an availability target, graceful degradation, and backups with RPO/RTO and restore-rehearsal.
• Accessibility & internationalization in the UI session (1.7): a concrete a11y target (WCAG 2.1 AA) plus a new i18n/l10n decision in the don't-foreclose spirit.
• New conditional session — Privacy, compliance & data governance for projects handling personal/regulated data (applicable regimes, data inventory, lawful basis/consent, retention/deletion, data-subject rights, residency & sub-processors).

Stronger process discipline

• Explicit conditional-session selection: the kickoff now records a Conditional sessions considered table (Include / N-A + reason), so a skipped conditional is a deliberate, recorded choice — never a silent omission.
• Milestone doc review: at each phase/release the agent proactively raises release notes and end-user docs.
• Documentation discipline strengthened across the method; testing guidance sharpened (~80% coverage suggestion, per-step/substep test defaults).

New operate-time runbooks

• Release / Deploy / Rollback — a rollback plan before you deploy, reversible migrations, staging-first, a post-deploy watch window.
• Incident Response & Postmortem — stabilize, then open an Incident STEP (RCA → find similar → fix & harden).
• Dependencies & Supply Chain — vet before adding (license / provenance / pin) and audit on the check-in cadence (vuln scan, lockfile hygiene, SBOM).

Mechanical tooling (new)

• scripts/check.sh — the "doctor": flags and suggests a fix for duplicate STEP/ADR numbers, invalid statuses, missing architecture-doc frontmatter, and ADR registry/disk drift. Read-only; runnable in CI.
• scripts/status.sh — next-action resolver: prints "where you are · next action · check-in cadence" straight from disk; a resuming agent now runs it as its first action.
• GitHub Actions CI starter: a live method-integrity workflow (runs check.sh) plus a per-repo test-gate template.

Other

• Maintainer contact moved to hershey@throughstone.org.
• A thin pointer README at the docs-hub root.

Full changelog: v1.0.0...v1.1.0

Throughstone v1.0.0

Throughstone v1.0.0 — the first public release. 🧱

Throughstone is an architecture-first project scaffold for building real software with an AI coding agent (Claude Code, Codex, …). You bring a rough idea; the scaffold and your agent turn it into a planned, documented, well-architected project — starting with the architecture, never a mystery box.

What it does

• Think before you code — the first STEP produces architecture docs and decision records (ADRs), no application code, so the foundation is deliberate.
• Decisions get recorded — versioned architecture docs (the what) and ADRs (the why).
• Work in runnable units — phases → steps → substeps, each small enough for an agent to execute cleanly in a fresh context.
• Plain Markdown + a one-time Bash wizard (init.sh) — nothing to trust but text you can read.
• Works with any agent — thin AGENTS.md / CLAUDE.md pointers to one canonical context; the whole handoff is a single message: "Read AGENTS.md and follow it."
• Solo or team modes, multi-repo or mono-repo layouts, and per-project license stamping.

Also in this release — brand & web presence

• Brand identity: wordmark, logo set, palette, and type system (brand/BRAND.md).
• Landing page live at https://throughstone.org.
• GitHub social preview card.

Getting started

Click "Use this template", then follow the Quickstart in the README.

License: BSD-3-Clause · © 2026 Mark A. Herschberg · Throughstone™