v0.9.1

What's Changed

• docs: Narrow the PBI rule and route decisions by @rodolfo-mendes in #27
• feat: Add the site by @rodolfo-mendes in #42
• fix: Let GitHub read pages.yml by @rodolfo-mendes in #43
• feat: Name the site in README.md and verify it for Google Search by @rodolfo-mendes in #54
• feat: Show a breadcrumb's title in the report's diagrams by @rodolfo-mendes in #56
• docs: Give each ADR and PBI a title in its breadcrumb by @rodolfo-mendes in #57

Full Changelog: v0.9.0...v0.9.1

v0.9.0

Four additions since v0.8.0, and one change to bcr verify.

breadcrumb.rules: a repository declares its shape

A repository may now say which types its breadcrumbs have, which links
are allowed between them, and which types carry claims, in a file
called breadcrumb.rules at its root:

type	ADR
type	spec
type	PBI
link	ADR	constrained_by	ADR
link	ADR	supersedes	ADR
link	spec	constrained_by	ADR
link	PBI	changes	spec
claims	spec

bcr verify reads the file from the current directory and reports
every breadcrumb, link or claim that goes beyond it, as problems at the
record that breaks the shape. The shape is closed: what no line allows
is a problem. A malformed line is a problem at its line in
breadcrumb.rules, and then no shape is checked. With no file, nothing
changes: bcr verify checks ids and links as before.

This is the first release that reads the file. An older bcr
ignores it. A workflow written by bcr init 0.8.0 keeps installing
0.8.0, so a repository that adds breadcrumb.rules gets no shape
checks in CI until it moves to this release: delete
.github/workflows/breadcrumbs.yml and run bcr init again.

Details: docs/bcr.md, verify,
ADR-0025.

bcr init --layout asdlc

A repository that follows ASDLC is set up in one
step:

bcr init --layout asdlc

