Release Notes v0.3.0¶

Released: 2026-11-01

The project is now impact-model, an AI-native format from ProductBuildersHQ. One impact model holds the outcomes and causal links of a program, the assumptions and evidence behind them, the interventions that bring them about, how progress is measured, and who is told which numbers. The theory of change, the logic model, the outcome map, the logframe, and OKRs are projections of that one model, each made for a different reader, and none of them is a part of another.

This is the first release under the new module path and command. It renames names only: the format, the lint checks, the reports, and their output are the same as in v0.2.0. A document written for v0.2.0 needs a new kind and a few renamed fields. See Upgrading.

Highlights¶

One model, many projections. The README and the docs index lead with the impact model as the format, list its projections and the command that draws each, and explain why a logic model is a projection beside the theory of change and not a part of it. A V2MOM projection is planned.
A new module path and command. github.com/ProductBuildersHQ/impact-model, and the impact-model command.
The decision is recorded. ADR 0001 says what changed, what did not, and which other names were considered.

Installation¶

go install github.com/ProductBuildersHQ/impact-model/cmd/[email protected]

Go 1.26.5 or later. The optional programs are the same as in v0.2.0: marp for decks, mmdc and d2 for diagrams, and pandoc for Word and PowerPoint.

Upgrading¶

Every renamed name¶

Was	Is
module `github.com/ProductBuildersHQ/theoryofchange-spec`	`github.com/ProductBuildersHQ/impact-model`
command `theoryofchange`	`impact-model`
packages `pkg/toc`, `pkg/tocio`	`pkg/impact`, `pkg/impactio`
type `toc.Document`, `toc.NewDocument`	`impact.Model`, `impact.NewModel`
`kind: TheoryOfChange`	`kind: ImpactModel`
`kind: TheoryOfChangeStatus`	`kind: ImpactModelStatus`
schemas `theory-of-change`, `theory-of-change-status`	`impact-model`, `impact-model-status`
file name `theory.yaml`	`impact-model.yaml`
fields `tocId`, `childToc`	`modelId`, `childModel`
cross-document reference `toc:<id>#<element>`	`model:<id>#<element>`
lint rule IDs such as `TOC-STR-001`	`IMP-STR-001`
flag `--toc`	`--model`
MCP tools `toc_*`	`impact_*`
agent skills `toc-*`	`impact-*`
documentation site `productbuildershq.com/theoryofchange-spec`	`productbuildershq.com/impact-model`

There are no aliases. The old command, kinds, and field names are not accepted.

Documents¶

A document that still says kind: TheoryOfChange is refused:

error VAL-SCH-003 /kind: invalid document: unknown kind "TheoryOfChange"

To upgrade a document written for v0.2.0:

Change kind: TheoryOfChange to kind: ImpactModel, and kind: TheoryOfChangeStatus to kind: ImpactModelStatus.
Rename the fields tocId to modelId and childToc to childModel.
Change cross-document references from toc: to model:.
If the document was written for v0.1.0, also change level: intermediate to level: medium_term, as described in the v0.2.0 notes.

specVersion stays "0.1", so nothing else in a document changes. Renaming theory.yaml to impact-model.yaml is optional; commands take any file name.

Go code¶

Replace the import paths, then the package and type names:

import (
    "github.com/ProductBuildersHQ/impact-model/pkg/impact"
    "github.com/ProductBuildersHQ/impact-model/pkg/impactio"
)

m := impact.NewModel("my-program", "Too few residents find stable work") // was toc.NewDocument

Scripts, configuration, and agents¶

Call impact-model where scripts called theoryofchange, and pass --model where they passed --toc.
lint --disable names rules as IMP-....
An MCP client configuration starts impact-model mcp, and an agent calls the impact_* tools.
Copy the skills again from skills/: they are now impact-author, impact-audience-story, impact-draft-from-sources, impact-learning-review, and impact-status-refresh.

What did not change¶

The projections keep their method names. report pathway, logic-model, outcome-map, and logframe are still the names of those reports.
Behavior. Validation, the lint rules, measurement, reports, and decks work as in v0.2.0. Only the names in their output change: a report or message says impact model where it said theory or Theory of Change. The workshop deck keeps Theory of Change in its title.
The quality rubric and the specification template in spec/ are still the theory of change checklist and outline.
Earlier releases. v0.1.0 and v0.2.0 stay published under the old module path. GitHub redirects the old repository address.

Compatibility¶

Breaking, for names only. Files still carry specVersion: "0.1", and this version reads any 0.x once the kind and fields are renamed. Exit codes are unchanged. The command still has the same dependencies.

Known Limitations¶

The limitations of v0.2.0 still apply.