@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 +16 -0
- package/README.md +55 -2
- package/adr/.mdschema.yml +48 -0
- package/adr/ADR-0001-record-product-decisions.md +174 -0
- package/adr/ADR-0002-toolkit.md +149 -0
- package/adr/ADR-0003-location.md +152 -0
- package/adr/ADR-0004-evidence.md +177 -0
- package/adr/ADR-0005-handoff.md +174 -0
- package/dist/ontrack-product-check.js +269 -0
- package/package.json +50 -4
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
|
-
#
|
|
1
|
+
# ontrack-product
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|