Besides the pieces bcr init always writes, it sets up ASDLC's
layout, following ASDLC's own conventions: a .breadcrumbs that names
docs/adrs/*.md, specs/*/spec.md and tasks/*.md, a
breadcrumb.rules with the shape above, a template for each of the
three (docs/adrs/TEMPLATE.md, specs/TEMPLATE.md,
tasks/TEMPLATE.md, kept out of .breadcrumbs), and a ## ASDLC
section in the agents file that says where each document goes. For
the links allowed, the section points to breadcrumb.rules.

A layout's files work only together, so --layout refuses when
.breadcrumbs or breadcrumb.rules is already there, and exits 2; to
set the layout up again, delete both. A layout bcr does not know is a
usage error that names the ones it knows.

Details: docs/bcr.md, init,
ADR-0027.

bcr filter

A new command that prints only the records matching its flags,
unchanged, wherever records flow:

bcr extract | bcr filter --id ADR-0019
bcr extract | bcr filter --object ADR-0019
bcr extract | bcr filter --type ADR
bcr extract | bcr verify | bcr audit | bcr filter --kind verdict --id ADR-0019

--id selects a breadcrumb's own records, --object the links that
point to it, --type the breadcrumbs of a type, and --kind records
by their first field. A flag given twice matches either value; flags
of different kinds must all match. bcr filter judges nothing, so it
comes after the stages that do.

Details: docs/bcr.md, filter.

The agents section shows the lookups

The ## Breadcrumbs section bcr init writes to the agents file now
shows how to look breadcrumbs up with bcr filter instead of
searching the files: one breadcrumb by its id, every breadcrumb of a
type, what links to a breadcrumb, and a breadcrumb's verdict. A
section written by 0.8.0 is left as it is; add the commands by hand.

Changed

• bcr verify now reads claim records, for the id, path and line
  of each. A malformed claim record stops it with exit status 2, as
  it already stopped bcr audit. Records printed by bcr extract are
  unaffected.
• The .breadcrumbs and breadcrumb.rules that bcr init writes
  start with a comment naming the command and the release, such as
  # bcr init, bcr 0.9.0.

Install

go install github.com/rodolfo-mendes/breadcrumb-sdd/cmd/bcr@v0.9.0

or an archive below, checked against bcr_0.9.0_checksums.txt. Each
archive holds bcr, bcr.1, README.md and LICENSE.

Full changelog: v0.8.0...v0.9.0

v0.8.0

v0.8.0 replaces the model of v0.7.0. It does not read breadcrumbs/, and has none of the old commands: a repository set up with v0.7.0 stays on v0.7.0.

The model

• A breadcrumb is YAML front matter, under the breadcrumb key, in a document the repository already keeps: an ADR, a spec, a task. .breadcrumbs names, by pattern, the files that carry one.
• A breadcrumb has an id, a type, links to other breadcrumbs, and optional claims about the repository's files.
• The one kind of claim is has-line: the file has a line equal to the text, once the spaces and tabs at its start and end are removed. From this release on, its meaning does not change; a new meaning would be a new kind (ADR-0020).

The commands

bcr extract | bcr verify | bcr audit | bcr report > report.md

• bcr extract reads the breadcrumbs and prints them as records.
• bcr verify checks that ids are unique and links point to a breadcrumb.
• bcr audit checks each claim against the files, and gives each claim and each breadcrumb a verdict: Confirmed, Refuted or Undecided. It exits 1 when a claim is Refuted.
• bcr report writes one Markdown page, with a Mermaid diagram for each spec.
• bcr init sets a repository up: a .breadcrumbs with comments only, a section for agents in AGENTS.md, and a GitHub Actions workflow that runs the pipe with this release.

Each command is documented in bcr.1, in each archive below: man ./bcr.1.

Removed

• breadcrumbs/ and its Intakes, Requirements, Technical Decisions and Tasks.
• bcr check, verdict, links, new, spec and audit-report, and the old bcr init.
• The method specification bcr spec printed, and its web site.

ADR-0024 records why.

Install

go install github.com/rodolfo-mendes/breadcrumb-sdd/cmd/bcr@v0.8.0

Or download the archive for your system below, and check it against bcr_0.8.0_checksums.txt.

v0.7.0

Full Changelog: v0.6.0...v0.7.0

v0.6.0

Full Changelog: v0.5.0...v0.6.0

v0.5.0

Full Changelog: v0.4.0...v0.5.0

v0.4.0

bcr now covers everything IN-0005 asked of the toolkit: checking the breadcrumbs, giving their verdicts, following their links, and writing new ones, all under one contract that scripts and agents can chain with pipes.

What's new

• bcr list [ID|PATH|-]... prints each breadcrumb's id, type and title, separated by tabs.
• bcr links [-r] [ID|PATH|-]... prints each link from a breadcrumb to its parent. -r, or --recursive, follows the links up the chain, printing each link once.
• bcr new TYPE TITLE [PARENT|-]... creates a breadcrumb under the next free number of its type (IN, RQ, TD or TK), with its Parent: lines and, for a Technical Decision or a Task, the empty sections to fill in. It prints the new file's path, writes nothing when it cannot write it right, and never replaces a file.
• One way to name breadcrumbs. verdict, list, links and new all take an id, a path, or - to read ids from standard input, so the output of any of them can feed another.

What a Refuted Task breaks, with titles:

bcr verdict | grep -w Refuted | bcr links -r - | cut -f2 | sort -u | bcr list -

A Task for every Requirement still gray:

bcr verdict | grep -w Undecided | grep '^RQ' | bcr new TK "Carry them out" -

Every command is documented in docs/bcr.md, shipped in each archive as the man page bcr.1.

Install

Download the archive for your system below, unpack it, and put bcr (bcr.exe on Windows) on your PATH. bcr.1 is its man page: man ./bcr.1. bcr_0.4.0_checksums.txt holds the SHA-256 of each archive.

System	Archive
Linux, x86-64	bcr_0.4.0_linux_amd64.tar.gz
Linux, ARM64	bcr_0.4.0_linux_arm64.tar.gz
macOS, Intel	bcr_0.4.0_darwin_amd64.tar.gz
macOS, Apple silicon	bcr_0.4.0_darwin_arm64.tar.gz
Windows, x86-64	bcr_0.4.0_windows_amd64.zip
Windows, ARM64	bcr_0.4.0_windows_arm64.zip

The binaries are not signed. On macOS, clear the quarantine flag before the first run: xattr -d com.apple.quarantine bcr.

Or, with Go 1.22 or later:

go install github.com/rodolfo-mendes/breadcrumb-sdd/cmd/bcr@v0.4.0

Full Changelog: v0.3.0...v0.4.0

v0.3.0

bcr gets a documented interface and two new commands, check and verdict, that scripts and agents can chain with pipes.

What's new

• The contract. docs/bcr.md documents every command, flag, output and exit code, and points to the breadcrumb that holds each rule. It ships in every archive as the man page bcr.1.
• POSIX conventions. getopt-style flags (-ab, -o FILE, --output=FILE, --), results on standard output, messages starting with bcr: on standard error.
• Exit codes. 0 when nothing is wrong, 1 when something is wrong in the breadcrumbs, 2 when bcr is used wrongly or cannot run.
• bcr audit-report --html -o FILE writes the report where you choose; -o - writes it to standard output.
• bcr check prints each problem in the breadcrumbs as PATH:LINE: MESSAGE, and warns of files in breadcrumbs/ that are not breadcrumbs.
• bcr verdict [ID|PATH|-]... prints each breadcrumb's id and verdict, separated by a tab, and reads breadcrumbs from standard input with -.

bcr verdict | grep -w Refuted | cut -f1
bcr check 2>/dev/null | cut -d: -f1 | sort | uniq -c

Changes in behavior

• bcr audit-report exits 1 when a breadcrumb is Refuted or has a problem. It still writes the report.
• Running bcr where there is no breadcrumbs/ directory exits 2, not 1.
• A Parent: link to no breadcrumb is a problem.

Install

Download the archive for your system below, unpack it, and put bcr (bcr.exe on Windows) on your PATH. bcr.1 is its man page: man ./bcr.1. bcr_0.3.0_checksums.txt holds the SHA-256 of each archive.

System	Archive
Linux, x86-64	bcr_0.3.0_linux_amd64.tar.gz
Linux, ARM64	bcr_0.3.0_linux_arm64.tar.gz
macOS, Intel	bcr_0.3.0_darwin_amd64.tar.gz
macOS, Apple silicon	bcr_0.3.0_darwin_arm64.tar.gz
Windows, x86-64	bcr_0.3.0_windows_amd64.zip
Windows, ARM64	bcr_0.3.0_windows_arm64.zip

The binaries are not signed. On macOS, clear the quarantine flag before the first run: xattr -d com.apple.quarantine bcr.

Or, with Go 1.22 or later:

go install github.com/rodolfo-mendes/breadcrumb-sdd/cmd/bcr@v0.3.0

Full Changelog: v0.2.0...v0.3.0

v0.2.0

bcr, the Breadcrumb SDD toolkit, written in Go.

What's in it

• bcr audit-report --html audits the breadcrumbs in breadcrumbs/ and writes audit-report.html: a graph of Intakes, Requirements, Technical Decisions and Tasks, each box showing its properties, with an arrow to each of its parents.
• Tasks and contains claims. A Task lists claims such as - `cmd/bcr/main.go` contains `func run(` . bcr checks each against the repository's files.
• Verdicts. A Task is Confirmed when all its claims hold and Refuted when any fails. Verdicts pass up the links, so a broken claim turns the whole chain above it red. Breadcrumbs with nothing below them stay gray (Undecided).
• The model in internal/breadcrumb defines the method; there is no written specification (TD-0007).
• Only the Go standard library (TD-0010).
• A README, a contributor guide, and the MIT License.

This release replaces the v0.1.0 specification and .breadcrumb-kit/, which are no longer in the repository.

Install

Download the archive for your system below, unpack it, and put bcr (bcr.exe on Windows) on your PATH. It is one static binary with nothing else to install. bcr_0.2.0_checksums.txt holds the SHA-256 of each archive.

System	Archive
Linux, x86-64	bcr_0.2.0_linux_amd64.tar.gz
Linux, ARM64	bcr_0.2.0_linux_arm64.tar.gz
macOS, Intel	bcr_0.2.0_darwin_amd64.tar.gz
macOS, Apple silicon	bcr_0.2.0_darwin_arm64.tar.gz
Windows, x86-64	bcr_0.2.0_windows_amd64.zip
Windows, ARM64	bcr_0.2.0_windows_arm64.zip

The binaries are not signed. On macOS, clear the quarantine flag before the first run: xattr -d com.apple.quarantine bcr.

Or, with Go 1.22 or later:

go install github.com/rodolfo-mendes/breadcrumb-sdd/cmd/bcr@v0.2.0

Then, from the root of a repository with a breadcrumbs/ directory:

bcr audit-report --html

Full Changelog: v0.1.0...v0.2.0

v0.1.0

What's Changed

• feat(tools): release the kit as one zip that installs .breadcrumb-kit/ by @rodolfo-mendes in #3

Full Changelog: https://github.com/rodolfo-mendes/breadcrumb-sdd/commits/v0.1.0