@trivoallan/ontrack-product 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,16 @@
1
+ MIT No Attribution
2
+
3
+ Copyright 2026 Tristan Rivoallan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy of this
6
+ software and associated documentation files (the "Software"), to deal in the Software
7
+ without restriction, including without limitation the rights to use, copy, modify,
8
+ merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
9
+ permit persons to whom the Software is furnished to do so.
10
+
11
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
12
+ INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
13
+ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
14
+ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
15
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
16
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,56 @@
1
- # Temporary Holding Version
1
+ # ontrack-product
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Product-management conventions your repositories import as ADRs, with
4
+ [ontrack](https://github.com/trivoallan/ontrack): which toolkit writes
5
+ product artifacts, where they live, what evidence they claim, and when an
6
+ engineering change may build on them. Each convention comes with a check
7
+ that `ontrack check` runs once you accept it.
8
+
9
+ This track needs no other track installed. It proposes the alias `product`.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npm i -D @trivoallan/ontrack
15
+ npm i -D product@npm:@trivoallan/ontrack-product
16
+ npx ontrack plan
17
+ npx ontrack apply
18
+ ```
19
+
20
+ The ADRs land in `docs/adr/product/`, `proposed`, with empty traits. Rule on
21
+ each one in its own file: the file says how.
22
+
23
+ ## The conventions
24
+
25
+ 5 decisions, on these subjects:
26
+
27
+ | ADR | Subject | Recommends |
28
+ | --- | --- | --- |
29
+ | [ADR-0001](adr/ADR-0001-record-product-decisions.md) | how these ADRs are written and ruled on | ships `accepted` |
30
+ | [ADR-0002](adr/ADR-0002-toolkit.md) | the toolkit agents write product artifacts with | `product.toolkit: pm-skills` |
31
+ | [ADR-0003](adr/ADR-0003-location.md) | where product artifacts live | `product.artifacts.root: research/` |
32
+ | [ADR-0004](adr/ADR-0004-evidence.md) | the `evidence:` level every artifact declares | `[hypothesis, observed, validated]`, `observed` required |
33
+ | [ADR-0005](adr/ADR-0005-handoff.md) | when an OpenSpec change may build on a PRD | `product.handoff: openspec` |
34
+
35
+ ## Checks
36
+
37
+ All 5 of them come with a check: a `check:` line in the frontmatter,
38
+ `npx --no-install ontrack-product-check ADR-000n`. Once your repository
39
+ accepts an ADR, `ontrack check` runs that command from your repository's
40
+ root. It runs this package's code there: read it as you would an install
41
+ script. It reads frontmatter keys (`status:`, the traits, `artifact:`,
42
+ `evidence:`) and the `PRD:` and `Probe:` lines of OpenSpec proposals, never
43
+ the prose of an artifact, and it changes no file.
44
+
45
+ ## Develop
46
+
47
+ ```bash
48
+ npm install
49
+ npm test
50
+ ```
51
+
52
+ Changes to this repository are planned with OpenSpec, in `openspec/`.
53
+
54
+ ## License
55
+
56
+ [MIT-0](LICENSE).
@@ -0,0 +1,48 @@
1
+ # yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json
2
+ #
3
+ # Schema for the ontrack-product ADRs once a repository has RULED on them:
4
+ # status decided, date set, no trait key left empty, Nygard sections present,
5
+ # and the how-to-rule block gone. A convention as shipped fails it on purpose
6
+ # (still `proposed`, traits empty); only ADR-0001, shipped `accepted`, passes.
7
+ #
8
+ # `ontrack-product-check ADR-0001` runs it on the ruled copies, and itself
9
+ # refuses an empty `authors:` list, which mdschema cannot express.
10
+ #
11
+ # Trait keys are `optional`: an ABSENT key passes, so a `rejected` ADR with no
12
+ # `traits:` block passes. A key that is PRESENT but empty is refused.
13
+ frontmatter:
14
+ fields:
15
+ - { name: "adr", type: string }
16
+ - { name: "slug", type: string }
17
+ - { name: "title", type: string }
18
+ - { name: "status", enum: [accepted, rejected] }
19
+ - { name: "revision", type: number }
20
+ - { name: "date", format: date }
21
+ - { name: "authors", type: array }
22
+ - { name: "supersedes", type: array }
23
+ - { name: "traits", type: object, optional: true }
24
+ # ADR-0002
25
+ - { name: "traits.product.toolkit", enum: [pm-skills, nanopm, none], optional: true }
26
+ # ADR-0003
27
+ - { name: "traits.product.artifacts.root", type: string, optional: true }
28
+ # ADR-0004
29
+ - { name: "traits.product.evidence.levels", type: array, optional: true }
30
+ - { name: "traits.product.evidence.required", type: string, optional: true }
31
+ # ADR-0005
32
+ - { name: "traits.product.handoff", enum: [openspec, none], optional: true }
33
+ structure:
34
+ - heading:
35
+ pattern: "^# .+"
36
+ children:
37
+ - heading: "## Status"
38
+ - heading: "## Context"
39
+ - heading: "## Decision"
40
+ forbidden_text: ["Everything below disappears when you rule"]
41
+ - heading: "## Consequences"
42
+ children:
43
+ - heading: "### Positive"
44
+ - heading: "### Negative"
45
+ - heading: "### Neutral"
46
+ - heading: "## Alternatives Considered"
47
+ allow_additional: true
48
+ - heading: "## References"
@@ -0,0 +1,174 @@
1
+ ---
2
+ adr: ADR-0001
3
+ slug: record-product-decisions
4
+ title: Record product decisions
5
+ status: accepted
6
+ revision: 1
7
+ date: 2026-11-21
8
+ authors: [Tristan Rivoallan]
9
+ supersedes: []
10
+ check: npx --no-install ontrack-product-check ADR-0001
11
+ ---
12
+
13
+ # Record product decisions
14
+
15
+ ## Status
16
+
17
+ Accepted
18
+
19
+ > **This ADR is not a convention to rule on.** The other ontrack-product ADRs
20
+ > arrive with `status: proposed` and wait for your repository to rule on
21
+ > them. This one arrives `accepted`, because it describes the mechanics you
22
+ > will use to rule on the others. You can supersede it like any other ADR,
23
+ > with a new ADR that lists it in `supersedes:`. Until then, it is what says
24
+ > how these ADRs are written and ruled on here.
25
+
26
+ ## Context
27
+
28
+ Product work done with coding agents leaves files behind: PRDs, problem
29
+ statements, hypotheses, interview syntheses. Where they go, how sure they
30
+ are, and whether engineering may build on them is decided in a conversation,
31
+ then decided again in the next one. An agent that finds no written rule
32
+ treats each choice as an accident.
33
+
34
+ These choices are rarely specific to one repository. ontrack-product ships
35
+ each of them as a **convention**: an ADR with the values it recommends and
36
+ why, which your repository imports through
37
+ [ontrack](https://github.com/trivoallan/ontrack) and rules on. This track
38
+ needs no other track installed: everything it relies on is written here.
39
+
40
+ What remains to decide is how these ADRs are written, shipped and ruled on.
41
+
42
+ ## Decision
43
+
44
+ We will keep ontrack-product ADRs as follows.
45
+
46
+ **1. The format is Nygard's.** Every ADR has, in this order: `## Status`,
47
+ `## Context`, `## Decision`, `## Consequences` (with `### Positive`,
48
+ `### Negative` and `### Neutral`), `## Alternatives Considered` and
49
+ `## References`. Everything is in English.
50
+
51
+ **2. Files are named `ADR-NNNN-slug.md`** and numbered without gaps. ontrack
52
+ imports them into `docs/adr/product/`, or into the directory named after the
53
+ alias you installed the track under. Your repository's own decisions live in
54
+ `docs/adr/local/`, with their own numbering.
55
+
56
+ **3. The frontmatter is the machine source.**
57
+
58
+ ```yaml
59
+ adr: ADR-0003 # must match the file name
60
+ slug: location # must match the file name
61
+ title: Location
62
+ status: accepted # proposed as shipped; accepted or rejected once ruled
63
+ revision: 1 # written by ontrack-product: it dates the convention, not the file
64
+ date: 2026-11-21 # the day you ruled
65
+ authors: [Your Name] # the people who decided, no email addresses
66
+ supersedes: [] # the ADRs this one replaces
67
+ check: npx --no-install ontrack-product-check ADR-0003 # see rule 8
68
+ traits: {...} # the machine-readable part of the ruling
69
+ ```
70
+
71
+ An ADR is superseded when another one lists it in `supersedes:`. The reverse
72
+ edge is not written: it would be a second place to keep in step.
73
+
74
+ **4. The body freezes once ruled; the status does not.** Once your
75
+ repository rules an ADR `accepted` or `rejected`, its text does not change,
76
+ and reopening the decision takes a new ADR. Only its `status` and its
77
+ `check:` line are still written. A superseded ADR stays in the directory: it
78
+ is a log of decisions, not a list of what is in force.
79
+
80
+ This freeze is about your ruling. The ADRs this package ships change only
81
+ through `revision` (rule 6).
82
+
83
+ **5. A convention arrives `proposed`, and the ruling is yours.** Every key
84
+ under `traits:` is empty. The Decision section states what ontrack-product
85
+ recommends and why, then a how-to-rule block, opened by a marker sentence,
86
+ that lists the steps to rule. Staying `proposed` is a state, not an
87
+ oversight: an agent reads a `proposed` convention as undecided.
88
+
89
+ A **trait** is a key this package ships and whose value is yours. The prose
90
+ explains and justifies; the trait is read without interpretation. All of
91
+ this track's traits sit under `product.`.
92
+
93
+ `accepted` means the values under `traits:` are in force. `rejected` is a
94
+ full ruling too: the convention does not apply here. Remove the whole
95
+ `traits:` block and say what stands in for the decision, so an agent knows
96
+ what to go by.
97
+
98
+ **6. `revision` dates the convention.** ontrack-product raises it by one
99
+ when, and only when, the convention changes: a trait added, removed or
100
+ renamed, an allowed value changed, or the recommended value changed. A
101
+ wording or link fix leaves it alone, and so does a change to a `check:` line
102
+ or to the script it runs. `ontrack plan` then reports an ADR as `revised`
103
+ only when there is something to rule on again. Each ADR above revision 1
104
+ ends with a **Revisions** list that says what changed and what to rule on
105
+ again.
106
+
107
+ **7. A half-ruled ADR fails.** This ADR's `check:` line runs
108
+ `ontrack-product-check ADR-0001`. It checks every copy of these ADRs that is
109
+ no longer `proposed` against the `.mdschema.yml` shipped next to them: status
110
+ decided, date set, authors named, no trait key left empty, the sections above
111
+ present, and the how-to-rule block gone. It names the file and the key.
112
+
113
+ **8. A `check:` line says when your work departs from a decision.** Every
114
+ ontrack-product ADR carries, in its frontmatter, a `check:` key holding
115
+ `npx --no-install ontrack-product-check <ADR number>`. Once your repository
116
+ rules the ADR `accepted`, `ontrack check` runs it from your repository's root
117
+ and reports `pass` or `fail`. The script reads the traits you ruled, so the
118
+ same line holds whatever you decide. It reads frontmatter and a few declared
119
+ lines, never the prose of your product artifacts, and it changes no file.
120
+ `--no-install` keeps `npx` from fetching anything. Read an imported `check:`
121
+ line as you would an npm install script: it runs this package's code in your
122
+ repository.
123
+
124
+ **9. If ontrack-product proposes the wrong convention,** rule it `rejected`
125
+ or write your own decision in `docs/adr/local/`, cite the ontrack-product ADR
126
+ you depart from, and say how.
127
+
128
+ ## Consequences
129
+
130
+ ### Positive
131
+
132
+ - Where product artifacts live, what they claim and when engineering builds
133
+ on them is written in the repository, for people and agents alike.
134
+ - A repository starts from a reasoned recommendation, and rules on it in one
135
+ commit.
136
+ - A ruled convention is checked by `ontrack check`, so a departure fails
137
+ before review instead of in it.
138
+
139
+ ### Negative
140
+
141
+ - If nothing runs `ontrack check`, in a pull request or elsewhere, nothing
142
+ looks at the rulings.
143
+ - A convention as shipped fails the schema on purpose, so ontrack-product's
144
+ own conventions are checked by review only.
145
+
146
+ ### Neutral
147
+
148
+ - The mechanics match those of other ontrack tracks, so a repository that
149
+ installs several reads one set of rules, but this track does not require
150
+ any of them.
151
+
152
+ ## Alternatives Considered
153
+
154
+ ### Rely on another track's mechanics
155
+
156
+ ontrack-engineering ships the same rules in its own ADR-0001. Pointing to it
157
+ would make this track depend on another being installed, and a product team
158
+ may not want engineering's conventions.
159
+
160
+ ### Ship rulings instead of conventions
161
+
162
+ Simpler to write, but the repository would have nothing to decide, and the
163
+ reasons would describe ontrack-product's context instead of its own.
164
+
165
+ ### Hand-written decisions with no tooling
166
+
167
+ Nothing to install, and nothing machine-readable: finding the open
168
+ conventions means reading prose, and a half-filled ADR goes unnoticed.
169
+
170
+ ## References
171
+
172
+ - Michael Nygard, [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) (2011).
173
+ - [ontrack](https://github.com/trivoallan/ontrack): imports these ADRs and reports `new`, `revised` and `removed` ones.
174
+ - [mdschema](https://github.com/jackchuka/mdschema): the checker behind `.mdschema.yml`.
@@ -0,0 +1,149 @@
1
+ ---
2
+ adr: ADR-0002
3
+ slug: toolkit
4
+ title: Product toolkit
5
+ status: proposed
6
+ revision: 1
7
+ date:
8
+ authors: []
9
+ supersedes: []
10
+ check: npx --no-install ontrack-product-check ADR-0002
11
+ traits:
12
+ product:
13
+ toolkit:
14
+ ---
15
+
16
+ # Product toolkit
17
+
18
+ ## Status
19
+
20
+ Proposed
21
+
22
+ > **What is this file?** A convention ontrack-product proposes to your
23
+ > repository, with the values it recommends. While it says
24
+ > `status: proposed`, you may edit it freely. `revision:` dates the
25
+ > convention, not the file: you do not fill it. `rejected` is a full ruling:
26
+ > when the convention does not apply here, rule `rejected`, remove the whole
27
+ > `traits:` block, and say what stands in for it.
28
+ > [ADR-0001](ADR-0001-record-product-decisions.md) explains the mechanics.
29
+
30
+ ## Context
31
+
32
+ Coding agents write product artifacts when asked: a PRD, a problem
33
+ statement, a hypothesis, a launch checklist. Without a shared toolkit, each
34
+ session improvises the structure, and two PRDs in the same repository share
35
+ nothing a person or a script can rely on.
36
+
37
+ A product toolkit is a set of skills an agent runs to produce those
38
+ artifacts from templates. What matters to this track is not the prose the
39
+ templates suggest but what they write in a form a tool can read: the rest
40
+ of ontrack-product's conventions (ADR-0003 to ADR-0005) check frontmatter,
41
+ never prose.
42
+
43
+ ## Decision
44
+
45
+ **What ontrack-product recommends, and why.**
46
+
47
+ | Key | Recommended value | Reason |
48
+ | --- | --- | --- |
49
+ | `product.toolkit` | `pm-skills` | the [pm-skills](https://github.com/product-on-purpose/pm-skills) Claude Code plugin, by product-on-purpose. Its templates open every artifact with YAML frontmatter (`artifact:`, `version:`, `created:`, `status:`), so the kind of an artifact is a key, not a guess from its title. It covers discovery to delivery (problem statements, hypotheses, PRDs, experiment designs) and leaves the output path to you, which ADR-0003 fixes |
50
+
51
+ With `pm-skills`, every product artifact carries a non-empty `artifact:`
52
+ key in its frontmatter. An artifact written by hand follows the same rule:
53
+ it says what kind of artifact it is.
54
+
55
+ Everything below disappears when you rule, from this sentence up to the
56
+ Consequences heading, which stays.
57
+
58
+ **How to rule: five steps, all in this file.** Read all of them before
59
+ doing any, because the last one deletes the other four, and do them in one
60
+ commit.
61
+
62
+ 1. **Write the value of `product.toolkit`** under `traits:` in the
63
+ frontmatter, or, if you rule `rejected`, **remove the whole `traits:`
64
+ block**.
65
+ 2. **Change `status:`** from `proposed` to `accepted` or `rejected`.
66
+ 3. **Fill `date:` and `authors:`**: `date:` as `YYYY-MM-DD`, the day you
67
+ rule; `authors:`, the names of the people who decided, without email
68
+ addresses.
69
+ 4. **Rewrite the Positive, Negative and Neutral lists under Consequences**
70
+ for your ruling.
71
+ 5. **Last, delete this block**, from its first sentence up to the
72
+ Consequences heading, which stays. In its place, write the reason for
73
+ your decision wherever you depart from the recommendation, or one line
74
+ that says you adopt it.
75
+
76
+ Once filled, the frontmatter reads:
77
+
78
+ ```yaml
79
+ status: accepted
80
+ date: 2026-11-21
81
+ authors: [Your Name]
82
+ check: npx --no-install ontrack-product-check ADR-0002
83
+ traits:
84
+ product:
85
+ toolkit: pm-skills
86
+ ```
87
+
88
+ **The `check:` line stays.** Once this ADR is `accepted`, it reads
89
+ `product.toolkit` and, from ADR-0003, `product.artifacts.root`. With
90
+ `pm-skills`, it fails on every product artifact (a Markdown file tracked by
91
+ git under the root) whose frontmatter has no non-empty `artifact:` key. It
92
+ reads that key and nothing else. With `nanopm` or `none`, it has nothing to
93
+ check, and passes.
94
+
95
+ The Alternatives Considered below were weighed without knowing your
96
+ context. Weighing them against yours is still to do.
97
+
98
+ ## Consequences
99
+
100
+ ### Positive
101
+
102
+ - Product artifacts share a structure, and their kind is a key a tool reads.
103
+ - The other conventions of this track have something to check.
104
+
105
+ ### Negative
106
+
107
+ - The repository depends on a third-party plugin and its template choices.
108
+ If pm-skills changes its frontmatter, the check fails until it is updated.
109
+ - People who write artifacts by hand must add the frontmatter themselves.
110
+
111
+ ### Neutral
112
+
113
+ - The toolkit is chosen per repository; the agent that runs it is not
114
+ decided here.
115
+
116
+ ## Alternatives Considered
117
+
118
+ ### `pm-skills`
119
+
120
+ Recommended, as above.
121
+
122
+ ### `nanopm`
123
+
124
+ A PM pipeline for coding agents (feedback, personas, objectives, strategy,
125
+ roadmap, PRD) that keeps its output in a wiki under `.nanopm/wiki/`, each
126
+ step reading the previous one. Strong at chaining a planning cycle; its
127
+ pages are not typed by an `artifact:` key, so the check has nothing to read
128
+ and passes. Choose it when the planning cycle matters more than checked
129
+ artifacts; ADR-0003 then names `.nanopm/wiki/` or another root.
130
+
131
+ ### `none`
132
+
133
+ No toolkit: artifacts are written by hand or by an agent without
134
+ templates. The check passes. Say why the repository can do without.
135
+
136
+ ## References
137
+
138
+ - [pm-skills](https://github.com/product-on-purpose/pm-skills): the recommended toolkit.
139
+ - [nanopm](https://github.com/nmrtn/nanopm): the alternative.
140
+ - [ADR-0003](ADR-0003-location.md): where the artifacts live, which this check reads.
141
+
142
+ **The keys.**
143
+
144
+ | Key | What it holds | Allowed values |
145
+ | --- | --- | --- |
146
+ | `product.toolkit` | the toolkit agents use to write product artifacts here | `pm-skills`, `nanopm`, `none` |
147
+
148
+ **The key is required**: an empty key is not a value. The check needs
149
+ ADR-0003 accepted when the value is `pm-skills`.
@@ -0,0 +1,152 @@
1
+ ---
2
+ adr: ADR-0003
3
+ slug: location
4
+ title: Location
5
+ status: proposed
6
+ revision: 1
7
+ date:
8
+ authors: []
9
+ supersedes: []
10
+ check: npx --no-install ontrack-product-check ADR-0003
11
+ traits:
12
+ product:
13
+ artifacts:
14
+ root:
15
+ ---
16
+
17
+ # Location
18
+
19
+ ## Status
20
+
21
+ Proposed
22
+
23
+ > **What is this file?** A convention ontrack-product proposes to your
24
+ > repository, with the values it recommends. While it says
25
+ > `status: proposed`, you may edit it freely. `revision:` dates the
26
+ > convention, not the file: you do not fill it. `rejected` is a full ruling:
27
+ > when the convention does not apply here, rule `rejected`, remove the whole
28
+ > `traits:` block, and say what stands in for it.
29
+ > [ADR-0001](ADR-0001-record-product-decisions.md) explains the mechanics.
30
+
31
+ ## Context
32
+
33
+ An agent asked for a PRD writes it where the conversation suggests: the
34
+ repository root, `docs/`, a feature folder, a scratch directory. Six months
35
+ later nobody can say which PRDs exist, and a tool that should check them
36
+ has nowhere to look.
37
+
38
+ pm-skills, the toolkit [ADR-0002](ADR-0002-toolkit.md) recommends, fixes no
39
+ output path: it writes where it is told. Something has to tell it.
40
+
41
+ ## Decision
42
+
43
+ **What ontrack-product recommends, and why.**
44
+
45
+ | Key | Recommended value | Reason |
46
+ | --- | --- | --- |
47
+ | `product.artifacts.root` | `research/` | one directory, at the top of the repository, named for what it holds before anything is built. It sits apart from `docs/`, which describes what exists, and from `openspec/`, which plans what will be built. Any depth below it is yours: `research/search/prd.md` is as valid as `research/prd-search.md` |
48
+
49
+ **Every product artifact lives under the root.** A product artifact is a
50
+ Markdown file tracked by git that says, in an `artifact:` frontmatter key,
51
+ what kind of product artifact it is. Anything under the root counts as a
52
+ product artifact for the checks of ADR-0002 and ADR-0004; anything with an
53
+ `artifact:` key outside it is in the wrong place.
54
+
55
+ The value is a directory relative to the repository root. It may not be
56
+ absolute, nor leave the repository.
57
+
58
+ Everything below disappears when you rule, from this sentence up to the
59
+ Consequences heading, which stays.
60
+
61
+ **How to rule: five steps, all in this file.** Read all of them before
62
+ doing any, because the last one deletes the other four, and do them in one
63
+ commit.
64
+
65
+ 1. **Write the value of `product.artifacts.root`** under `traits:` in the
66
+ frontmatter, or, if you rule `rejected`, **remove the whole `traits:`
67
+ block**.
68
+ 2. **Change `status:`** from `proposed` to `accepted` or `rejected`.
69
+ 3. **Fill `date:` and `authors:`**: `date:` as `YYYY-MM-DD`, the day you
70
+ rule; `authors:`, the names of the people who decided, without email
71
+ addresses.
72
+ 4. **Rewrite the Positive, Negative and Neutral lists under Consequences**
73
+ for your ruling.
74
+ 5. **Last, delete this block**, from its first sentence up to the
75
+ Consequences heading, which stays. In its place, write the reason for
76
+ your decision wherever you depart from the recommendation, or one line
77
+ that says you adopt it.
78
+
79
+ Once filled, the frontmatter reads:
80
+
81
+ ```yaml
82
+ status: accepted
83
+ date: 2026-11-21
84
+ authors: [Your Name]
85
+ check: npx --no-install ontrack-product-check ADR-0003
86
+ traits:
87
+ product:
88
+ artifacts:
89
+ root: research/
90
+ ```
91
+
92
+ **The `check:` line stays.** Once this ADR is `accepted`, it fails when the
93
+ root is absolute or leaves the repository, when it is not a directory of the
94
+ repository, or when a Markdown file tracked by git outside the root has a
95
+ non-empty `artifact:` frontmatter key. It reads that key and nothing else.
96
+
97
+ ## Consequences
98
+
99
+ ### Positive
100
+
101
+ - Every product artifact is found in one place, by people, agents and
102
+ checks.
103
+ - An artifact written in the wrong place fails before review.
104
+
105
+ ### Negative
106
+
107
+ - An artifact that belongs next to the code it describes has to live
108
+ elsewhere, and be linked.
109
+ - The directory must exist before the check passes, even before the first
110
+ artifact: keep a `.gitkeep` in it.
111
+
112
+ ### Neutral
113
+
114
+ - The name is a convention, not a meaning: `product/` or `discovery/`
115
+ work as well.
116
+
117
+ ## Alternatives Considered
118
+
119
+ ### `research/`
120
+
121
+ Recommended, as above.
122
+
123
+ ### `docs/product/`
124
+
125
+ Keeps every document under `docs/`. It mixes what is described with what
126
+ is still a claim, and a documentation site built from `docs/` publishes
127
+ hypotheses next to reference pages.
128
+
129
+ ### `.nanopm/wiki/`
130
+
131
+ The directory nanopm writes to, when [ADR-0002](ADR-0002-toolkit.md) rules
132
+ `nanopm`. Hidden, and owned by the tool rather than the team.
133
+
134
+ ### No fixed place
135
+
136
+ Each artifact goes where it is needed. Nothing can find them all, and the
137
+ evidence convention of ADR-0004 has nothing to check.
138
+
139
+ ## References
140
+
141
+ - [ADR-0002](ADR-0002-toolkit.md): the toolkit that writes the artifacts.
142
+ - [ADR-0004](ADR-0004-evidence.md): what every artifact under the root
143
+ declares.
144
+
145
+ **The keys.**
146
+
147
+ | Key | What it holds | Allowed values |
148
+ | --- | --- | --- |
149
+ | `product.artifacts.root` | the directory every product artifact lives under | a directory relative to the repository root |
150
+
151
+ **The key is required**: an empty key is not a value. ADR-0002, ADR-0004 and
152
+ ADR-0005 read it from this file, and fail until this ADR is accepted.
@@ -0,0 +1,177 @@
1
+ ---
2
+ adr: ADR-0004
3
+ slug: evidence
4
+ title: Evidence
5
+ status: proposed
6
+ revision: 1
7
+ date:
8
+ authors: []
9
+ supersedes: []
10
+ check: npx --no-install ontrack-product-check ADR-0004
11
+ traits:
12
+ product:
13
+ evidence:
14
+ levels:
15
+ required:
16
+ ---
17
+
18
+ # Evidence
19
+
20
+ ## Status
21
+
22
+ Proposed
23
+
24
+ > **What is this file?** A convention ontrack-product proposes to your
25
+ > repository, with the values it recommends. While it says
26
+ > `status: proposed`, you may edit it freely. `revision:` dates the
27
+ > convention, not the file: you do not fill it. `rejected` is a full ruling:
28
+ > when the convention does not apply here, rule `rejected`, remove the whole
29
+ > `traits:` block, and say what stands in for it.
30
+ > [ADR-0001](ADR-0001-record-product-decisions.md) explains the mechanics.
31
+
32
+ ## Context
33
+
34
+ A PRD written by an agent reads the same whether it rests on twenty user
35
+ interviews or on one sentence typed in a chat. Its structure is complete,
36
+ its tone is confident, and nothing in it says how much of it is known. The
37
+ next agent, asked to build it, takes it at its word.
38
+
39
+ pm-skills' templates record the kind of an artifact, its version, its
40
+ creation date and its draft status. None of them records how well the
41
+ artifact is supported.
42
+
43
+ ## Decision
44
+
45
+ **ontrack-product adds one frontmatter field, `evidence:`, to every product
46
+ artifact** under the root [ADR-0003](ADR-0003-location.md) fixes. pm-skills
47
+ does not write it: add it when the artifact is created, next to `artifact:`.
48
+
49
+ ```yaml
50
+ ---
51
+ artifact: prd
52
+ version: "1.0"
53
+ created: 2026-11-21
54
+ status: draft
55
+ evidence: hypothesis
56
+ ---
57
+ ```
58
+
59
+ **What ontrack-product recommends, and why.**
60
+
61
+ | Key | Recommended value | Reason |
62
+ | --- | --- | --- |
63
+ | `product.evidence.levels` | `[hypothesis, observed, validated]` | three levels, weakest first, each one a different kind of claim. Fewer cannot tell a guess from a seen behaviour; more invites arguing about the level instead of looking at users |
64
+ | `product.evidence.required` | `observed` | the level an artifact must reach before engineering builds on it ([ADR-0005](ADR-0005-handoff.md)). A hypothesis is welcome as a starting point, not as a specification |
65
+
66
+ The recommended levels mean:
67
+
68
+ - **`hypothesis`**: what the artifact states is believed, not yet seen.
69
+ - **`observed`**: what it states has been seen in real use, interviews or
70
+ data, at least once.
71
+ - **`validated`**: what it states has been tested on purpose, and the test
72
+ came out as the artifact says.
73
+
74
+ The levels are ordered: each one ranks above those before it in the list.
75
+ `product.evidence.required` must be one of them.
76
+
77
+ **How a level is raised is not decided in this revision.** What proves an
78
+ artifact `observed` or `validated`, and how that proof is written next to
79
+ the level, is left to a later revision of this convention. Until then, the
80
+ level is declared by whoever writes the artifact, and review judges it.
81
+
82
+ Everything below disappears when you rule, from this sentence up to the
83
+ Consequences heading, which stays.
84
+
85
+ **How to rule: five steps, all in this file.** Read all of them before
86
+ doing any, because the last one deletes the other four, and do them in one
87
+ commit.
88
+
89
+ 1. **Write the value of each key** under `traits:` in the frontmatter, or,
90
+ if you rule `rejected`, **remove the whole `traits:` block**.
91
+ 2. **Change `status:`** from `proposed` to `accepted` or `rejected`.
92
+ 3. **Fill `date:` and `authors:`**: `date:` as `YYYY-MM-DD`, the day you
93
+ rule; `authors:`, the names of the people who decided, without email
94
+ addresses.
95
+ 4. **Rewrite the Positive, Negative and Neutral lists under Consequences**
96
+ for your ruling.
97
+ 5. **Last, delete this block**, from its first sentence up to the
98
+ Consequences heading, which stays. In its place, write the reason for
99
+ your decision wherever you depart from the recommendation, or one line
100
+ that says you adopt it.
101
+
102
+ Once filled, the frontmatter reads:
103
+
104
+ ```yaml
105
+ status: accepted
106
+ date: 2026-11-21
107
+ authors: [Your Name]
108
+ check: npx --no-install ontrack-product-check ADR-0004
109
+ traits:
110
+ product:
111
+ evidence:
112
+ levels: [hypothesis, observed, validated]
113
+ required: observed
114
+ ```
115
+
116
+ **The `check:` line stays.** Once this ADR is `accepted`, it reads these
117
+ keys and, from ADR-0003, `product.artifacts.root`. It fails when the levels
118
+ are empty or repeat a value, when the required level is not one of them,
119
+ and on every product artifact whose frontmatter has no `evidence:` key or a
120
+ value outside the levels. It reads the `evidence:` key and nothing else: it
121
+ does not judge whether a level is deserved. An artifact at `hypothesis`
122
+ passes: the gate is on changes, in ADR-0005.
123
+
124
+ ## Consequences
125
+
126
+ ### Positive
127
+
128
+ - How sure an artifact is reads in one key, before its prose.
129
+ - A hypothesis can be written down and shared without being mistaken for a
130
+ specification.
131
+
132
+ ### Negative
133
+
134
+ - The level is self-declared: an artifact can claim `observed` with
135
+ nothing behind it, until a later revision says what proves it.
136
+ - Every artifact needs one more key, which pm-skills does not write.
137
+
138
+ ### Neutral
139
+
140
+ - The level describes the artifact as a whole, not each of its claims.
141
+
142
+ ## Alternatives Considered
143
+
144
+ ### Three levels, `observed` required
145
+
146
+ Recommended, as above.
147
+
148
+ ### Two levels, `hypothesis` and `validated`
149
+
150
+ Simpler, but it forces a choice between a guess and a tested result, and
151
+ most product knowledge sits between them.
152
+
153
+ ### Proof required with the level
154
+
155
+ Each level would come with the source that supports it, and the check would
156
+ require one. Deferred: what counts as proof differs between teams, and
157
+ deciding it now would freeze a guess.
158
+
159
+ ### No evidence field
160
+
161
+ Artifacts stay as pm-skills writes them. Nothing tells a supported PRD from
162
+ an unsupported one, and ADR-0005 has nothing to gate on.
163
+
164
+ ## References
165
+
166
+ - [ADR-0003](ADR-0003-location.md): which files are product artifacts.
167
+ - [ADR-0005](ADR-0005-handoff.md): where the required level is enforced.
168
+
169
+ **The keys.**
170
+
171
+ | Key | What it holds | Allowed values |
172
+ | --- | --- | --- |
173
+ | `product.evidence.levels` | the evidence levels, weakest first | a list of distinct names, at least one |
174
+ | `product.evidence.required` | the level an artifact must reach before a change builds on it | one of `product.evidence.levels` |
175
+
176
+ **Both keys are required**: an empty key is not a value. The check needs
177
+ ADR-0003 accepted.
@@ -0,0 +1,174 @@
1
+ ---
2
+ adr: ADR-0005
3
+ slug: handoff
4
+ title: Handoff
5
+ status: proposed
6
+ revision: 1
7
+ date:
8
+ authors: []
9
+ supersedes: []
10
+ check: npx --no-install ontrack-product-check ADR-0005
11
+ traits:
12
+ product:
13
+ handoff:
14
+ ---
15
+
16
+ # Handoff
17
+
18
+ ## Status
19
+
20
+ Proposed
21
+
22
+ > **What is this file?** A convention ontrack-product proposes to your
23
+ > repository, with the values it recommends. While it says
24
+ > `status: proposed`, you may edit it freely. `revision:` dates the
25
+ > convention, not the file: you do not fill it. `rejected` is a full ruling:
26
+ > when the convention does not apply here, rule `rejected`, remove the whole
27
+ > `traits:` block, and say what stands in for it.
28
+ > [ADR-0001](ADR-0001-record-product-decisions.md) explains the mechanics.
29
+
30
+ ## Context
31
+
32
+ The moment a PRD turns into engineering work is the moment its claims stop
33
+ being cheap. Before it, a wrong hypothesis costs a paragraph; after it, it
34
+ costs a feature. [ADR-0004](ADR-0004-evidence.md) says how well each
35
+ artifact is supported. Nothing yet says what happens when engineering
36
+ starts on one that is not supported enough.
37
+
38
+ Blocking the PRD itself would be wrong: a hypothesis has to be written down
39
+ to be tested. What should be stopped is building on it as if it were known.
40
+ Sometimes building is the test, and then the change should say so.
41
+
42
+ ## Decision
43
+
44
+ **What ontrack-product recommends, and why.**
45
+
46
+ | Key | Recommended value | Reason |
47
+ | --- | --- | --- |
48
+ | `product.handoff` | `openspec` | engineering work is planned as [OpenSpec](https://github.com/Fission-AI/OpenSpec) changes, written in the repository before the code, so the handoff from product to engineering is a file a check can read: the change's `proposal.md` |
49
+
50
+ **With `openspec`, this convention assumes engineering work is planned as
51
+ OpenSpec changes under `openspec/changes/`.** A change that builds on a
52
+ product artifact says so in its `proposal.md`, on a line of its own:
53
+
54
+ ```markdown
55
+ PRD: research/prd-search.md
56
+ ```
57
+
58
+ **The gate blocks the change, not the PRD.** A PRD below the level
59
+ `product.evidence.required` names may exist, be shared and be worked on. A
60
+ change whose proposal cites it with a `PRD:` line is refused, unless the
61
+ proposal also carries a `Probe:` line that names the hypothesis the change
62
+ tests and what will be observed:
63
+
64
+ ```markdown
65
+ PRD: research/prd-search.md
66
+ Probe: users who search twice abandon less; read in the funnel for two weeks after release.
67
+ ```
68
+
69
+ A probe is a change built to learn, not to deliver: it is how a hypothesis
70
+ becomes `observed`. **The check only sees that the `Probe:` line is there;
71
+ review judges whether the probe is real**: that the hypothesis is the PRD's,
72
+ and that what will be observed could prove it wrong.
73
+
74
+ A proposal with no `PRD:` line passes: it claims no product basis, and
75
+ review sees that.
76
+
77
+ Everything below disappears when you rule, from this sentence up to the
78
+ Consequences heading, which stays.
79
+
80
+ **How to rule: five steps, all in this file.** Read all of them before
81
+ doing any, because the last one deletes the other four, and do them in one
82
+ commit.
83
+
84
+ 1. **Write the value of `product.handoff`** under `traits:` in the
85
+ frontmatter, or, if you rule `rejected`, **remove the whole `traits:`
86
+ block**.
87
+ 2. **Change `status:`** from `proposed` to `accepted` or `rejected`.
88
+ 3. **Fill `date:` and `authors:`**: `date:` as `YYYY-MM-DD`, the day you
89
+ rule; `authors:`, the names of the people who decided, without email
90
+ addresses.
91
+ 4. **Rewrite the Positive, Negative and Neutral lists under Consequences**
92
+ for your ruling.
93
+ 5. **Last, delete this block**, from its first sentence up to the
94
+ Consequences heading, which stays. In its place, write the reason for
95
+ your decision wherever you depart from the recommendation, or one line
96
+ that says you adopt it.
97
+
98
+ Once filled, the frontmatter reads:
99
+
100
+ ```yaml
101
+ status: accepted
102
+ date: 2026-11-21
103
+ authors: [Your Name]
104
+ check: npx --no-install ontrack-product-check ADR-0005
105
+ traits:
106
+ product:
107
+ handoff: openspec
108
+ ```
109
+
110
+ **The `check:` line stays.** Once this ADR is `accepted`, with `openspec`,
111
+ it reads the `proposal.md` of every directory under `openspec/changes/`,
112
+ `archive/` excluded. What it reads is: the proposal's `PRD:` and `Probe:`
113
+ lines, the cited file's `evidence:` key, and, from ADR-0003 and ADR-0004,
114
+ the root and the levels. Nothing else. It fails when a cited path is not a
115
+ product artifact under the root, or when the cited artifact ranks below the
116
+ required level and the proposal has no `Probe:` line with text after it.
117
+ With `none`, it has nothing to check, and passes. It needs ADR-0003 and
118
+ ADR-0004 accepted.
119
+
120
+ ## Consequences
121
+
122
+ ### Positive
123
+
124
+ - Engineering does not start on a guess without saying it is a guess.
125
+ - A hypothesis can still be built, as a probe, with what it will teach
126
+ written next to it.
127
+
128
+ ### Negative
129
+
130
+ - A `Probe:` line is easy to write. The check cannot tell a real probe from
131
+ a line added to get past it; only review can.
132
+ - Only changes that declare their PRD are gated. A change that leaves the
133
+ `PRD:` line out passes.
134
+
135
+ ### Neutral
136
+
137
+ - Archived changes are not read: they record what was decided at the time.
138
+
139
+ ## Alternatives Considered
140
+
141
+ ### `openspec`, gate on the change
142
+
143
+ Recommended, as above.
144
+
145
+ ### Gate on the PRD
146
+
147
+ Refuse any PRD below the required level. It would keep hypotheses out of the
148
+ repository, which is where they should be written and tested.
149
+
150
+ ### Read the links in the proposal
151
+
152
+ Find PRDs from any link in the proposal's prose instead of a declared line.
153
+ It would make the check read prose, and a passing mention would count as a
154
+ basis.
155
+
156
+ ### `none`
157
+
158
+ Engineering work is not planned as files the check can read, or the gate is
159
+ not wanted. Say how the repository keeps unsupported PRDs from being built
160
+ as if they were known.
161
+
162
+ ## References
163
+
164
+ - [OpenSpec](https://github.com/Fission-AI/OpenSpec): the change framework this convention assumes.
165
+ - [ADR-0003](ADR-0003-location.md): where cited artifacts must live.
166
+ - [ADR-0004](ADR-0004-evidence.md): the levels and the required one.
167
+
168
+ **The keys.**
169
+
170
+ | Key | What it holds | Allowed values |
171
+ | --- | --- | --- |
172
+ | `product.handoff` | how engineering work that builds on product artifacts is declared | `openspec`, `none` |
173
+
174
+ **The key is required**: an empty key is not a value.
@@ -0,0 +1,269 @@
1
+ #!/usr/bin/env node
2
+ // ontrack-product-check <ADR number>
3
+ // Runs the check this package ships for one ADR, from the consuming repository's
4
+ // root, as called by that ADR's `check:` line through `ontrack check`. Reads
5
+ // frontmatter and declared lines only; writes nothing.
6
+ import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
7
+ import { join, dirname, basename, relative, isAbsolute, normalize } from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+ import { createRequire } from 'node:module';
10
+ import { spawnSync } from 'node:child_process';
11
+ class CheckError extends Error {
12
+ }
13
+ const USAGE = 'usage: ontrack-product-check <ADR number>';
14
+ // The directory under docs/adr/ holding this package's ADRs: the alias it is
15
+ // installed under, read from this script's path, node_modules/<alias>/dist/.
16
+ // Empty when the script runs from elsewhere (this package's own tests).
17
+ const pkg = dirname(dirname(fileURLToPath(import.meta.url)));
18
+ const NAMESPACE = basename(dirname(pkg)) === 'node_modules' ? basename(pkg) : '';
19
+ // The single repository copy of an ADR. Without a namespace, every directory
20
+ // of docs/adr/ but `local`, which holds the repository's own decisions.
21
+ function findAdr(root, number) {
22
+ const base = join(root, 'docs', 'adr');
23
+ const pattern = `docs/adr/${NAMESPACE || '*'}/${number}-*.md`;
24
+ const dirs = existsSync(base)
25
+ ? readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory() && (NAMESPACE ? d.name === NAMESPACE : d.name !== 'local'))
26
+ : [];
27
+ const hits = dirs.flatMap((d) => readdirSync(join(base, d.name)).filter((f) => f.startsWith(`${number}-`) && f.endsWith('.md')).map((f) => join(base, d.name, f)));
28
+ if (hits.length === 0)
29
+ throw new CheckError(`${number}: no file matches ${pattern}`);
30
+ if (hits.length > 1)
31
+ throw new CheckError(`${number}: several files match ${pattern}: ${hits.join(', ')}`);
32
+ return hits[0];
33
+ }
34
+ // A scalar as ontrack reads it: trailing ` # comment` cut, one pair of quotes removed.
35
+ function scalar(raw) {
36
+ let v = raw.replace(/\s+#.*$/, '').trim();
37
+ if (v.length >= 2 && (v[0] === '"' || v[0] === "'") && v.at(-1) === v[0])
38
+ v = v.slice(1, -1);
39
+ return v;
40
+ }
41
+ // The YAML frontmatter flattened to dotted keys (`traits.product.toolkit`).
42
+ // A value is a string, '' when empty, or a list (flow `[a, b]` or block `- a`).
43
+ // ponytail: an indentation reader for the shapes these ADRs and pm-skills
44
+ // templates use, not YAML (no anchors, no multi-line strings). A form it
45
+ // misses reads as a missing key, which fails, never a pass; switch to the
46
+ // `yaml` package if a real artifact breaks it.
47
+ function front(text) {
48
+ const lines = text.split(/\r?\n/);
49
+ const end = lines[0] === '---' ? lines.indexOf('---', 1) : -1;
50
+ const out = {};
51
+ if (end === -1)
52
+ return out;
53
+ const stack = [];
54
+ let last = '';
55
+ for (const line of lines.slice(1, end)) {
56
+ const body = line.trim();
57
+ if (!body || body.startsWith('#'))
58
+ continue;
59
+ const item = body.match(/^-\s*(.*)$/);
60
+ if (item) {
61
+ if (last)
62
+ out[last] = [...(Array.isArray(out[last]) ? out[last] : []), scalar(item[1])];
63
+ continue;
64
+ }
65
+ const kv = body.match(/^([\w.-]+):\s*(.*)$/);
66
+ if (!kv)
67
+ continue;
68
+ const indent = line.length - line.trimStart().length;
69
+ while (stack.length && stack.at(-1).indent >= indent)
70
+ stack.pop();
71
+ last = [...stack.map((s) => s.key), kv[1]].join('.');
72
+ stack.push({ indent, key: kv[1] });
73
+ const v = scalar(kv[2]);
74
+ out[last] = v.startsWith('[') && v.endsWith(']') ? v.slice(1, -1).split(',').map(scalar).filter(Boolean) : v;
75
+ }
76
+ return out;
77
+ }
78
+ const read = (file) => front(readFileSync(file, 'utf8'));
79
+ const rel = (root, file) => relative(root, file);
80
+ // One ruled value: a non-empty string.
81
+ function one(f, key, number, file, allowed) {
82
+ const v = f[`traits.${key}`];
83
+ if (v === undefined || v === '' || (Array.isArray(v) && !v.length))
84
+ throw new CheckError(`${number}: ${key} is not set in ${file}; the ADR is not ruled`);
85
+ if (Array.isArray(v))
86
+ throw new CheckError(`${number}: ${key} is not one value in ${file}`);
87
+ if (allowed && !allowed.includes(v))
88
+ throw new CheckError(`${number}: ${key} has an unknown value: ${v} (allowed: ${allowed.join(', ')})`);
89
+ return v;
90
+ }
91
+ // Another ADR of this track the check depends on, which must be accepted.
92
+ function accepted(root, number, by) {
93
+ const path = findAdr(root, number);
94
+ const f = read(path);
95
+ if (f.status !== 'accepted')
96
+ throw new CheckError(`${by}: ${number} must be accepted first (it is ${f.status || 'not ruled'})`);
97
+ return { file: rel(root, path), f };
98
+ }
99
+ // Markdown files tracked by git, relative to the root.
100
+ function tracked(root) {
101
+ const r = spawnSync('git', ['ls-files', '-z', '--', '*.md'], { cwd: root, encoding: 'utf8' });
102
+ if (r.status !== 0)
103
+ throw new CheckError(`git ls-files failed in ${root}: ${r.stderr.trim()}`);
104
+ return r.stdout.split('\0').filter(Boolean);
105
+ }
106
+ const under = (dir, path) => dir === '.' || path.startsWith(`${dir}/`);
107
+ // ADR-0003's root, normalised without its trailing slash, refused outside the repository.
108
+ function artifactsRoot(f, number, file) {
109
+ const raw = one(f, 'product.artifacts.root', number, file);
110
+ const dir = normalize(raw).replace(/\/+$/, '') || '.';
111
+ if (isAbsolute(raw) || dir === '..' || dir.startsWith('../'))
112
+ throw new CheckError(`${number}: product.artifacts.root is ${raw}, which is not a directory inside the repository`);
113
+ return dir;
114
+ }
115
+ function rootOf(root, by) {
116
+ const { file, f } = accepted(root, 'ADR-0003', by);
117
+ return artifactsRoot(f, 'ADR-0003', file);
118
+ }
119
+ // ADR-0004's levels and required level, refused when they cannot rank anything.
120
+ function evidenceOf(f, number, file) {
121
+ const levels = f['traits.product.evidence.levels'];
122
+ if (levels === undefined || levels === '' || (Array.isArray(levels) && !levels.length)) {
123
+ throw new CheckError(`${number}: product.evidence.levels is not set in ${file}; the ADR is not ruled`);
124
+ }
125
+ if (!Array.isArray(levels))
126
+ throw new CheckError(`${number}: product.evidence.levels is not a list in ${file}`);
127
+ const twice = levels.find((l, i) => levels.indexOf(l) !== i);
128
+ if (twice)
129
+ throw new CheckError(`${number}: product.evidence.levels lists ${twice} twice in ${file}`);
130
+ const required = one(f, 'product.evidence.required', number, file);
131
+ if (!levels.includes(required))
132
+ throw new CheckError(`${number}: product.evidence.required is ${required}, which is not one of product.evidence.levels (${levels.join(', ')})`);
133
+ return { levels, required };
134
+ }
135
+ // Prints each failure, or the pass line, and returns the exit code.
136
+ function report(fails, pass) {
137
+ if (fails.length) {
138
+ for (const f of fails)
139
+ console.log(f);
140
+ return 1;
141
+ }
142
+ console.log(pass);
143
+ return 0;
144
+ }
145
+ // --- ADR-0001: every ruled copy against adr/.mdschema.yml, plus named authors.
146
+ function adrs(root, file) {
147
+ const dir = dirname(file);
148
+ const ruled = readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => join(dir, f)).filter((f) => read(f).status !== 'proposed');
149
+ if (!ruled.length) {
150
+ console.log('ADR-0001: no ADR is ruled yet, nothing to check');
151
+ return 0;
152
+ }
153
+ const schema = join(pkg, 'adr', '.mdschema.yml');
154
+ const files = ruled.map((f) => rel(root, f));
155
+ console.log(`ADR-0001: checking ${files.length} ruled ADR(s) against ${rel(root, schema)}`);
156
+ const unnamed = ruled.filter((f) => !Array.isArray(read(f).authors) || !read(f).authors.length);
157
+ for (const f of unnamed)
158
+ console.log(`ADR-0001: ${rel(root, f)} is ruled and names no authors`);
159
+ // From this package, never the repository's node_modules/.bin nor PATH.
160
+ const manifest = createRequire(import.meta.url).resolve('@jackchuka/mdschema/package.json');
161
+ const cli = join(dirname(manifest), JSON.parse(readFileSync(manifest, 'utf8')).bin.mdschema);
162
+ const r = spawnSync(process.execPath, [cli, 'check', '--schema', schema, ...files], { cwd: root, stdio: 'inherit' });
163
+ if (r.error)
164
+ throw r.error;
165
+ return unnamed.length ? 1 : (r.status ?? 1);
166
+ }
167
+ // --- ADR-0002: with pm-skills, every product artifact says what kind it is.
168
+ function toolkit(root, file) {
169
+ const name = rel(root, file);
170
+ const tool = one(read(file), 'product.toolkit', 'ADR-0002', name, ['pm-skills', 'nanopm', 'none']);
171
+ if (tool !== 'pm-skills') {
172
+ console.log(`ADR-0002: product.toolkit is ${tool}, whose artifacts carry no artifact: key; nothing to check`);
173
+ return 0;
174
+ }
175
+ const dir = rootOf(root, 'ADR-0002');
176
+ const found = tracked(root).filter((p) => under(dir, p));
177
+ const fails = found.filter((p) => !front(readFileSync(join(root, p), 'utf8')).artifact).map((p) => `ADR-0002: ${p} has no artifact: key in its frontmatter`);
178
+ return report(fails, `ADR-0002: ${found.length} product artifact(s) under ${dir}/ say what kind they are`);
179
+ }
180
+ // --- ADR-0003: the root exists, and no artifact lives outside it.
181
+ function location(root, file) {
182
+ const dir = artifactsRoot(read(file), 'ADR-0003', rel(root, file));
183
+ if (!existsSync(join(root, dir)) || !statSync(join(root, dir)).isDirectory()) {
184
+ throw new CheckError(`ADR-0003: product.artifacts.root is ${dir}/, and that directory does not exist`);
185
+ }
186
+ const fails = tracked(root)
187
+ .filter((p) => !under(dir, p) && !!front(readFileSync(join(root, p), 'utf8')).artifact)
188
+ .map((p) => `ADR-0003: ${p} is a product artifact outside ${dir}/`);
189
+ return report(fails, `ADR-0003: every product artifact lives under ${dir}/`);
190
+ }
191
+ // --- ADR-0004: every product artifact declares a known evidence level.
192
+ function evidence(root, file) {
193
+ const { levels } = evidenceOf(read(file), 'ADR-0004', rel(root, file));
194
+ const dir = rootOf(root, 'ADR-0004');
195
+ const found = tracked(root).filter((p) => under(dir, p));
196
+ const fails = found.flatMap((p) => {
197
+ const v = front(readFileSync(join(root, p), 'utf8')).evidence;
198
+ if (v === undefined || v === '')
199
+ return [`ADR-0004: ${p} has no evidence: key in its frontmatter`];
200
+ if (Array.isArray(v) || !levels.includes(v))
201
+ return [`ADR-0004: ${p} says evidence: ${v}, not one of ${levels.join(', ')}`];
202
+ return [];
203
+ });
204
+ return report(fails, `ADR-0004: ${found.length} product artifact(s) under ${dir}/ declare their evidence`);
205
+ }
206
+ // --- ADR-0005: an open change that cites a PRD below the required level declares a probe.
207
+ function handoff(root, file) {
208
+ const mode = one(read(file), 'product.handoff', 'ADR-0005', rel(root, file), ['openspec', 'none']);
209
+ if (mode === 'none') {
210
+ console.log('ADR-0005: product.handoff is none; nothing to check');
211
+ return 0;
212
+ }
213
+ const dir = rootOf(root, 'ADR-0005');
214
+ const ev = accepted(root, 'ADR-0004', 'ADR-0005');
215
+ const { levels, required } = evidenceOf(ev.f, 'ADR-0004', ev.file);
216
+ const artifacts = new Set(tracked(root).filter((p) => under(dir, p)));
217
+ const base = join(root, 'openspec', 'changes');
218
+ const changes = existsSync(base)
219
+ ? readdirSync(base, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== 'archive' && existsSync(join(base, d.name, 'proposal.md'))).map((d) => d.name)
220
+ : [];
221
+ const fails = [];
222
+ for (const change of changes) {
223
+ const lines = readFileSync(join(base, change, 'proposal.md'), 'utf8').split(/\r?\n/);
224
+ const probe = lines.some((l) => /^Probe:\s*\S/.test(l));
225
+ for (const l of lines) {
226
+ const m = l.match(/^PRD:\s*(.*?)\s*$/);
227
+ if (!m)
228
+ continue;
229
+ const cited = normalize(m[1].replace(/^`(.*)`$/, '$1'));
230
+ if (!artifacts.has(cited)) {
231
+ fails.push(`ADR-0005: change ${change} cites PRD ${cited}, which is not a product artifact tracked under ${dir}/`);
232
+ continue;
233
+ }
234
+ const level = front(readFileSync(join(root, cited), 'utf8')).evidence;
235
+ const rank = typeof level === 'string' ? levels.indexOf(level) : -1;
236
+ if (rank === -1)
237
+ fails.push(`ADR-0005: change ${change} cites PRD ${cited}, whose evidence: ${level || '(none)'} is not one of ${levels.join(', ')}`);
238
+ else if (rank < levels.indexOf(required) && !probe) {
239
+ fails.push(`ADR-0005: change ${change} cites PRD ${cited} at evidence: ${level}, below ${required}, and its proposal has no Probe: line`);
240
+ }
241
+ }
242
+ }
243
+ return report(fails, `ADR-0005: ${changes.length} open change(s) checked against evidence ${required}`);
244
+ }
245
+ const CHECKS = {
246
+ 'ADR-0001': adrs,
247
+ 'ADR-0002': toolkit,
248
+ 'ADR-0003': location,
249
+ 'ADR-0004': evidence,
250
+ 'ADR-0005': handoff,
251
+ };
252
+ function main(argv, root = process.cwd()) {
253
+ try {
254
+ if (argv.length !== 1 || !argv[0])
255
+ throw new CheckError(USAGE);
256
+ const [number] = argv;
257
+ const check = CHECKS[number];
258
+ if (!check)
259
+ throw new CheckError(`this package ships no check for ${number}`);
260
+ return check(root, findAdr(root, number));
261
+ }
262
+ catch (e) {
263
+ if (!(e instanceof CheckError))
264
+ throw e;
265
+ console.error(e.message);
266
+ return 1;
267
+ }
268
+ }
269
+ process.exitCode = main(process.argv.slice(2));
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "@trivoallan/ontrack-product",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Product-management conventions your repositories import as ADRs: toolkit, where artifacts live, the evidence they claim, and when a change may build on them. Checked in CI.",
5
+ "license": "MIT-0",
6
+ "keywords": [
7
+ "ontrack",
8
+ "ontrack-tracks",
9
+ "adr",
10
+ "architecture-decision-records",
11
+ "product-management",
12
+ "conventions",
13
+ "openspec",
14
+ "coding-agents",
15
+ "claude-code"
16
+ ],
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/trivoallan/ontrack-product.git"
20
+ },
21
+ "type": "module",
22
+ "files": [
23
+ "adr/",
24
+ "dist/ontrack-product-check.js"
25
+ ],
26
+ "bin": {
27
+ "ontrack-product-check": "dist/ontrack-product-check.js"
28
+ },
29
+ "engines": {
30
+ "node": ">=22.18"
31
+ },
32
+ "scripts": {
33
+ "build": "tsc",
34
+ "prepare": "npm run build",
35
+ "test": "tsc --noEmit && node --test --experimental-test-coverage --test-coverage-include='checks/*.ts' --test-coverage-exclude='checks/*.test.ts' --test-coverage-lines=90 checks/*.test.ts"
36
+ },
37
+ "ontrack": {
38
+ "adr": "adr",
39
+ "namespace": "product"
40
+ },
41
+ "devDependencies": {
42
+ "@fission-ai/openspec": "1.13.1",
43
+ "@types/node": "22.20.5",
44
+ "typescript": "7.0.2"
45
+ },
46
+ "dependencies": {
47
+ "@jackchuka/mdschema": "0.15.1"
48
+ },
49
+ "allowScripts": {
50
+ "@jackchuka/mdschema": false
51
+ }
52
+ }