v2.19.0

Fix (ADR-0043, idea 0037, plan 0032; amends ADR-0008): the provenance citation format dropped the patch component, so fix releases fell out of scope.

The citation was pinned everywhere as the two-component placeholder Based on decision-trail vX.Y. Because that placeholder advertises the scope at which a version is read and compared, a consumer modelled its version as major.minor and collapsed patch releases together — a repo on v2.18.1 and a target v2.18.2 both read as "v2.18", so a fix-level change went unrecognized.

Fix: pin the citation to full three-component semver vX.Y.Z across the live surfaces (adopter template, updating.agent.md read-version step + conformance item #6, adopting.md, the spec delta note, and AGENTS.md), and read the full major.minor.patch when comparing.

Adopter migration — Required

Ensure your Based on decision-trail citation carries the full three-component semver (vX.Y.Z) in both docs/working-method.md and the AGENTS.md "How we work" block. If it reads only major.minor (e.g. v2.7), append the patch of the version you are on (→ v2.7.0). From now on, cite and compare the full three-component version. An adopter already citing a full vX.Y.Z (e.g. v2.18.2) needs only the normal version bump.

v2.18.2 — reframe update step 2 as enumerate-and-copy (ADR-0042)

Bugfix release — a second patch on the copy-driven update thread.

v2.18.1 fixed the immediate miss by wording step 2's list as non-exhaustive, but step 2 was still a prose paragraph an agent interprets file-by-file — under-copying became wrong, not impossible. This patch removes the interpretation at the source.

Changed

• ADR-0042 (idea 0036 → plan 0031; amends ADR-0022) — updating.agent.md step 2 is reframed as a deterministic enumerate-and-copy rule: "copy every subfolder you detect under the source''s starter/docs/, with all contents, overwriting — except the project-authored preserve-list." Because the agent discovers subfolders instead of reading a named example list, a future scaffold subtree (like v2.18''s docs/scripts/) is picked up automatically and can''t be silently dropped — and no per-folder instruction line is ever needed. starter/ stays the single source of truth; no manifest; ADR-0022''s mechanics unchanged (execution-detail amendment only).

Adopter migration

None. Pure wording refinement — enumerate-and-copy lands exactly the same files; it only makes a future under-copy impossible to author. A fresh update naturally uses the sharper wording.

v2.18.1 — harden copy-driven re-copy against a missed scaffold (ADR-0041)

Bugfix release — decision-trail's first patch release.

A real adopter update to v2.18 skipped docs/scripts/regen-overview.ps1 because updating.agent.md step 2's example list omitted scripts/ and read as exhaustive, silently overriding the "copy starter/'s contents" instruction beside it.

Fixed

• ADR-0041 (idea 0035 → plan 0030; amends ADR-0022) — step 2's list is reframed as explicitly non-exhaustive: "copy everything under starter/, including but not limited to … and scripts/." No example list can override "copy everything" again, fixing the whole class (any future scaffold subtree), not just this file. starter/ stays the single source of truth; no manifest introduced; ADR-0022's mechanics unchanged (execution-detail amendment only).

Adopter migration (required if you took v2.18)

Re-run the step-2 re-copy of the source's starter/ into your docs/, or minimally confirm docs/scripts/regen-overview.ps1 is present and copy it from the source if absent. Repos that never took v2.18, or that already have the script, need do nothing.

The omission surfaced from a real adopter update, which is why this ships as a remediating release rather than a silent edit.

v2.18.0 — optional deterministic overview-regen script (ADR-0040)

v2.18.0 — an optional, deterministic overview.md regeneration script

ADR-0040 (idea 0033 → plan 0029).

Overview regeneration had grown from a trivial agent task into a mechanical-yet-error-prone one — five derived views over ~100 artifacts, with three drift classes already observed — pitting Economy (#2) against tool-agnosticism (#3/#7/#8). This release resolves the tension without sacrificing either: a small, deliberate crack in the "instructions-and-markdown-only" purism that leaves the promises intact.

Added

• scripts/regen-overview.ps1 (shipped to adopters in starter/docs/scripts/) — a cross-platform pwsh script that deterministically rebuilds the three family tables, the ADR → plans sub-index, and the stand-alone list, and flags non-conformant headers (bare/bullet-less block per ADR-0026; title-line ordinal disagreeing with the filename slot per ADR-0028) instead of silently copying drift — aborting rather than emitting a misfiled index.

Four guards that keep agnosticism intact

• Prose stays normative — the script is an implementation of the refresh procedure, never a second source of truth.
• Strictly optional & additive — absence changes nothing.
• Instruction-triggered, invisible to the user — the trigger is standing agent guidance (the same plain "regenerate the overview" request; the agent runs the script if present, else regenerates by hand).
• Only the output's shape is contract — the script may be reimplemented in any language or omitted; adopters lacking the runtime fall through to the prose path.

Changed

• Landed the standing trigger in starter/docs/working-method.md (an "Optional regeneration script" paragraph + docs/scripts/ layout entry), this repo's AGENTS.md derived body, and the "Keep overview.md current" guidance bullet in both AGENTS.md renderings.
• Enriched idea 0030 (kept seed) with the ADR-0040 precedent and the widened question of further mechanical economy-win candidates (a conformance lint, insert-and-shift renumbering, reciprocal-link checks).
• starter/ provenance bumped to v2.18; overview.md regenerated via the new script.

Adopter migration

None. The script is a new optional scaffold that reaches you automatically via the copy-driven "bring me current" update (it lands at docs/scripts/regen-overview.ps1). Your existing hand-regeneration keeps working unchanged, because the prose refresh procedure stays normative. To use the faster path after updating, just ask the agent to regenerate the overview.

v2.17.0 — delivered-artifacts and derived-artifacts companion folders (ADR-0039)

v2.17.0 — delivered-artifacts and derived-artifacts as optional companion folders

ADR-0039 (idea 0034 → plan 0028).

Promotes two more optional companion folders into the method — proven first in the sibling repo josyn-builder. Together with the existing intermediate-artifacts/ (ADR-0020) they form a visibly-parallel *-artifacts/ family, split by the origin of what they hold: gathered scratch, created output, derived projections.

Added

• delivered-artifacts/ — the home for content a plan creates (a report, a spec, a diagram; authored fresh, not distilled). Defined by origin, not authority — deliberately not a fourth lifecycle family or a new source of truth, so no new status, verb, or cross-link field.
• derived-artifacts/ — human-facing projections mechanically distilled from the ADRs; regenerable on request, never a source of truth, distinct from the always-present overview.md status index. A derived document should link back to the artifacts it distills (recommended, no mandated format).
• Guard split — folder mechanics (creating the folder, dropping a README, filing/moving files) are guard-free like intermediate-artifacts/; creating deliverable content follows the normal confirmation guard as real plan work, and regenerating a derived-artifacts/ document is user-triggered like overview.md.
• Two documented-but-empty starter folders under starter/docs/, mirrored by this home repo's own seeded folders.

Changed

• Landed in starter/docs/working-method.md (two companion sections + layout entries), this repo's AGENTS.md derived body + a new "Delivered / derived artifacts" guidance bullet in both AGENTS.md renderings, a note in both guides, and a regenerated overview.md.
• starter/ provenance bumped to v2.17.

Adopter migration

If your repo already uses the pre-promotion josyn-builder names, rename docs/deliverables/ → docs/delivered-artifacts/ and docs/derived/ → docs/derived-artifacts/ (use git mv to keep history) and update any links. Repos without these folders need do nothing — the empty documented starter folders arrive automatically via the copy-driven "bring me current" update.

v2.16.0 — stand-alone decision overview section (ADR-0038)

v2.16.0 — stub-plan-at-acceptance discipline + derived "ADR — stand-alone decision" overview section

ADR-0038 (idea 0032 → plan 0027), amending ADR-0011 and ADR-0034.

Added

• Stub-plan-at-acceptance discipline — when accepting an ADR that needs execution, write its plan then and there (at minimum a one-line draft stub that Implements: it), so a plan-less accepted ADR reads as "self-standing," not "forgotten."
• Derived "ADR — stand-alone decision" section in overview.md — lists every accepted ADR that no plan carries out via Implements:, regenerated in the same header scan as the ADR → plans sub-index. A review-queue backstop, not a classifier. No new field, status, or cross-link; reuses the existing draft status. ADR-0012 stands untouched.

Changed

• The section is titled "ADR — stand-alone decision" with plain-English, non-accusatory wording (leads with these decisions stand on their own).
• Title-line conformance fixes for ADR-0016 and ADR-0035 H1s.
• starter/ provenance bumped to v2.16.

Adopter migration

Regenerate docs/overview.md to gain the new section. No artifact back-migration — the stub-plan discipline is forward-looking guidance; existing accepted ADRs need no change.

Also: seeded idea 0033 (overview regeneration is mechanical yet error-prone) with measured token/determinism/purity analysis — stays seed.

v2.15.0 - Plans are mechanical execution; a surfaced question returns to the decision stage (ADR-0037)

Hardens the plan stage after a real incident in a consumer repo: an agent derived a plan whose tasks included deciding undecided things ("decide X" / "clarify Y") — collapsing the decision and plan lifecycle stages and letting decisions slip through as unreviewed plan steps, bypassing the confirmation guard.

Changed

• ADR-0037 — plans are mechanical execution; a surfaced question returns to the decision stage (idea 0031). Amends ADR-0004. A plan is for mechanical execution only and never contains a decision-making task. If a question surfaces while executing, do not fold the decision into the plan — return to the decision stage: clarify / patch / amend the governing ADR (or open a new one), then resume. That it returns is fixed; which form the return takes (patch, amend, or new ADR) is judgment sized to the question. Landed in the spec Plans bullet, the AGENTS.md derived body, a new "Plans are mechanical execution" bullet in both AGENTS.md checklists (audience-fork delta preserved), and a note in both guides. ADR-0004 stands (amended, not rewritten) with an Amended by: back-link.
• Provenance citations bumped v2.14 -> v2.15 across the three starter/ renderings.

Adopter migration

The plans rule is tightened — internalize it and apply it going forward; there is no artifact back-migration. Re-copy the method-owned set (starter/ -> your docs/) to pick up the sharpened spec bullet, the new agent-checklist bullet, and the guide note; existing plans need no rewrite. Then regenerate docs/overview.md as usual.

v2.14.0

Bundles four method threads accumulated since v2.13.

Added

• ADR-0034 — a derived ADR to plans sub-index in overview.md (idea 0028). overview.md gains a second, derived view: for each ADR, the plan(s) whose Implements: field points to it, each with its status, grouped by target ADR and built from the same header scan. Each ADR row renders as ADR-000n - Title. No new hand-maintained field and no back-link on the settled ADR; amends ADR-0011 only, leaves ADR-0012 untouched.
• ADR-0035 — enumerate two missing "lookup, not judgment call" rules in the agent operating checklist (idea 0029). Adds two bullets (decision heading transition; reciprocal cross-links) to the "Follow the spec''s mechanics" checklist in both AGENTS.md renderings, respecting the audience-fork delta. A pure discoverability/placement fix; no underlying rule change.

Changed

• ADR-0032 — audience-forked sections are a declared delta class in the sync model (idea 0026). Lets the derived-rendering sync model hold sections that legitimately differ between the home-repo and adopter renderings.
• ADR-0033 — author new artifacts from the spec, not from a sibling as a template (idea 0027). Pins "author from the spec, never from a sibling" and the proposal-heading convention (## Proposed decision while proposed, renamed to ## Decision on acceptance).
• Provenance citations bumped v2.13 -> v2.14 across the three starter/ renderings.

Adopter migration

After copying this version, regenerate docs/overview.md so it gains the new derived ADR to plans sub-index (ADR-0034). No other behavioral changes: the proposal-heading convention (ADR-0033) requires no back-migration, and the new checklist bullets and sync-model refinement reach adopters automatically via the copy-driven update.

v2.13.0

[2.13.0] - 2026-07-11

Added

• ADR-0030 — resume economy as a human-facing discipline in the guide (idea
  0023, the third and final axis of decomposed idea 0020): Economy (#2) promises
  the method is cheap to resume, but nothing named the discipline that makes
  that real for the human driving the work. The mechanics already exist (derived
  overview.md, travel diary, greppable header fields) and the agent already
  exploits them — so the missing piece is advice aimed at the levers only the
  human controls. Per the accepted decision, a short "Working with an agent:
  resuming cheaply" section is added to guide.md (both this repo's and
  starter/docs/guide.md), carrying five human levers: how you re-open the
  session, name the artifact not the topic, ask narrow, invest at pause-time not
  resume-time, and terseness as a write/approve discipline. It is purely
  advisory — no mechanism, no new artifact family, no cross-link vocabulary. It
  lands only in the human-facing guide.md register (never the always-loaded
  spec working-method.md / AGENTS.md), so it adds zero per-session weight
  and preserves ADR-0029's shrink; agent-facing mechanics (grep headers, header-
  only overview regeneration, already owned by ADR-0011 / idea 0008) are
  cross-referenced by concept rather than restated.
• All three starter/ renderings bump their provenance citation to v2.13
  (starter/docs/working-method.md, starter/docs/guide.md, starter/AGENTS.md).
• ADR-0031 — the adopter update path is human intent, agent execution (idea
  0025, promoted): the update path (adopting.md §3) read as an overcomplicated,
  deterrent human checklist even though the ADR-0022 mechanics are sound — because
  it mixed audiences, handing a present-by-definition agent's mechanical steps to
  the human. Per the accepted decision, the two audiences are split into two
  artifacts. The human trigger shrinks to one plain intent that names the
  source and the how-to file — "update the method from <source>; the how-to
  is <source>/updating.agent.md" — run as one transparent batch under the
  confirmation guard; the human must supply the source (the agent never guesses a
  target). The agent procedure moves into a new terse, self-contained,
  tool-agnostic updating.agent.md (standard-repo-only,
  not copied into adopters), the single operational source of truth for the
  copy-driven "bring me current" steps and the conformance check. Naming the how-to
  file in the prompt closes the bootstrap (hen-and-egg): an adopter on an older
  version needs no prior in-repo knowledge of the mechanism. ADR-0022's mechanics
  are unchanged — this amends it in presentation and audience framing only; a
  deterministic conformance linter stays a deferred option (ADR-0008), no tool
  ships.

Changed

• Human-facing on-ramp clarity (informal patches, no contract change). Two
  small documentation improvements folded into this release: (a) guide.md's
  "How to start" now opens with a short adoption lead-in — clone/pull the standard
  repo and follow adopting.md — before the everyday lifecycle
  steps (home-repo guide.md only; the adopter's starter/docs/guide.md keeps the
  lifecycle steps); (b) adopting.md §2 ("Inject into an existing repo") is
  collapsed from a near-duplicate of §1 down to the two real deltas (copy
  starter/docs/, and the AGENTS.md create-vs-append difference). No mechanic or
  contract changed — ADR-0021/ADR-0022 remain in force.
• Captured, then reworked (idea 0025 → ADR-0031 → plan 0021). The confusing
  update path was first recorded as idea 0025 and has now been reworked
  decision-trail: adopting.md §3 is slimmed from an 8-step human procedure to a
  single human trigger (intent + source + how-to pointer) that points at the new
  updating.agent.md; the standalone "Conformance check"
  section is collapsed to a pointer at the same file (the six-point checklist now
  lives there); and this repo's AGENTS.md "Agent operating guidance" bullet on the
  copy-driven update is updated to name the human/agent split and updating.agent.md
  as the executable source of truth. guide.md's existing adopting.md pointer is
  left unchanged (the agent-facing file stays out of the human narrative). ADR-0022
  is cross-linked Amended by: ADR-0031 (mechanics unchanged).
• Small on-the-fly guide.md wording patches (no contract change): the opening
  sentence now reads "This is the narrative introduction to decision-trail", and
  the closing "quick reference" line acknowledges that some human-facing advice
  lives only in the guide (both the canonical starter/docs/guide.md and this
  repo's derived guide.md).
• Human-facing on-ramp clarity (informal patches, no contract change). Two
  small documentation improvements folded into this release: (a) guide.md's
  "How to start" now opens with a short adoption lead-in — clone/pull the standard
  repo and follow adopting.md — before the everyday lifecycle
  steps (home-repo guide.md only; the adopter's starter/docs/guide.md keeps the
  lifecycle steps); (b) adopting.md §2 ("Inject into an existing repo") is
  collapsed from a near-duplicate of §1 down to the two real deltas (copy
  starter/docs/, and the AGENTS.md create-vs-append difference). No mechanic or
  contract changed — ADR-0021/ADR-0022 remain in force.

Adopter migration: none. This release adds human-facing advisory prose to
guide.md and re-presents the (unchanged) update path; the new updating.agent.md
is standard-repo-facing (an adopter's agent is pointed at it during an update, it
is not copied in), and the copied method text reaches adopters automatically via the
"bring me current" update (ADR-0022). No hand-done step is required.

v2.12.0 - Shrink the always-loaded agent instruction weight (ADR-0029)

ADR-0029 — shrink the always-loaded agent instruction weight (idea 0021, amends ADR-0014).

AGENTS.md is injected as custom instructions before every session and re-stated each normative rule ~twice (derived spec body + the non-derived ## Agent operating guidance block). This release states each rule once and rewrites the guidance block to principle + pointer form.

Changed

• Compacted the canonical spec starter/docs/working-method.md (15.3 KB → 13.7 KB).
• Rewrote both ## Agent operating guidance blocks (AGENTS.md, starter/AGENTS.md) to principle + pointer; removed the verbatim-duplicated Refresh procedure (now spec-only).
• Regenerated the derived AGENTS.md body (21.9 KB → 18.6 KB, ~1k tokens/session), which also reconciled two drifts: the Refresh procedure now sits in the lifecycle section, and overview-regeneration wording matches ADR-0016.
• Spec optimized agent-first; guide.md already narrates every trimmed concept, so nothing was lost (verified: no rule, status, or field name dropped).
• Provenance bumped to v2.12 across the three starter/ renderings.

Adopter migration

None. Prose-compaction only, no behavioral change; the tightened text reaches adopters automatically via the copy-driven "bring me current" update (ADR-0022).