Skip to content

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

Choose a tag to compare

View all tags
@ckluth ckluth released this 16 Jul 17:13
· 8 commits to main since this release
v2.17.0
7ebed84

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.

Assets 2
Loading