project-spec 0.9.2 → 0.11.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/README.md +52 -14
- package/bin/project-spec.mjs +129 -15
- package/package.json +2 -1
- package/skills/project-knowledge/SKILL.md +23 -7
- package/skills/project-knowledge/references/agents.md +30 -0
- package/skills/project-knowledge/references/format.md +5 -3
- package/skills/project-knowledge/references/gaps.md +7 -2
- package/skills/project-knowledge/references/sync.md +1 -1
- package/skills/project-knowledge/scripts/coverage.py +7 -3
- package/skills/project-knowledge/scripts/knowledge.py +74 -5
- package/{skills/project-knowledge/assets → viewer}/viewer.html +251 -52
- package/skills/project-knowledge/scripts/test_coverage.py +0 -128
- package/skills/project-knowledge/scripts/test_knowledge.py +0 -1276
- package/skills/project-knowledge/scripts/test_maintain.py +0 -864
- package/skills/project-knowledge/scripts/test_merge.py +0 -165
- package/skills/spec-change/LICENSE +0 -21
- package/skills/spec-change/SKILL.md +0 -63
- package/skills/spec-change/agents/openai.yaml +0 -4
- package/skills/spec-change/references/gaps.md +0 -159
- /package/skills/{spec-change → project-knowledge}/references/plan.md +0 -0
|
@@ -1,165 +0,0 @@
|
|
|
1
|
-
import json
|
|
2
|
-
import os
|
|
3
|
-
import shutil
|
|
4
|
-
from pathlib import Path
|
|
5
|
-
import subprocess
|
|
6
|
-
import tempfile
|
|
7
|
-
import unittest
|
|
8
|
-
|
|
9
|
-
SCRIPT = Path(__file__).with_name('merge.py')
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
class MergeTests(unittest.TestCase):
|
|
13
|
-
def setUp(self):
|
|
14
|
-
self.tmp = tempfile.TemporaryDirectory()
|
|
15
|
-
self.addCleanup(self.tmp.cleanup)
|
|
16
|
-
self.repo = Path(self.tmp.name)
|
|
17
|
-
self.git('init', '-b', 'main')
|
|
18
|
-
self.git('config', 'user.email', 'test@example.invalid')
|
|
19
|
-
self.git('config', 'user.name', 'Test')
|
|
20
|
-
self.vault = self.repo / 'vault'
|
|
21
|
-
(self.vault / '.knowledge').mkdir(parents=True)
|
|
22
|
-
self.note('old.md', 'old', 'base')
|
|
23
|
-
self.note('shared.md', 'shared', 'base')
|
|
24
|
-
(self.vault / '.knowledge/review.json').write_text('base')
|
|
25
|
-
self.commit('base')
|
|
26
|
-
self.base = self.git('rev-parse', 'HEAD').strip()
|
|
27
|
-
self.git('checkout', '-b', 'ours')
|
|
28
|
-
|
|
29
|
-
def git(self, *args):
|
|
30
|
-
return subprocess.run(['git', '-C', str(self.repo), *args], capture_output=True, text=True, check=True).stdout
|
|
31
|
-
|
|
32
|
-
def note(self, name, ident, body=''):
|
|
33
|
-
path = self.vault / name
|
|
34
|
-
path.parent.mkdir(parents=True, exist_ok=True)
|
|
35
|
-
path.write_text('---\nid: ' + json.dumps(ident) + '\n---\n' + body + '\n')
|
|
36
|
-
|
|
37
|
-
def commit(self, msg):
|
|
38
|
-
self.git('add', '-A')
|
|
39
|
-
self.git('commit', '-m', msg)
|
|
40
|
-
|
|
41
|
-
def call(self, ours='ours', theirs='theirs', repo=None, vault=None):
|
|
42
|
-
return subprocess.run(['python3', str(SCRIPT), 'inspect', '--repo', str(repo or self.repo), '--vault', str(vault or self.vault), '--ours', ours, '--theirs', theirs, '--json'], capture_output=True, text=True)
|
|
43
|
-
|
|
44
|
-
def test_overlap_rename_delete_duplicate_and_states_without_mutation(self):
|
|
45
|
-
self.git('mv', 'vault/old.md', 'vault/renamed.md')
|
|
46
|
-
self.note('shared.md', 'shared', 'ours')
|
|
47
|
-
self.note('a.md', 'same-id', 'ours')
|
|
48
|
-
self.note('both.md', 'ours-id', 'ours')
|
|
49
|
-
(self.vault / '.knowledge/review.json').write_text('ours')
|
|
50
|
-
self.commit('ours')
|
|
51
|
-
self.git('checkout', '-b', 'theirs', self.base)
|
|
52
|
-
self.git('rm', 'vault/old.md')
|
|
53
|
-
self.note('shared.md', 'shared', 'theirs')
|
|
54
|
-
self.note('b.md', 'same-id', 'theirs')
|
|
55
|
-
self.note('both.md', 'theirs-id', 'theirs')
|
|
56
|
-
(self.vault / '.knowledge/review.json').write_text('theirs')
|
|
57
|
-
(self.vault / '.knowledge/sources.json').write_text('{}')
|
|
58
|
-
self.commit('theirs')
|
|
59
|
-
before = self.git('status', '--porcelain=v1')
|
|
60
|
-
index = (self.repo / '.git/index').read_bytes()
|
|
61
|
-
result = self.call()
|
|
62
|
-
self.assertEqual(result.returncode, 0, result.stderr)
|
|
63
|
-
report = json.loads(result.stdout)
|
|
64
|
-
self.assertEqual(report['base'], self.base)
|
|
65
|
-
self.assertTrue(report['needs_review'])
|
|
66
|
-
self.assertEqual(report['shared_canonical_paths'], ['vault/both.md', 'vault/old.md', 'vault/shared.md'])
|
|
67
|
-
self.assertEqual(report['duplicate_ids'], [{'id': 'same-id', 'ours': ['vault/a.md'], 'theirs': ['vault/b.md']}])
|
|
68
|
-
self.assertTrue(any(x['status'].startswith('R') for x in report['changes']['ours']))
|
|
69
|
-
self.assertTrue(any(x['status'] == 'D' for x in report['changes']['theirs']))
|
|
70
|
-
self.assertTrue(report['reviewed_state']['.knowledge/review.json']['different'])
|
|
71
|
-
self.assertIsNotNone(report['reviewed_state']['.knowledge/review.json']['base'])
|
|
72
|
-
self.assertIsNone(report['reviewed_state']['.knowledge/sources.json']['base'])
|
|
73
|
-
self.assertEqual(before, self.git('status', '--porcelain=v1'))
|
|
74
|
-
self.assertEqual(index, (self.repo / '.git/index').read_bytes())
|
|
75
|
-
|
|
76
|
-
def test_disjoint_changes(self):
|
|
77
|
-
self.note('left.md', 'left'); self.commit('left')
|
|
78
|
-
self.git('checkout', '-b', 'theirs', self.base)
|
|
79
|
-
self.note('right.md', 'right'); self.commit('right')
|
|
80
|
-
result = self.call()
|
|
81
|
-
self.assertEqual(result.returncode, 0, result.stderr)
|
|
82
|
-
report = json.loads(result.stdout)
|
|
83
|
-
self.assertFalse(report['needs_review'])
|
|
84
|
-
self.assertEqual(report['shared_canonical_paths'], [])
|
|
85
|
-
|
|
86
|
-
def test_missing_and_unrelated_refs_and_shallow(self):
|
|
87
|
-
self.note('x.md', 'x'); self.commit('ours')
|
|
88
|
-
self.assertEqual(self.call(theirs='missing').returncode, 1)
|
|
89
|
-
self.git('checkout', '--orphan', 'theirs')
|
|
90
|
-
self.git('rm', '-rf', '.')
|
|
91
|
-
self.vault.mkdir(exist_ok=True)
|
|
92
|
-
self.note('y.md', 'y'); self.commit('unrelated')
|
|
93
|
-
result = self.call()
|
|
94
|
-
self.assertEqual(result.returncode, 1)
|
|
95
|
-
self.assertIn('no common merge base', result.stderr)
|
|
96
|
-
clone = self.repo.parent / (self.repo.name + '-shallow')
|
|
97
|
-
self.addCleanup(lambda: __import__('shutil').rmtree(clone, ignore_errors=True))
|
|
98
|
-
subprocess.run(['git', 'clone', '--depth=1', '-q', self.repo.as_uri(), str(clone)], check=True)
|
|
99
|
-
result = self.call(ours='HEAD', theirs='HEAD', repo=clone, vault=clone / 'vault')
|
|
100
|
-
self.assertEqual(result.returncode, 1)
|
|
101
|
-
self.assertIn('shallow history', result.stderr)
|
|
102
|
-
|
|
103
|
-
def test_ambiguous_ref_and_multiple_merge_bases(self):
|
|
104
|
-
self.note('x.md', 'x'); self.commit('ours')
|
|
105
|
-
self.git('tag', 'ours', self.base)
|
|
106
|
-
self.assertIn('ambiguous ref', self.call(ours='ours', theirs='HEAD').stderr)
|
|
107
|
-
self.git('tag', '-d', 'ours')
|
|
108
|
-
first = self.git('rev-parse', 'HEAD').strip()
|
|
109
|
-
self.git('checkout', '-b', 'theirs', self.base)
|
|
110
|
-
self.note('y.md', 'y'); self.commit('theirs')
|
|
111
|
-
second = self.git('rev-parse', 'HEAD').strip()
|
|
112
|
-
tree = self.git('rev-parse', 'HEAD^{tree}').strip()
|
|
113
|
-
one = self.git('commit-tree', tree, '-p', first, '-p', second, '-m', 'merge one').strip()
|
|
114
|
-
two = self.git('commit-tree', tree, '-p', second, '-p', first, '-m', 'merge two').strip()
|
|
115
|
-
result = self.call(ours=one, theirs=two)
|
|
116
|
-
self.assertEqual(result.returncode, 1)
|
|
117
|
-
self.assertIn('multiple merge bases', result.stderr)
|
|
118
|
-
|
|
119
|
-
def test_fresh_invocation_does_not_write_fixture_or_skill(self):
|
|
120
|
-
self.note('left.md', 'left'); self.commit('left')
|
|
121
|
-
self.git('checkout', '-b', 'theirs', self.base)
|
|
122
|
-
self.note('right.md', 'right'); self.commit('right')
|
|
123
|
-
with tempfile.TemporaryDirectory() as directory:
|
|
124
|
-
copied = Path(directory) / 'scripts'
|
|
125
|
-
copied.mkdir()
|
|
126
|
-
for name in ('merge.py', 'knowledge.py'):
|
|
127
|
-
shutil.copy2(SCRIPT.parent / name, copied / name)
|
|
128
|
-
def inventory(root):
|
|
129
|
-
return {str(p.relative_to(root)): ('dir' if p.is_dir() else p.read_bytes())
|
|
130
|
-
for p in root.rglob('*') if not p.is_symlink()}
|
|
131
|
-
before_repo, before_skill = inventory(self.repo), inventory(copied)
|
|
132
|
-
env = dict(os.environ)
|
|
133
|
-
env.pop('PYTHONDONTWRITEBYTECODE', None)
|
|
134
|
-
result = subprocess.run(['python3', str(copied / 'merge.py'), 'inspect', '--repo', str(self.repo), '--vault', str(self.vault), '--ours', 'ours', '--theirs', 'theirs', '--json'], env=env, capture_output=True, text=True)
|
|
135
|
-
self.assertEqual(result.returncode, 0, result.stderr)
|
|
136
|
-
self.assertEqual(before_repo, inventory(self.repo))
|
|
137
|
-
self.assertEqual(before_skill, inventory(copied))
|
|
138
|
-
|
|
139
|
-
def test_partial_and_promisor_config_rejected_before_object_access(self):
|
|
140
|
-
self.note('x.md', 'x'); self.commit('ours')
|
|
141
|
-
for key, value in (('extensions.partialClone', 'origin'), ('remote.origin.promisor', 'true')):
|
|
142
|
-
with self.subTest(key=key):
|
|
143
|
-
self.git('config', key, value)
|
|
144
|
-
result = self.call(ours='does-not-exist', theirs='HEAD')
|
|
145
|
-
self.assertEqual(result.returncode, 1)
|
|
146
|
-
self.assertIn('requires full local history', result.stderr)
|
|
147
|
-
self.assertNotIn(value, result.stderr)
|
|
148
|
-
self.git('config', '--unset', key)
|
|
149
|
-
|
|
150
|
-
def test_symlink_blob_not_parsed_and_credential_paths_ignored(self):
|
|
151
|
-
(self.vault / 'alias.md').symlink_to('old.md')
|
|
152
|
-
(self.vault / '.env.md').write_text('---\nid: "secret"\n---\n')
|
|
153
|
-
self.commit('unsafe')
|
|
154
|
-
self.git('checkout', '-b', 'theirs', self.base)
|
|
155
|
-
self.note('other.md', 'other'); self.commit('other')
|
|
156
|
-
result = self.call()
|
|
157
|
-
self.assertEqual(result.returncode, 0, result.stderr)
|
|
158
|
-
report = json.loads(result.stdout)
|
|
159
|
-
self.assertEqual(report['skipped_id_paths']['ours'][0]['reason'], 'not a regular file blob')
|
|
160
|
-
self.assertNotIn('.env.md', result.stdout)
|
|
161
|
-
self.assertTrue(report['needs_review'])
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
if __name__ == '__main__':
|
|
165
|
-
unittest.main()
|
|
@@ -1,21 +0,0 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 WorldStoryCm
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: spec-change
|
|
3
|
-
description: Change the product, starting from the specification. A person edits the spec text on a branch and the diff is the change request; use to review that diff for contradictions, ambiguity and missing cases before any code is written, then implement it and check every changed statement against the code. Also use to plan a change without building it, with scope, ordered steps, decision gates and observable acceptance criteria. Works on a project-knowledge vault or on any specification kept as Markdown in Git.
|
|
4
|
-
license: MIT
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Spec Change
|
|
8
|
-
|
|
9
|
-
The person describes what they want by editing the specification, not by describing code. Your job is to make the code say what the edited spec says, and to tell them where their text cannot be built as written. They follow the work by reading the spec and your questions, so write for a reader who does not open the source.
|
|
10
|
-
|
|
11
|
-
This skill changes application code. It is the only one in this bundle that does; a plan-only request changes none. Read the repository's instructions first, work on the branch that holds the spec edits, and leave committing, pushing and merging to the person unless they ask.
|
|
12
|
-
|
|
13
|
-
## Plan only
|
|
14
|
-
|
|
15
|
-
When the person asks for a plan and no code, or wants to plan a gap they accepted, follow [the planning guide](references/plan.md) and stop there. The deliverable is the plan; nothing below this section applies until they ask for the change itself.
|
|
16
|
-
|
|
17
|
-
## Read the change request
|
|
18
|
-
|
|
19
|
-
- Find the base the person branched from (ask if it is not obvious) and read the spec diff against it: committed and uncommitted edits to the spec pages. In a project-knowledge vault these are `areas/` and `notes/`; ignore `.knowledge/`.
|
|
20
|
-
- The base spec must describe the base code. If it is behind (a pending sync, freshness warnings), the diff mixes the person's intent with ordinary drift; say so and separate the two before going on.
|
|
21
|
-
- Restate every changed statement as one line in plain language: what happens today, what should happen instead. A removed sentence is a change too. Edits that only reword a page without changing behavior are listed as such and need no code.
|
|
22
|
-
- Do not treat anything outside the diff as a request. An idea in a chat message or a gap page becomes part of the change only when the person puts it into the spec text.
|
|
23
|
-
|
|
24
|
-
## Ask before writing code
|
|
25
|
-
|
|
26
|
-
Review the change as a careful colleague would review a requirement, against both the rest of the spec and the code.
|
|
27
|
-
|
|
28
|
-
- **Contradictions.** Read the pages linked from the changed ones, the rest of their area and the pages that cite the same sources. Name each statement elsewhere that the edit now contradicts.
|
|
29
|
-
- **Ambiguity.** For each changed statement, say who triggers it, when, and what they observe. If two reasonable readings lead to different code, that is a question.
|
|
30
|
-
- **Missing cases.** Check what the edit leaves unsaid: failure and denial, permissions, empty and boundary values, existing stored data, concurrent use, and what other features that call the same code will now do.
|
|
31
|
-
- **Cost surprises.** Trace the current code path far enough to see what the change touches. Tell the person when a one-line edit implies a migration, a contract change for other callers or a new dependency.
|
|
32
|
-
|
|
33
|
-
Sort the findings into two lists. **Questions** need the person's answer because the answer changes behavior; give each a number, the options and the one you would pick. **Assumptions** are choices you can make and reverse cheaply; state them and proceed. Keep the lists short and written in the language of the spec, not of the code.
|
|
34
|
-
|
|
35
|
-
Stop and wait for answers while any question is open. Each answer goes into the spec text, written by the person or by you in their words, so that the spec, not the conversation, holds the decision. If the person cannot answer now, take that statement out of this round: restore its as-built wording and, in a vault, record the open choice as a gap following [gaps.md](references/gaps.md).
|
|
36
|
-
|
|
37
|
-
## Implement
|
|
38
|
-
|
|
39
|
-
- For more than a small change, lay out the ordered steps first, as [the planning guide](references/plan.md) describes: shared contracts before their callers, each step with the check that verifies it.
|
|
40
|
-
- Every changed statement gets a check that would fail on the old behavior, at the boundary the statement describes. Follow the project's conventions and keep the change inside the scope of the diff. If you find something else wrong on the way, report it; do not fix it silently.
|
|
41
|
-
- If the code shows that a statement cannot hold as written, stop and return to the person with the reason and options. Do not reword their spec to match what was easy to build.
|
|
42
|
-
|
|
43
|
-
## Check the code against the spec
|
|
44
|
-
|
|
45
|
-
When the code is done, read it again as if you had not written it and compare it with each changed page, statement by statement.
|
|
46
|
-
|
|
47
|
-
- A statement that holds: note the file and symbol that implement it and the check that ran. Reading a test is not running it; mark checks you did not run `NOT RUN`.
|
|
48
|
-
- A statement that does not hold: fix the code, or bring it to the person. The spec changes only on their word.
|
|
49
|
-
- In a vault, update each changed page's `sources` to the files it now rests on, then run `check` and `snapshot --notes` for the pages you re-read, as the project-knowledge skill describes. No spec page may be left describing behavior the branch does not implement: before the work is called done, such text goes back to its as-built wording and the intent moves to a gap.
|
|
50
|
-
|
|
51
|
-
## Report
|
|
52
|
-
|
|
53
|
-
```text
|
|
54
|
-
# Spec change: <title>
|
|
55
|
-
## What changed one line per statement: before, after
|
|
56
|
-
## Answered questions the question, the answer, where the spec now says it
|
|
57
|
-
## Assumptions choices made without asking, and how to reverse them
|
|
58
|
-
## Evidence statement -> file and symbol -> check, PASS / FAIL / NOT RUN
|
|
59
|
-
## Not done statements taken out of this round, with their gaps
|
|
60
|
-
## Spec text I edited every wording change made by the agent, so the person can review it
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
Keep the report in the person's language and in terms of behavior. Code references belong in the Evidence section only.
|
|
@@ -1,4 +0,0 @@
|
|
|
1
|
-
interface:
|
|
2
|
-
display_name: "Spec Change"
|
|
3
|
-
short_description: "Plan a change, or build it from an edited spec"
|
|
4
|
-
default_prompt: "Use $spec-change to take my edits to the specification as the change request. Review the diff and ask your questions before writing code, then implement it and check every changed statement against the code."
|
|
@@ -1,159 +0,0 @@
|
|
|
1
|
-
# Writing gap and plan pages
|
|
2
|
-
|
|
3
|
-
This page is self-contained: it is enough to create, update or close a gap page, or to write a plan page, in a project-knowledge vault. Nothing else needs to be read first.
|
|
4
|
-
|
|
5
|
-
## Why gaps are separate from the spec
|
|
6
|
-
|
|
7
|
-
A vault has two layers. Spec pages (`areas/`, `notes/`) say what the code does today, nothing more. Gap pages (`gaps/`) hold every doubt, missing piece, contradiction or idea, one question per page. Plan pages (`plans/`) say how to build one accepted gap. The layers stay apart so a reader can trust the spec without wondering which sentences are proposals, and so a person can look at each gap on its own and decide it. An agent proposes; a person decides.
|
|
8
|
-
|
|
9
|
-
Gap and plan pages link to spec notes with wikilinks. Spec pages never link back to gaps or plans (the validator rejects it).
|
|
10
|
-
|
|
11
|
-
## Files and properties
|
|
12
|
-
|
|
13
|
-
A gap lives in `gaps/<slug>.md`; a plan in `plans/<gap-id>.md`. Frontmatter is one property per line with a JSON value (strings in double quotes, arrays on one line).
|
|
14
|
-
|
|
15
|
-
Every page: `id` (unique ASCII slug), `title`, `type`, `areas` (at least one existing area id), `sources` (repository-relative files read; may be empty for gaps and plans), `updated` (`YYYY-MM-DD`, last substantive edit).
|
|
16
|
-
|
|
17
|
-
A gap must not have `status`; its progress is carried by `recheck` and `decision`.
|
|
18
|
-
|
|
19
|
-
| Property | When | Values |
|
|
20
|
-
| --- | --- | --- |
|
|
21
|
-
| `type` | always | `"gap"` |
|
|
22
|
-
| `kind` | always | one of `product-gap` (accepted requirement missing or unmet), `verification-gap` (behavior exists but evidence is missing), `product-plan` (a proposal or open product choice), `conflict` (credible sources disagree), `knowledge-gap` (a specific behavior is unexplained or undocumented; never the vault's own research backlog) |
|
|
23
|
-
| `recheck` | always | `not-checked`, `confirmed` (still holds), `not-reproduced` (no longer holds), `outdated` (the cited sources changed after the last recorded recheck); see [What a recheck means](#what-a-recheck-means) |
|
|
24
|
-
| `rechecked_by` | when `recheck` is not `not-checked` | a person's name, or `agent`; an agent always writes `agent`, and a person's name appears only when that person ran the check and said so |
|
|
25
|
-
| `rechecked_on` | when `recheck` is not `not-checked` | `YYYY-MM-DD` |
|
|
26
|
-
| `decision` | always | `open`, `accepted`, `rejected`, `deferred`, `done`, `duplicate` |
|
|
27
|
-
| `decided_by` | when `decision` is `accepted`, `rejected` or `deferred` | a person's name; the value `agent` is an error |
|
|
28
|
-
| `decided_on` | when `decision` is `accepted`, `rejected` or `deferred` | `YYYY-MM-DD` |
|
|
29
|
-
| `duplicate_of` | when `decision` is `duplicate` | id of another existing gap (not itself) |
|
|
30
|
-
| `priority`, `confidence` | optional, gap and plan pages only | short strings, e.g. `"high"`. Use `high`, `medium` or `low` for `priority` (or `P0` to `P4`): the viewer lists the most urgent gap of each state first and can show one priority only. |
|
|
31
|
-
|
|
32
|
-
`decided_by` and `decided_on` are also allowed on `done` and `duplicate` but not required. With `outdated`, `rechecked_by` and `rechecked_on` stay in place as the record of the last recheck actually done. A fresh recheck replaces all three fields and adds a new dated entry to the `Recheck` section; keep the older entries.
|
|
33
|
-
|
|
34
|
-
The `rechecked_*` fields must be absent only while `recheck` is `not-checked`; `decided_*` absent while `decision` is `open`; `duplicate_of` absent for any other decision. Optional `tags`, `aliases`, `task_ids`, `summary` and `verification` work as on other pages.
|
|
35
|
-
|
|
36
|
-
A plan page has `type: "plan"`, a `status` (`current`, `partial`, `planned`, `stale` or `superseded`; use `planned` until the work is done) and `gap`: the id of an existing gap whose `decision` is `accepted` or `done`.
|
|
37
|
-
|
|
38
|
-
## The six sections
|
|
39
|
-
|
|
40
|
-
Every gap has exactly these `##` headings, once each (order does not matter). A missing or repeated heading is a validation error.
|
|
41
|
-
|
|
42
|
-
- `## Current behavior`: what the code does today in this area, as plain fact, linking the relevant spec notes. No opinion about what it should do.
|
|
43
|
-
- `## Gap`: the one question this page asks, phrased so a person can answer it. If the finding has a second aspect with a different next step or owner, make it a second page.
|
|
44
|
-
- `## Evidence`: what supports the question: files and symbols read, commands run with results, `NOT RUN` for anything only read. Label documented intent, static reading and observed execution separately.
|
|
45
|
-
- `## Recheck`: while `not-checked`, write "Not checked yet." Otherwise: who re-verified, how, when, and what they found, newest entry last. When you set `outdated`, add a dated line saying which source changed. The pass that raised the gap is not a recheck.
|
|
46
|
-
- `## Discussion`: append-only log, see below.
|
|
47
|
-
- `## Decision`: while `open`, write "Open." Otherwise the decision and its reason, in the words of the person who decided. For `done`, say where in the code the question is now closed. For `duplicate`, name the surviving gap.
|
|
48
|
-
|
|
49
|
-
When `recheck` is not `not-checked`, the Recheck section must have text; when `decision` is not `open`, so must Decision.
|
|
50
|
-
|
|
51
|
-
## What a recheck means
|
|
52
|
-
|
|
53
|
-
A recheck asks one question of every gap, whatever its kind: **does the page's `Current behavior` section still describe the code?** It is not a verdict on the gap's worth. The reason to ask is that a person decides on the gap only after someone has confirmed the page still describes reality, and that needs to be possible for proposals and questions about unexplained behavior too, not only for defects.
|
|
54
|
-
|
|
55
|
-
- `confirmed` ("confirmed (still holds)"): yes. What `Current behavior` says, including what it says is absent, is what the code does now.
|
|
56
|
-
- `not-reproduced` ("not reproduced (no longer holds)"): no. The code no longer matches the description: the capability exists, the defect is gone, the sources stopped disagreeing. The usual next step is `decision: "done"`, or rewriting the gap around what is true now.
|
|
57
|
-
|
|
58
|
-
What that means for each kind:
|
|
59
|
-
|
|
60
|
-
| Kind | `confirmed` (still holds) | `not-reproduced` (no longer holds) |
|
|
61
|
-
| --- | --- | --- |
|
|
62
|
-
| `product-gap` | The requirement is still unmet: the code does not do what it asks for. | The code now meets the requirement, or the defect cannot be reproduced. |
|
|
63
|
-
| `verification-gap` | The behavior is as described and the evidence is still missing. | Evidence now exists (a test, a run, a log), or the behavior differs from the description. |
|
|
64
|
-
| `product-plan` | The proposed capability is still absent and nothing already implements it. | Something in the code now does what was proposed. |
|
|
65
|
-
| `conflict` | Both sources still say what the page says, and they still disagree. | One source changed or the claims no longer clash. |
|
|
66
|
-
| `knowledge-gap` | The thing is still unexplained or undocumented: no code, comment or document answers it. | The code or a source now answers the question. |
|
|
67
|
-
|
|
68
|
-
A recheck never judges whether a proposal is worth doing, whether a requirement is right or which side of a conflict should win. That is the person's decision, made afterwards. For a proposal or a question about unexplained behavior the recheck is usually quick, for example reading the code to confirm the capability is absent, and it is still required: without it the gap stays in `needs-recheck` and cannot reach `needs-decision`. Write what you read in `Recheck` so the person can see the page was checked, not assumed.
|
|
69
|
-
|
|
70
|
-
## Discussion entries
|
|
71
|
-
|
|
72
|
-
One bullet per entry, oldest first, never edited or removed afterwards:
|
|
73
|
-
|
|
74
|
-
```text
|
|
75
|
-
- 2026-11-15 · Name: what was said, proposed or learned.
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
Use `agent` as the name for entries you write yourself. Layout of options, objections and questions belongs here, not in `Decision`, which records only the outcome.
|
|
79
|
-
|
|
80
|
-
## Who sets which field
|
|
81
|
-
|
|
82
|
-
| Field | Who |
|
|
83
|
-
| --- | --- |
|
|
84
|
-
| New gap: `kind`, `recheck: "not-checked"`, `decision: "open"`, optional `priority`/`confidence` | The agent that found it |
|
|
85
|
-
| `recheck`, `rechecked_by`, `rechecked_on`, `Recheck` text | Whoever actually performed the check; an agent writes `agent` only for a check it ran itself, with its commands and results. An agent may also set `recheck: "outdated"` when a cited source changed since the recorded recheck, keeping the other two fields |
|
|
86
|
-
| `decision: accepted`, `rejected`, `deferred` with `decided_by`, `decided_on` | A person only. An agent writes it only when a person said so in the conversation, and records that person's name |
|
|
87
|
-
| `decision: done` | An agent may set it after reading current code that closes the question; it cites where in `Decision` and records that reading as a recheck (see below). A person closing a gap as done records the decision in `decided_by`/`Decision`; their name goes in `rechecked_by` only if they read or ran the current code themselves, otherwise the recheck fields stay as they are |
|
|
88
|
-
| `decision: duplicate`, `duplicate_of` | Agent or person (bookkeeping) |
|
|
89
|
-
| `Discussion` | Anyone, by appending |
|
|
90
|
-
|
|
91
|
-
Never guess a decision from silence, from a plan existing, or from a task being created. If it is unclear whether a person decided, leave `open` and ask in `Discussion`.
|
|
92
|
-
|
|
93
|
-
## Closing a gap as done
|
|
94
|
-
|
|
95
|
-
When an agent sets `decision: "done"` because it read (or ran) the current code and the gap no longer holds, that reading is itself a recheck, and the page should say so. In the same edit record `recheck: "not-reproduced"`, `rechecked_by: "agent"`, today's `rechecked_on`, and add a dated entry to `Recheck` saying what was read or run. In `Decision`, say where in the code the question is now closed. The two sections answer different questions: `Recheck` is how you know it no longer holds, `Decision` is where the code does it. Without the recheck fields a closed gap looks as if nobody ever looked at the code. When a person closes a gap as done, they record the decision in `decided_by` and `Decision`. Their name goes in `rechecked_by` (not `agent`) only if they read or ran the current code themselves and add a `Recheck` entry saying what they did; if they decided without doing so, leave the recheck fields as they are. If you are not sure the question is closed, leave it open.
|
|
96
|
-
|
|
97
|
-
## Derived state
|
|
98
|
-
|
|
99
|
-
Computed by the helper, never written into Markdown:
|
|
100
|
-
|
|
101
|
-
| `decision` | `recheck` | State |
|
|
102
|
-
| --- | --- | --- |
|
|
103
|
-
| `open` | `not-checked` or `outdated` | `needs-recheck` |
|
|
104
|
-
| `open` | `confirmed` or `not-reproduced` | `needs-decision` |
|
|
105
|
-
| anything else | any | the `decision` value |
|
|
106
|
-
|
|
107
|
-
Every open gap passes through a recheck before `needs-decision`, including proposals (`product-plan`) and questions about unexplained behavior (`knowledge-gap`). Rechecking a proposal means confirming the capability is still absent, not judging the proposal.
|
|
108
|
-
|
|
109
|
-
## Example gap page (illustrative)
|
|
110
|
-
|
|
111
|
-
````markdown
|
|
112
|
-
---
|
|
113
|
-
id: "invoice-retry-limit"
|
|
114
|
-
title: "Should failed invoice emails retry more than once?"
|
|
115
|
-
type: "gap"
|
|
116
|
-
kind: "product-plan"
|
|
117
|
-
areas: ["billing"]
|
|
118
|
-
sources: ["src/billing/mailer.py"]
|
|
119
|
-
recheck: "confirmed"
|
|
120
|
-
rechecked_by: "Dana Ruiz"
|
|
121
|
-
rechecked_on: "2026-11-15"
|
|
122
|
-
decision: "open"
|
|
123
|
-
priority: "medium"
|
|
124
|
-
updated: "2026-11-15"
|
|
125
|
-
---
|
|
126
|
-
|
|
127
|
-
# Should failed invoice emails retry more than once?
|
|
128
|
-
|
|
129
|
-
## Current behavior
|
|
130
|
-
|
|
131
|
-
`send_invoice` makes one delivery attempt and logs a failure; it does not schedule another. See [[notes/invoice-delivery|Invoice delivery]].
|
|
132
|
-
|
|
133
|
-
## Gap
|
|
134
|
-
|
|
135
|
-
Customers with a temporary mail outage never receive the invoice. Should the mailer retry, and if so how many times and over what period?
|
|
136
|
-
|
|
137
|
-
## Evidence
|
|
138
|
-
|
|
139
|
-
- Static: `send_invoice` in `src/billing/mailer.py` has no retry loop or queue call.
|
|
140
|
-
- Documented intent: none found; no requirement mentions retries.
|
|
141
|
-
- No test covers a failed first attempt (NOT RUN, nothing to run).
|
|
142
|
-
|
|
143
|
-
## Recheck
|
|
144
|
-
|
|
145
|
-
2026-11-15, Dana Ruiz: re-read `send_invoice` and ran it against a stubbed transport that raises on the first call; the invoice stays unsent, one error is logged and nothing schedules a second attempt. No queue or retry code exists elsewhere in `src/billing/`. Confirmed (still holds): the capability is absent. Whether to add it is the open question below.
|
|
146
|
-
|
|
147
|
-
## Discussion
|
|
148
|
-
|
|
149
|
-
- 2026-11-15 · agent: Options are (a) fixed three retries within an hour, (b) hand the email to the existing job queue, (c) leave as is and show a "resend" button.
|
|
150
|
-
- 2026-11-16 · Dana Ruiz: Leaning to (b); need to check queue limits first.
|
|
151
|
-
|
|
152
|
-
## Decision
|
|
153
|
-
|
|
154
|
-
Open.
|
|
155
|
-
````
|
|
156
|
-
|
|
157
|
-
## Writing a plan page
|
|
158
|
-
|
|
159
|
-
Create one only for a gap whose `decision` is `accepted`. Name it `plans/<gap-id>.md`, give it its own `id` (for example `<gap-id>-plan`), set `gap` to the gap's id and use the gap's areas. The body states the goal and what exists today (with links to spec notes), the ordered steps with the files they touch, observable acceptance checks, what is out of scope, and which checks have not been run. A plan records intent for one decision; it does not add facts to the spec. When the work lands, an agent that reads the code may set the gap to `done`, and the spec notes are then updated from the code.
|
|
File without changes
|