@antoneeo/kb-agentic-skill 1.25.0 → 1.26.1
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/CHANGELOG.md +16 -0
- package/README.md +2 -2
- package/gemini-extension.json +1 -1
- package/package.json +1 -1
- package/skills/kb-agentic-skill/SKILL.md +5 -4
- package/skills/kb-agentic-skill/elicitation.md +16 -5
- package/skills/kb-agentic-skill/templates.md +45 -6
- package/skills/kb-agentic-skill/vision.md +69 -6
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
Every significant change to this skill is recorded here.
|
|
4
4
|
|
|
5
|
+
## [1.26.1] - 2026-10-18
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
- F-072 (field run): the `SKILL.md` line that announces the docs site now reads `scripts/docs_site.py --root <project> --open` and says to use it to show the project state. Asked for the state, an agent had opened the site in its own client pane, where it renders blank, and improvised a local server; `--open` opens it in the user's browser, where it works offline.
|
|
9
|
+
|
|
10
|
+
## [1.26.0] - 2026-10-18
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- F-074: every Vision is born from an owner interview. Before any Vision text is written (project, feature, lens, and the devPNT M-VISION), the agent asks the owner six questions in order, re-asking an answer that has the wrong form: the problem as one concrete case, the benefit as a result for someone, the actors including who takes the initiative, a success signal with its starting value, the boundaries, and the known constraints with where each comes from. Then the owner approves a one- or two-sentence north star in their own words; without it no Vision is written, not even a draft. The blind check still tests that the rules hold; the approved north star shows they are the owner's. `vision.md` §The owner interview.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
- `elicitation.md`: the skip path never covers a Vision; the interview is a planned occasion like the round.
|
|
17
|
+
- Bootstrap no longer writes a Vision reconstructed by the agent: the installer seeds `ai_docs/vision/project_vision.md` as a stub awaiting the interview (an existing file is never overwritten).
|
|
18
|
+
- A Non-Goal now bounds scope. It rejects a proposal that pursues what it names; it is not a ban on behaviour that already exists and creates no obligation. A behaviour that must never happen is an Invariant or a constraint with its source.
|
|
19
|
+
- Vision templates ask for the north star in the owner's words with its approval, the problem as a case, the actor with the initiative, signals with starting values, and the source of every rule.
|
|
20
|
+
|
|
5
21
|
## [1.25.0] - 2026-10-18
|
|
6
22
|
|
|
7
23
|
### Added
|
package/README.md
CHANGED
|
@@ -49,7 +49,7 @@ Deliberately absent: any per-node coverage or completion state. `gaps:` says wha
|
|
|
49
49
|
- **Risk-proportional triage, measured in knowledge and never in files**: one claim row → propagating a fact already settled → a new knowledge unit (a source ingested, a node created or superseded, the hierarchy moved). Carrying one settled fact into eight documents is small; one claim that re-parents a node is not. On a live front, a new source or statement within an open unit's declared scope is an **ingestion step** of that unit — recorded on the ledger at once — while the rewrite of dependent documents, the registry and the full check run once, at a closure the practitioner calls. A **Write Triggers** table maps each knowledge event to exactly one destination.
|
|
50
50
|
- **Portable knowledge**: `export` bundles a subgraph together with the bytes its claims cite — a closure, not a selection, because a claim whose source cannot be reopened is model knowledge arriving by another route. `import` merges it into another project **additively**: it never overwrites a node and never deletes, and claims already present are recognised by id rather than by comparing text, since the same artifact cited at the same span mints the same id in every project. Knowledge crosses the project boundary; **authority does not** — an imported ruling arrives as `prov: IMPORTED`, keeps its original `basis:`, and cannot settle a local disagreement until you re-ratify it.
|
|
51
51
|
- **Several people, one project**: the workstream registry (`audit/handoff.md`) is **generated** from one file per open workstream, so two people opening or closing two workstreams on two branches edit two different files and their merge is clean. Row-per-workstream alone was not enough — a file-global `Date:` header defeats row-level ownership — so the header is derived from the sources and no writer touches it. The generated view can still conflict; that conflict is resolved by re-running `index`, never by hand, and `validate` refuses CLEAN until the file matches its sources. The append-only review log gets `merge=union` (a built-in driver, no per-clone configuration). It all works with no VCS at all: it is files and a generator.
|
|
52
|
-
- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone.
|
|
52
|
+
- **Vision-guided governance**: Standalone projects use `ai_docs/vision/`; Hybrid projects use devPNT `M-VISION` as the milestone north star. `DRAFT` informs, `APPROVED` binds, promotion is the user's alone. Every Vision, the M-VISION included, is written only after a six-question **owner interview** and your explicit approval of a one- or two-sentence north star in your own words — the agent never writes one alone.
|
|
53
53
|
- **Independent review, twice**: the design before it is implemented, the result before it is declared done — fresh-context subagent > one-shot run > a declared self-pass, 3 rounds max, one log line each, and a PASS is invalid on "found nothing".
|
|
54
54
|
- **Question discipline**: a real doubt is asked when it emerges, before its answer is written, with the pros and cons of each option; a choice whose pros clearly win is taken with the weighing written next to it. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks.
|
|
55
55
|
- **Verbatim request record**: every L3 starts `audit/requests/REQUEST_[topic].md` before the Vision Gate — the practitioner's own words and every later decision (answers, approvals, costs, rulings), append-only and redacted for secrets — so analyses cite what was asked instead of paraphrasing it, and reviews check owner statements against it.
|
|
@@ -89,7 +89,7 @@ Initialize a project:
|
|
|
89
89
|
kb-agentic-init
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
-
Run it inside a project to create `ai_docs/`, Vision
|
|
92
|
+
Run it inside a project to create `ai_docs/`, Vision stubs awaiting your interview, strategic docs, audit plan, and agent protocol files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`).
|
|
93
93
|
|
|
94
94
|
Installing or updating the npm package **wires the session-orientation hook
|
|
95
95
|
machine-wide** (user-level `~/.claude/settings.json`, Claude Code with Python):
|
package/gemini-extension.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kb-agentic-skill",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.26.1",
|
|
4
4
|
"description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
|
|
5
5
|
"author": "Antonio Pinto (https://github.com/Antoneeo)"
|
|
6
6
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@antoneeo/kb-agentic-skill",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.26.1",
|
|
4
4
|
"description": "Knowledge-Base & Document-First protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, signal distillation and optional devPNT integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude-code",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: kb-agentic
|
|
3
|
-
version: 1.
|
|
3
|
+
version: 1.26.1
|
|
4
4
|
description: Knowledge-Base & Document-First protocol with risk-proportional triage, Vision as a guide, Signal Distillation, a complete Standalone mode and optional symbiosis with devPNT. Use for user documentation, knowledge extraction, SOPs, research notes, decision logs, knowledge management — and for answering project questions from the claim ledger and topic graph.
|
|
5
5
|
author: Antonio Pinto (https://github.com/Antoneeo)
|
|
6
6
|
copyright: (c) 2026 Antonio Pinto
|
|
@@ -25,7 +25,7 @@ Support files in the skill directory:
|
|
|
25
25
|
- `dispatch.md`: opt-in subagent execution of an approved plan, plus the family-wide delegation boundary (what may be delegated at all) — that part applies at any level.
|
|
26
26
|
- `routing.md`: which lens owns this unit of work. Read ONLY when a sibling lens skill is installed alongside this one; a single-lens install never reads it.
|
|
27
27
|
- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`, `stale` (spine staleness plus `## claims` -- the time cycle's consolidated view), plus `remind` — the opt-in per-turn one-line reminder, ENFORCEMENT §4). Keep the entry point, `scripts/sdlc_core.py` and `scripts/knowledge.py` together; the last supplies common memory and KB integrity.
|
|
28
|
-
- `scripts/docs_site.py --root <project
|
|
28
|
+
- `scripts/docs_site.py --root <project> --open`: opens in the user's browser a read-only site of what the agent reads; use it to show the project state.
|
|
29
29
|
- `ENFORCEMENT.md`: optional setup for CI and hooks.
|
|
30
30
|
|
|
31
31
|
Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
|
|
@@ -97,7 +97,7 @@ Triage decides IF documentation is due; this table decides WHICH document each e
|
|
|
97
97
|
| `audit/reviews/REVIEW_LOG.md` | Every completed review — recorded in log. | 3 / 5 |
|
|
98
98
|
| ADR / Decision Log — `architecture/` or devPNT DB | A strategic decision was taken (pattern, policy, structural change): record before DONE. | 5 |
|
|
99
99
|
| `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the knowledge catalog actually changed. | 1 / 5 |
|
|
100
|
-
| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap as `Status: DRAFT
|
|
100
|
+
| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap writes each as a **stub** awaiting the owner interview (`Status: DRAFT`) — never a Vision reconstructed by the agent. The Vision is written only after the owner interview and its approved north star (`vision.md` §The owner interview); promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
|
|
101
101
|
| `topics/<slug>.md` | A placement verdict creates it (MISSING/INADEQUATE-child, `taxonomy.md`); reconciliation updates its claim rows. One node per topic — a similar-but-distinct concept is a sibling with `related:` + a written distinction, never a merge and never a duplicate. Merged/renamed nodes become tombstones (`status: SUPERSEDED` + `redirect_to:`), never deleted. | 4 |
|
|
102
102
|
| a KB bundle (`export`) | Knowledge must leave this project. Export is L1 — it writes nothing into the corpus. **Importing one is L3**: a source enters the corpus and nodes are created, and a bundle is external input, so never L1 whatever its size (`portability.md`). | — |
|
|
103
103
|
| `corpus/given/*` + sidecar | A source arrives: it becomes a content-addressed artifact with a sidecar carrying digest/date/`supersedes:`. A text source is copied verbatim. A non-text source yields its stored canonical extraction — copied **beside** the original when that is small enough to keep, or **instead of it** on a large binary corpus, where the original stays where it lives and is recorded as `original_path:`/`original_sha256:` (`distillation.md` §1, which owns this rule). Never edited after ingest — the digest check on whatever `given/` holds is what enforces it. | 4 |
|
|
@@ -125,12 +125,13 @@ Use this mode when `devpnt_*` tools are available and point at the current proje
|
|
|
125
125
|
### 1. Audit and Alignment
|
|
126
126
|
- Read `ai_docs/audit/handoff.md` (workstream registry) to see active topics.
|
|
127
127
|
- Read `ai_docs/README.md`, `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md` (the guide router) before exploring notes. The router is a mandatory read, not an optional one: it is the only orientation step that tells you a guide already governs the work you are about to do.
|
|
128
|
-
- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/`
|
|
128
|
+
- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/` stubs awaiting the owner interview, `strategic/` docs, and `audit/audit_plan.md`, then run `sdlc_check.py index`.
|
|
129
129
|
|
|
130
130
|
### 2. Vision Gate
|
|
131
131
|
- Read `project_vision.md`, `roadmap.md`, `principles.md` (or devPNT `M-VISION`).
|
|
132
132
|
- Compare them with the request as recorded in `audit/requests/REQUEST_[topic].md`, not with a paraphrase of it.
|
|
133
133
|
- Verify request aligns with expected benefits, user goals, and success signals.
|
|
134
|
+
- Writing or amending a Vision starts with the owner interview (`vision.md` §The owner interview): the north star is approved in the owner's words before any Vision text exists; there is no skip path.
|
|
134
135
|
|
|
135
136
|
### 3. Request Analysis & Taxonomy Pass
|
|
136
137
|
|
|
@@ -10,10 +10,20 @@ Skip path: if the spec is already complete — an approved Vision or explicit
|
|
|
10
10
|
user requirements already answer goal, scope, and constraints — skip the
|
|
11
11
|
round and add a one-line note in the analysis stating why it was skipped.
|
|
12
12
|
Do not run the round as a formality when the answers are already on record.
|
|
13
|
+
The skip path never covers a Vision (next paragraph).
|
|
14
|
+
|
|
15
|
+
Vision path: when the unit writes or amends a Vision — any kind, the M-VISION
|
|
16
|
+
included — the owner interview in `vision.md` §The owner interview runs instead
|
|
17
|
+
of this round for the Vision's own content, and it has **no skip path**: one
|
|
18
|
+
sentence from the user plus a spike never makes a Vision's spec complete. The
|
|
19
|
+
round then covers only what the interview did not (the unit's own scope and
|
|
20
|
+
acceptance), deriving from the interview's answers. The interview is a planned
|
|
21
|
+
occasion like the round (§Ask before the write): its questions go in one numbered
|
|
22
|
+
set, and only an answer in the wrong form is asked again.
|
|
13
23
|
|
|
14
24
|
Unattended path: when the user is not reachable (a scheduled or autonomous run,
|
|
15
|
-
and a bootstrap Vision is
|
|
16
|
-
apply on a project's first L3) and a real doubt remains, do not stall and do not
|
|
25
|
+
and a bootstrap Vision is a stub awaiting the owner interview, so the skip
|
|
26
|
+
path above cannot apply on a project's first L3) and a real doubt remains, do not stall and do not
|
|
17
27
|
invent consensus. Write it as a **declared assumption** (§Ask before the write)
|
|
18
28
|
in the artifact it touches. At L3, mark the ANALYSIS `BLOCKED on the user` and
|
|
19
29
|
stop before implementation; below L3, proceed and list the assumption in the
|
|
@@ -24,9 +34,10 @@ design is not.
|
|
|
24
34
|
|
|
25
35
|
A doubt kept silent is decided by the agent alone and reaches the documents
|
|
26
36
|
looking settled; a useless question wastes the practitioner's attention. This
|
|
27
|
-
section rules on both. The process *plans* questions in
|
|
28
|
-
below,
|
|
29
|
-
a
|
|
37
|
+
section rules on both. The process *plans* questions in three places — the round
|
|
38
|
+
below, the owner interview for a Vision (`vision.md` §The owner interview), and the
|
|
39
|
+
Capture Moment sweep at a user-signed closing (`SKILL.md`) — each a planned
|
|
40
|
+
occasion that keeps its own form.
|
|
30
41
|
|
|
31
42
|
### When a doubt emerges
|
|
32
43
|
|
|
@@ -103,18 +103,30 @@ the first draft — the properties that make a rule survive a motivated reader a
|
|
|
103
103
|
cheap to apply while writing and expensive to retrofit. `vision.md` §6 is the
|
|
104
104
|
blind check that gates promotion to APPROVED.
|
|
105
105
|
|
|
106
|
+
**No section below is written before the owner interview** (`vision.md` §The owner
|
|
107
|
+
interview) and its approved north star. Until then — at bootstrap, or for an owner
|
|
108
|
+
not yet reached — the file is this stub, and nothing traces to it:
|
|
109
|
+
|
|
110
|
+
```markdown
|
|
111
|
+
# Project Vision
|
|
112
|
+
Status: DRAFT
|
|
113
|
+
<!-- STUB: awaiting the owner interview (vision.md §The owner interview). Not a
|
|
114
|
+
Vision: no artifact traces to it. What the agent observed is in strategic/. -->
|
|
115
|
+
```
|
|
116
|
+
|
|
106
117
|
Sections below marked **[gate]** are load-bearing for that ruling; the others are
|
|
107
118
|
orientation for humans. Keep the human ones — just know which is which.
|
|
108
119
|
|
|
109
120
|
```markdown
|
|
110
121
|
# Project Vision
|
|
111
122
|
Status: DRAFT
|
|
112
|
-
<!-- Status: DRAFT (
|
|
123
|
+
<!-- Status: DRAFT (written from the owner interview, NOT yet a gating authority)
|
|
113
124
|
or APPROVED (by <who>, <date>) — only after the user's explicit confirmation
|
|
114
125
|
AND the blind check in vision.md §6. -->
|
|
115
126
|
|
|
116
127
|
## North Star
|
|
117
|
-
<!-- [gate, partly]
|
|
128
|
+
<!-- [gate, partly] One or two sentences IN THE OWNER'S WORDS, approved before any
|
|
129
|
+
other section (Gate 1): (approved: REQUEST_[topic].md#R<n>). The BENEFIT to be obtained — what the actor gets, never the
|
|
118
130
|
mechanism, and never by comparison to another product (a comparative
|
|
119
131
|
definition rots silently when the comparison target moves). Concrete enough
|
|
120
132
|
that an obstacle to it is recognizable: that is what makes every Non-Goal
|
|
@@ -123,11 +135,15 @@ Status: DRAFT
|
|
|
123
135
|
scale levels. Routing the reader to another file breaks the cold-read
|
|
124
136
|
premise. -->
|
|
125
137
|
## Core Problem
|
|
126
|
-
<!--
|
|
127
|
-
|
|
138
|
+
<!-- Interview question 1: ONE concrete case that today does not get the expected
|
|
139
|
+
result, with its example — never a missing feature. Cite the answer
|
|
140
|
+
(REQUEST_[topic].md#R<n>). Human orientation: carries no gate weight unless
|
|
141
|
+
the admission test names it. -->
|
|
128
142
|
## Actors
|
|
129
143
|
<!-- [gate] the cast this product serves. One light line per actor:
|
|
130
144
|
**Role** — primary goal; good UX = what a good experience means to them.
|
|
145
|
+
Interview question 3: who receives the benefit, who acts, and who has the
|
|
146
|
+
INITIATIVE — an actor that acts unprompted is named here, or it goes missing.
|
|
131
147
|
The "good UX =" clauses are admissible work, not decoration — say so in the
|
|
132
148
|
admission test. Define each actor ONCE here; use-cases (Standalone) / D-UC
|
|
133
149
|
(Hybrid) reference them by role and never re-describe them (anti-DRY).
|
|
@@ -144,7 +160,14 @@ Status: DRAFT
|
|
|
144
160
|
with BOTH branches answered, plus an anti-laundering clause naming the
|
|
145
161
|
re-descriptions you expect. Omit the section if the product has none. -->
|
|
146
162
|
## Non-Goals
|
|
147
|
-
<!-- [gate — the REJECT side
|
|
163
|
+
<!-- [gate — the REJECT side, with the Invariants]
|
|
164
|
+
A Non-Goal bounds SCOPE: it rejects a proposal that pursues what it names; it
|
|
165
|
+
never bans a behaviour the product already has and never creates an
|
|
166
|
+
obligation (obligations come from the North Star and the Success Signals). A
|
|
167
|
+
behaviour that must never happen is an Invariant, with its provenance.
|
|
168
|
+
PROVENANCE on every rule, at the end of its bullet: (source: owner
|
|
169
|
+
REQUEST_[topic].md#R<n> | higher Vision: "quoted line" | inference confirmed
|
|
170
|
+
REQUEST_[topic].md#R<n>). An unconfirmed author inference is not a rule.
|
|
148
171
|
Derive every rule by the deletion test: remove it — if the benefit is still
|
|
149
172
|
reachable, the rule does not belong (it spends a degree of freedom on
|
|
150
173
|
nothing); if not, keep it and name the obstacle it removes. Constraints
|
|
@@ -164,7 +187,7 @@ Status: DRAFT
|
|
|
164
187
|
clause. State the default for anything unreached, per path. -->
|
|
165
188
|
## Success Signals
|
|
166
189
|
<!-- [gate] Each checkable against a NAMED artifact or command by someone who was
|
|
167
|
-
not here. Not "we are the best" — a file, a command, a battery, and what the
|
|
190
|
+
not here, with its STARTING VALUE (interview question 4). Not "we are the best" — a file, a command, a battery, and what the
|
|
168
191
|
result must be. -->
|
|
169
192
|
## Where the rest lives
|
|
170
193
|
<!-- Pointers, so an absence reads as intentional rather than as a gap. Competitive
|
|
@@ -197,16 +220,32 @@ Only for features spanning multiple ANALYSIS documents or multiple milestones: o
|
|
|
197
220
|
```markdown
|
|
198
221
|
# Feature Vision: [Name]
|
|
199
222
|
|
|
223
|
+
<!-- Written only after the owner interview (vision.md §The owner interview). Each
|
|
224
|
+
section cites the answer it comes from: REQUEST_[topic].md#R<n>. -->
|
|
225
|
+
## North Star
|
|
226
|
+
<!-- One or two sentences in the owner's words, explicitly approved before any
|
|
227
|
+
other section (Gate 1): (approved: REQUEST_[topic].md#R<n>). -->
|
|
200
228
|
## Problem
|
|
229
|
+
<!-- One concrete case that today does not get the expected result, with its
|
|
230
|
+
example — not a missing feature. -->
|
|
201
231
|
## Expected Benefit
|
|
232
|
+
<!-- What who obtains once solved: a result, not a function. -->
|
|
202
233
|
## Actors
|
|
203
234
|
<!-- the cast this feature serves — usually a subset/refinement of the project
|
|
204
235
|
Actors, or a distinct feature-local cast for internal-tooling work. One light
|
|
205
236
|
line each: **Role** — primary goal; good UX = what good feels like.
|
|
237
|
+
Name who receives the benefit, who acts, and who has the initiative.
|
|
206
238
|
Referenced by the use-cases, not re-described in them. -->
|
|
207
239
|
## Success Signals
|
|
240
|
+
<!-- Observable, each with its starting value. -->
|
|
208
241
|
## Non-Goals / Out of Scope
|
|
242
|
+
<!-- Scope this feature does not pursue. Not a ban on existing behaviour, and no
|
|
243
|
+
obligation: those come from the Benefit and the Signals. -->
|
|
209
244
|
## Related Constraints and Principles
|
|
245
|
+
<!-- Each with its provenance: (source: owner REQUEST_[topic].md#R<n> | higher
|
|
246
|
+
Vision: "quoted line" | inference confirmed REQUEST_[topic].md#R<n>). A
|
|
247
|
+
constraint imported from a higher Vision is asked about, never assumed to
|
|
248
|
+
apply here. -->
|
|
210
249
|
```
|
|
211
250
|
|
|
212
251
|
## ai_docs/audit/requests/REQUEST_[topic].md
|
|
@@ -47,14 +47,67 @@ Four consequences, each operational:
|
|
|
47
47
|
|
|
48
48
|
Extracting the benefit from a discussion is real work: a discourse arrives with
|
|
49
49
|
solutions, preferences and constraints tangled together, and the Vision is the
|
|
50
|
-
distilled benefit only. The
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
actor obtains.
|
|
50
|
+
distilled benefit only. The owner interview below asks for it — and a mechanism
|
|
51
|
+
("a dashboard") is not an acceptable answer to a benefit question ("never lose
|
|
52
|
+
the thread"); ask again until the answer names what the actor obtains.
|
|
54
53
|
|
|
55
54
|
The deletion test decides **which** rules exist. Everything below decides **how**
|
|
56
55
|
to write a rule so it holds once you know it must exist.
|
|
57
56
|
|
|
57
|
+
## The owner interview (before any Vision text)
|
|
58
|
+
|
|
59
|
+
A Vision is the **owner's** statement of what is to be obtained. Nothing in this
|
|
60
|
+
file after this section can detect a Vision the author wrote alone: the blind
|
|
61
|
+
check (§6) tests whether the rules survive a hostile reader, never whether they
|
|
62
|
+
are the owner's. So every Vision is born from an interview of the owner, and its
|
|
63
|
+
north star is approved **before** a line of it is drafted.
|
|
64
|
+
|
|
65
|
+
**Scope — every Vision, in every mode:** `project_vision.md`, a feature
|
|
66
|
+
`VISION_*.md`, a lens Vision (course, marketing), and the devPNT M-VISION in
|
|
67
|
+
Hybrid; also an ANALYSIS `## Feature Vision` that states a benefit no existing
|
|
68
|
+
Vision names (one that cites an approved Vision's benefit is alignment, not a
|
|
69
|
+
Vision). An amendment re-runs the questions whose answers it changes, and Gate 1
|
|
70
|
+
again when the north star changes. **There is no skip path**: one sentence from
|
|
71
|
+
the user plus a spike is not a complete spec — that exact shortcut produced a
|
|
72
|
+
Vision with an imported prohibition, no north star and a missing actor, and four
|
|
73
|
+
downstream artifacts built on it (field case, 2026-10). A reply already on record
|
|
74
|
+
in the owner's words is read back for confirmation, never re-asked as an open
|
|
75
|
+
question; an answer the author derived (from a spike, the code, another Vision)
|
|
76
|
+
is never an answer — it is a proposal the owner confirms or rejects.
|
|
77
|
+
|
|
78
|
+
**The questions, in this order.** Each is repeated until its answer has the form
|
|
79
|
+
stated; the wrong form is named so it can be recognized and asked again.
|
|
80
|
+
|
|
81
|
+
| # | Question | Right form | Wrong form — ask again |
|
|
82
|
+
|---|---|---|---|
|
|
83
|
+
| 1 | **Problem** — which concrete case today does not get the expected result? | one real case, with an example | a missing feature ("there is no drawing tool") |
|
|
84
|
+
| 2 | **Benefit** — once solved, who obtains what? | a result for a named actor | a function or mechanism ("a renderer") |
|
|
85
|
+
| 3 | **Actors** — who receives the benefit, who acts, who has the initiative? | all three named, initiative included | only the one who asks — the actor who acts unprompted goes missing |
|
|
86
|
+
| 4 | **Success** — what observable signal shows the benefit arrived? | a signal with its starting value | a feeling, or a signal with no baseline |
|
|
87
|
+
| 5 | **Boundaries** — what does this NOT pursue? | scope excluded from this work | a ban on behaviour ("X must never happen") — that is a constraint (6) or an obligation (2, 4) |
|
|
88
|
+
| 6 | **Known constraints** — each with its provenance: owner, a quoted line of a higher Vision, or author inference | every constraint sourced; every inference asked here | a constraint written in silently, or imported from a higher Vision without asking whether it applies here |
|
|
89
|
+
|
|
90
|
+
A **Non-Goal bounds scope**: it rejects a proposal that pursues what it names; it
|
|
91
|
+
is not a ban on behaviour that already exists, and it creates no obligation.
|
|
92
|
+
Obligations come from the Benefit and the Success Signals.
|
|
93
|
+
|
|
94
|
+
**Gate 1 — north star.** One or two sentences, in the owner's words, explicitly
|
|
95
|
+
approved by the owner. The author may compose a wording from the answers; the
|
|
96
|
+
approval is of that exact text, recorded verbatim in the request record
|
|
97
|
+
(`audit/requests/REQUEST_[unit].md`; a Vision written outside any unit, such as
|
|
98
|
+
the project Vision after bootstrap, records its interview in
|
|
99
|
+
`audit/requests/REQUEST_project_vision.md`). **Without it no Vision text is written** —
|
|
100
|
+
not a DRAFT, not a reconstruction: bootstrap writes a stub awaiting the
|
|
101
|
+
interview, and what the agent observed goes to `strategic/`.
|
|
102
|
+
Unattended, the unit is `BLOCKED on the user` (`elicitation.md` Unattended path).
|
|
103
|
+
|
|
104
|
+
**Gate 2 — the full Vision**, written from the answers. Every section traces to
|
|
105
|
+
an answer or a stated provenance (`REQUEST_[unit].md#R<n>`); every rule carries
|
|
106
|
+
its provenance; an author inference the owner did not confirm is not in it. The
|
|
107
|
+
blind check (§6) verifies that it holds; the approved north star verifies that it
|
|
108
|
+
is the owner's. Promotion to APPROVED still needs the owner's explicit
|
|
109
|
+
confirmation — Gate 2 is that confirmation, given on the written text.
|
|
110
|
+
|
|
58
111
|
## 0. The one-line test
|
|
59
112
|
|
|
60
113
|
> Could a reader who has never seen this project rule ACCEPT or REJECT on a
|
|
@@ -138,7 +191,14 @@ rule that survived and the same rule leaking.
|
|
|
138
191
|
This is the most common structural failure and it is invisible from the inside.
|
|
139
192
|
|
|
140
193
|
- **A Goal cannot reject anything.** If the admission test says "advances a Goal
|
|
141
|
-
and violates no Non-Goal", then rejection power lives *only* in the Non-Goals
|
|
194
|
+
and violates no Non-Goal", then rejection power lives *only* in the Non-Goals
|
|
195
|
+
(and the Invariants, where the Vision has them).
|
|
196
|
+
- **A Non-Goal rejects scope, not behaviour.** It turns away a proposal that
|
|
197
|
+
pursues what it names; it never forbids a behaviour the product already has, and
|
|
198
|
+
it never creates an obligation — obligations come from the Benefit and the
|
|
199
|
+
Success Signals. A behaviour the product must never have is an Invariant, or a
|
|
200
|
+
constraint with its provenance (§The owner interview, question 6). Written as a
|
|
201
|
+
Non-Goal, it reads as a ban the owner never stated.
|
|
142
202
|
A Goal that says "scale cost to risk in both directions" cannot stop cost
|
|
143
203
|
inflation — you need a prohibition for that.
|
|
144
204
|
- **A prohibition scoped to one rung of your own scale protects only that rung.**
|
|
@@ -204,7 +264,10 @@ it.
|
|
|
204
264
|
## 6. The blind check (procedure)
|
|
205
265
|
|
|
206
266
|
Run this **before promoting any Vision to APPROVED, and before any amendment of an
|
|
207
|
-
approved one**.
|
|
267
|
+
approved one**. It runs on a Vision that already passed Gate 1 (§The owner
|
|
268
|
+
interview): it tests whether the rules hold against a hostile reader, and it
|
|
269
|
+
cannot see whether they are the owner's — a Vision the author wrote alone passes
|
|
270
|
+
it cleanly. Not for DRAFT edits — promotion is when authority is granted, and
|
|
208
271
|
it is rare, so the cost lands where it buys most.
|
|
209
272
|
|
|
210
273
|
1. **Give the reviewer the document text and nothing else.** Not a path — the
|