@antoneeo/kb-agentic-skill 1.4.0 → 1.4.3
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
CHANGED
|
@@ -2,6 +2,47 @@
|
|
|
2
2
|
|
|
3
3
|
Every significant change to this skill is recorded here.
|
|
4
4
|
|
|
5
|
+
## [1.4.3] - 2026-08-05
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
- **Shared-spine sync: Interface Contract rename (inert in this lens).** The shared `review.md`
|
|
9
|
+
Interaction Contract clause is renamed to **Interface Contract** and gains the code lens's
|
|
10
|
+
evolved checks (responsibility-level flow, solution-leakage, universal feedback); the
|
|
11
|
+
`interaction_contract` capability key is unchanged. The kb lens defines no such template
|
|
12
|
+
section, so the clause stays inert here — spine parity only.
|
|
13
|
+
|
|
14
|
+
## [1.4.2] - 2026-08-05
|
|
15
|
+
|
|
16
|
+
### Fixed
|
|
17
|
+
- **Registry recognition hard-coded to one entry point.** The workstream-registry
|
|
18
|
+
header is written with `entry_script()` but was recognized as "already ours" only
|
|
19
|
+
by the literal `sdlc_check.py`; recognition now matches the generated marker for
|
|
20
|
+
any family entry point — relevant on mixed-lens projects.
|
|
21
|
+
- **Spine battery isolation.** `test_merge_safety` now pins its docs root in
|
|
22
|
+
`setUpModule` instead of inheriting whichever overlay was imported first by
|
|
23
|
+
unittest discovery.
|
|
24
|
+
|
|
25
|
+
### Changed
|
|
26
|
+
- **Shared-spine sync with code 1.22.0 (Interaction Contract, F-032).** The shared
|
|
27
|
+
`review.md` gains the Interaction Contract conformance clause and the shared core
|
|
28
|
+
registers the `interaction_contract` capability — both **inert in this lens**: the
|
|
29
|
+
clause is keyed on the lens whose template defines the section (the code lens),
|
|
30
|
+
kb claims no such capability, and no kb workflow gains any new step or artifact.
|
|
31
|
+
|
|
32
|
+
## [1.4.1] - 2026-08-03
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
- **`version:` in every `SKILL.md` frontmatter.** An installed skill carries no
|
|
36
|
+
`package.json` and no `gemini-extension.json` — only doctrine and scripts — so nothing
|
|
37
|
+
in it said which build it was. Answering "is that fix in your copy?" took `npm view`
|
|
38
|
+
plus a shasum comparison; from a user's side it was unanswerable. Now the first thing
|
|
39
|
+
in the operating contract says it.
|
|
40
|
+
- **A battery invariant asserting every bump point agrees** (`SKILL.md` ↔ `package.json`
|
|
41
|
+
↔ `gemini-extension.json`). A hand-maintained version string rots, and this repository
|
|
42
|
+
has the scar: the third bump point was skipped for two whole releases with nothing to
|
|
43
|
+
catch it. The fourth arrives with its guard attached, and `GUIDE_release.md` step 1
|
|
44
|
+
now says FOUR.
|
|
45
|
+
|
|
5
46
|
## [1.4.0] - 2026-08-03
|
|
6
47
|
|
|
7
48
|
F-028 — several people on one project. `templates.md` had claimed the workstream
|
package/gemini-extension.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "kb-agentic-skill",
|
|
3
|
-
"version": "1.4.
|
|
4
|
-
"description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
|
|
5
|
-
"author": "Antonio Pinto (https://github.com/Antoneeo)"
|
|
6
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "kb-agentic-skill",
|
|
3
|
+
"version": "1.4.3",
|
|
4
|
+
"description": "Knowledge-Base & Document-First protocol with risk triage, Vision governance, signal distillation and optional devPNT integration.",
|
|
5
|
+
"author": "Antonio Pinto (https://github.com/Antoneeo)"
|
|
6
|
+
}
|
package/package.json
CHANGED
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@antoneeo/kb-agentic-skill",
|
|
3
|
-
"version": "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
|
-
"keywords": [
|
|
6
|
-
"claude-code",
|
|
7
|
-
"claude-skill",
|
|
8
|
-
"gemini-cli",
|
|
9
|
-
"skill",
|
|
10
|
-
"knowledge-base",
|
|
11
|
-
"documentation",
|
|
12
|
-
"ai-agent"
|
|
13
|
-
],
|
|
14
|
-
"author": "Antonio Pinto (https://github.com/Antoneeo)",
|
|
15
|
-
"license": "MIT",
|
|
16
|
-
"publishConfig": {
|
|
17
|
-
"access": "public"
|
|
18
|
-
},
|
|
19
|
-
"bin": {
|
|
20
|
-
"kb-agentic-init": "scripts/init.js",
|
|
21
|
-
"kb-agentic-install-skill": "scripts/postinstall.js"
|
|
22
|
-
},
|
|
23
|
-
"scripts": {
|
|
24
|
-
"postinstall": "node scripts/postinstall.js",
|
|
25
|
-
"preuninstall": "node scripts/preuninstall.js"
|
|
26
|
-
},
|
|
27
|
-
"files": [
|
|
28
|
-
"skills/kb-agentic-skill/SKILL.md",
|
|
29
|
-
"skills/kb-agentic-skill/templates.md",
|
|
30
|
-
"skills/kb-agentic-skill/taxonomy.md",
|
|
31
|
-
"skills/kb-agentic-skill/guides.md",
|
|
32
|
-
"skills/kb-agentic-skill/vision.md",
|
|
33
|
-
"skills/kb-agentic-skill/distillation.md",
|
|
34
|
-
"skills/kb-agentic-skill/reconciliation.md",
|
|
35
|
-
"skills/kb-agentic-skill/elicitation.md",
|
|
36
|
-
"skills/kb-agentic-skill/review.md",
|
|
37
|
-
"skills/kb-agentic-skill/dispatch.md",
|
|
38
|
-
"skills/kb-agentic-skill/routing.md",
|
|
39
|
-
"skills/kb-agentic-skill/portability.md",
|
|
40
|
-
"skills/kb-agentic-skill/ENFORCEMENT.md",
|
|
41
|
-
"skills/kb-agentic-skill/scripts/sdlc_check.py",
|
|
42
|
-
"skills/kb-agentic-skill/scripts/sdlc_core.py",
|
|
43
|
-
"gemini-extension.json",
|
|
44
|
-
"README.md",
|
|
45
|
-
"CHANGELOG.md",
|
|
46
|
-
"scripts/lib.js",
|
|
47
|
-
"scripts/init.js",
|
|
48
|
-
"scripts/postinstall.js",
|
|
49
|
-
"scripts/preuninstall.js"
|
|
50
|
-
]
|
|
51
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@antoneeo/kb-agentic-skill",
|
|
3
|
+
"version": "1.4.3",
|
|
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
|
+
"keywords": [
|
|
6
|
+
"claude-code",
|
|
7
|
+
"claude-skill",
|
|
8
|
+
"gemini-cli",
|
|
9
|
+
"skill",
|
|
10
|
+
"knowledge-base",
|
|
11
|
+
"documentation",
|
|
12
|
+
"ai-agent"
|
|
13
|
+
],
|
|
14
|
+
"author": "Antonio Pinto (https://github.com/Antoneeo)",
|
|
15
|
+
"license": "MIT",
|
|
16
|
+
"publishConfig": {
|
|
17
|
+
"access": "public"
|
|
18
|
+
},
|
|
19
|
+
"bin": {
|
|
20
|
+
"kb-agentic-init": "scripts/init.js",
|
|
21
|
+
"kb-agentic-install-skill": "scripts/postinstall.js"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"postinstall": "node scripts/postinstall.js",
|
|
25
|
+
"preuninstall": "node scripts/preuninstall.js"
|
|
26
|
+
},
|
|
27
|
+
"files": [
|
|
28
|
+
"skills/kb-agentic-skill/SKILL.md",
|
|
29
|
+
"skills/kb-agentic-skill/templates.md",
|
|
30
|
+
"skills/kb-agentic-skill/taxonomy.md",
|
|
31
|
+
"skills/kb-agentic-skill/guides.md",
|
|
32
|
+
"skills/kb-agentic-skill/vision.md",
|
|
33
|
+
"skills/kb-agentic-skill/distillation.md",
|
|
34
|
+
"skills/kb-agentic-skill/reconciliation.md",
|
|
35
|
+
"skills/kb-agentic-skill/elicitation.md",
|
|
36
|
+
"skills/kb-agentic-skill/review.md",
|
|
37
|
+
"skills/kb-agentic-skill/dispatch.md",
|
|
38
|
+
"skills/kb-agentic-skill/routing.md",
|
|
39
|
+
"skills/kb-agentic-skill/portability.md",
|
|
40
|
+
"skills/kb-agentic-skill/ENFORCEMENT.md",
|
|
41
|
+
"skills/kb-agentic-skill/scripts/sdlc_check.py",
|
|
42
|
+
"skills/kb-agentic-skill/scripts/sdlc_core.py",
|
|
43
|
+
"gemini-extension.json",
|
|
44
|
+
"README.md",
|
|
45
|
+
"CHANGELOG.md",
|
|
46
|
+
"scripts/lib.js",
|
|
47
|
+
"scripts/init.js",
|
|
48
|
+
"scripts/postinstall.js",
|
|
49
|
+
"scripts/preuninstall.js"
|
|
50
|
+
]
|
|
51
|
+
}
|
|
@@ -1,147 +1,148 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: kb-agentic
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- `
|
|
17
|
-
- `
|
|
18
|
-
- `
|
|
19
|
-
- `
|
|
20
|
-
- `
|
|
21
|
-
- `
|
|
22
|
-
- `
|
|
23
|
-
- `
|
|
24
|
-
- `
|
|
25
|
-
- `
|
|
26
|
-
- `
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
- **
|
|
34
|
-
- **
|
|
35
|
-
- **
|
|
36
|
-
- **
|
|
37
|
-
- **
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
| **
|
|
49
|
-
| **
|
|
50
|
-
| **
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
-
|
|
62
|
-
-
|
|
63
|
-
-
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| `solutions/
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `audit/
|
|
79
|
-
| `audit/
|
|
80
|
-
| `audit/
|
|
81
|
-
| `audit/
|
|
82
|
-
| `
|
|
83
|
-
| `reference/GUIDE_[topic].md` (`source_kind:
|
|
84
|
-
| `
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
|
|
|
90
|
-
|
|
|
91
|
-
| `corpus/
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
- Read `ai_docs/
|
|
112
|
-
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
- Run
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
-
|
|
127
|
-
-
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
-
|
|
134
|
-
-
|
|
135
|
-
-
|
|
136
|
-
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
- **
|
|
142
|
-
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
- `scripts/sdlc_check.py
|
|
147
|
-
- `scripts/sdlc_check.py
|
|
1
|
+
---
|
|
2
|
+
name: kb-agentic
|
|
3
|
+
version: 1.4.3
|
|
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 and knowledge management.
|
|
5
|
+
author: Antonio Pinto (https://github.com/Antoneeo)
|
|
6
|
+
copyright: (c) 2026 Antonio Pinto
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# KB Agentic
|
|
10
|
+
|
|
11
|
+
**Why this skill exists:** to prevent *knowledge degradation and myopia* — acting from partial understanding, where new information contradicts un-indexed notes and hard-won knowledge evaporates between sessions. Triage, the Vision Gate, signal distillation, the documentation lifecycle, and operative guide routers are all one defense against that.
|
|
12
|
+
|
|
13
|
+
This skill guides knowledge management and documentation with a Document-First process proportional to risk. It works fully even without devPNT. When devPNT is available and configured for the current project, the skill works in symbiosis with its governance: M-VISION, Master Plan, Action Plan and versioned artifacts become the authoritative frame for milestones and knowledge nodes.
|
|
14
|
+
|
|
15
|
+
Support files in the skill directory:
|
|
16
|
+
- `templates.md`: templates for Vision, Knowledge ANALYSIS, Research SPIKE, SOP GUIDE, audit plan, and handoff.
|
|
17
|
+
- `portability.md`: carrying knowledge between projects — what a bundle is, why export is a closure rather than a selection, and the rule that knowledge crosses a project boundary while authority does not (`prov: IMPORTED`). Read before `export`/`import`.
|
|
18
|
+
- `taxonomy.md`: placing a claim in the topic graph — descent over the generated index, the five verdicts (EXISTS / INADEQUATE / MISSING / GENERALIZES / UNPLACED), the sibling rule, guarded re-parenting, canonicalization. Run at L3 before drafting.
|
|
19
|
+
- `guides.md`: pipeline for distilling user-provided indications into `ai_docs/reference/GUIDE_[topic].md`.
|
|
20
|
+
- `vision.md`: how to write a Vision a cold reviewer can actually apply — the properties that make a rule hold, the minimum operable sections, and the blind check.
|
|
21
|
+
- `distillation.md`: from a source to claim rows — intake (content-addressed originals, stored canonical extraction, every provenance a real file), the claim table, extraction discipline, signal rules (symbiosis with `distill`).
|
|
22
|
+
- `reconciliation.md`: what happens when two claims meet — five outcomes, detect-and-hold (the machine never decides), rulings with mandatory `basis:`, the claim state machine, the batched escalation form.
|
|
23
|
+
- `review.md`: the review discipline — when a review is due, how to request one, how to receive findings, how to review.
|
|
24
|
+
- `dispatch.md`: opt-in subagent execution of an approved plan.
|
|
25
|
+
- `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.
|
|
26
|
+
- `scripts/sdlc_check.py` + `scripts/sdlc_core.py`: the mechanical validator for the docs root (`check`, `validate`, `index`, `stale`, `mark`, `gate`, `plan`, `orient`, `migrate`, and the knowledge overlay: `graph`, `corpus`, `claim-id`, `anchor`, `export`, `import`). Two files: the core is the family's shared spine; the entry point IS the knowledge overlay — the claim ledger and topic-graph checks live inside it, so the core alone runs none of them. Copy both, or neither.
|
|
27
|
+
- `ENFORCEMENT.md`: optional setup for CI and hooks.
|
|
28
|
+
|
|
29
|
+
Read these files only when needed. `SKILL.md` is the operating contract; the support files are progressive resources.
|
|
30
|
+
|
|
31
|
+
## Knowledge Values
|
|
32
|
+
|
|
33
|
+
- **Understand before writing/updating:** do not modify or create knowledge documents without checking root cause, user constraints, and existing notes — trust the primary sources and existing guides, not memory.
|
|
34
|
+
- **Apply DRY and Single Source of Truth:** do not duplicate knowledge across files; extend existing notes (`ANALYSIS_[topic].md` or `GUIDE_[topic].md`).
|
|
35
|
+
- **Signal & Distillation:** eliminate fluff, filler, and speculative statements; keep deterministic facts, constraints, decisions, and clear SOP steps (symbiosis with `distill`).
|
|
36
|
+
- **Lifecycle & Freshness:** mark superseded knowledge (`status: SUPERSEDED` or `DEPRECATED`) so outdated information does not cause hallucination.
|
|
37
|
+
- **Protect the Vision & User Style:** align all knowledge work with user strategic goals, operational preferences, and expected outcomes.
|
|
38
|
+
- **Map-First Navigation:** rely on `ai_docs/README.md`, `INDEX.md`, and `reference/INDEX.md` router for targeted retrieval before creating new documents.
|
|
39
|
+
|
|
40
|
+
## Rule Zero: Triage
|
|
41
|
+
|
|
42
|
+
Always classify the request before choosing the process. Declare the chosen level to the user when you start operational work.
|
|
43
|
+
|
|
44
|
+
**Declare the level WITH the router verdict** (one line, for L2, L3 and Spike — L1 declares the level alone): the result of the guide-router lookup described under `## Operative Guides`, i.e. `Level: L2 · router: no match` or `Level: L3 · router: GUIDE_release_sop.md → read`. Name the guide you matched, or `no match`.
|
|
45
|
+
|
|
46
|
+
| Level | Criteria | Required process |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| **L1 - Quick Fact / Snippet** | One claim row added to an existing topic; a typo; a preference update. No node created, no source entering the corpus, no frontmatter change. | Implement edit directly in existing note. No new documents. |
|
|
49
|
+
| **L2 - Propagation of settled knowledge** | The fact is **already settled** in the corpus and the work carries it into existing documents — restating, correcting a stale copy, updating an SOP that quotes it. No node created or superseded, no hierarchy change, no node frontmatter change, no new source ingested. | Mini-analysis in message: objective, impact, sources, validation. Update existing document or create single SOP/note. |
|
|
50
|
+
| **L3 - New knowledge unit / Corpus** | A source enters the corpus; a topic node is created or superseded; the hierarchy moves; a conflict must be reconciled; or what a claim asserts changes. | Full workflow: Vision Gate, Spec Elicitation, Taxonomy Pass, Knowledge Analysis, Distillation, Review, Indexing. |
|
|
51
|
+
| **Spike - Exploration** | Time-boxed exploratory research or draft without merging into official KB. | Outcome in `ai_docs/solutions/SPIKE_[topic].md`. |
|
|
52
|
+
|
|
53
|
+
Cross-cutting rules:
|
|
54
|
+
- **The unit of measure here is knowledge, never file count.** In this domain risk is
|
|
55
|
+
knowledge-shaped: carrying one settled fact into eight documents is small, and one
|
|
56
|
+
claim that re-parents a node is not. Do not import the code lens's file thresholds —
|
|
57
|
+
a level is chosen by what the change does to the corpus and the graph. What keeps
|
|
58
|
+
this from becoming an escape hatch is the trigger list below, which overrides the
|
|
59
|
+
level whatever the size, plus one limit: **propagation that changes what a claim
|
|
60
|
+
asserts is not propagation** — it is a new knowledge unit, so L3.
|
|
61
|
+
- **Domain routing (multi-lens installs only).** After the level is set, and only when a sibling lens skill of this family is installed (`agentic-sdlc`, `mkt-agentic-sdlc`), run the router in `routing.md` for every L2, L3 and Spike: it decides which lens's method and validation rules govern this unit of work. L1 never reaches it, and a single-lens install never reads the file — detection fails open. In such a project, never refer to a document whose meaning differs by lens ("threat model", "vision", `principles.md`, `handoff.md`) by its bare name: qualify it with its domain, or name its path.
|
|
62
|
+
- Personal data, credentials, security-sensitive processes, authN/authZ specs are high-risk: never L1.
|
|
63
|
+
- **Escalation triggers — ANY of these makes it L3, whatever the file count:** the change touches the topic hierarchy (`parents:`, a `GENERALIZES` verdict, a re-parent); it touches more than one node's frontmatter; it creates or supersedes a node other nodes reference. Re-shaping the graph is a unit of change, never a side effect of placing one claim.
|
|
64
|
+
- Adding one claim row to an existing topic is L1: the `id` may be left empty (the validator fills it — `claim-id --fill`), and no check errors on a hand-written row.
|
|
65
|
+
- If a bigger impact emerges during L1/L2 work, stop, reclassify and declare it.
|
|
66
|
+
- When in doubt, pick the higher level.
|
|
67
|
+
- **No useless questions.** Every question to the practitioner passes the legality test of the question discipline (`elicitation.md`): searched first with the search named, and the blocked decision named. Claim-conflict escalations additionally carry their own mandated form and are batched at run end (`reconciliation.md` §4).
|
|
68
|
+
|
|
69
|
+
## Write Triggers
|
|
70
|
+
|
|
71
|
+
Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it.
|
|
72
|
+
|
|
73
|
+
| Document | Write trigger | Phase |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `solutions/ANALYSIS_[topic].md` | Every L3, after elicitation and before any drafting. On topic match with an existing analysis, update that one instead of a new file. | 3 |
|
|
76
|
+
| `solutions/SPIKE_[topic].md` | Closing any Spike — including a negative outcome. | — |
|
|
77
|
+
| `vision/features/VISION_[feature].md` | Multi-milestone topic at analysis time, or retroactive trigger (second ANALYSIS on same theme). | 3 |
|
|
78
|
+
| `audit/handoff.md` (workstream registry) | **Never by hand — generated by `sdlc_check.py index` from the `HANDOFF_*.md` sources**, and `validate` errors when the two disagree. Regenerate at every L3 closure and at session end; the `Date:` header is derived, so no writer touches it. Inventory for lookup, never a work board. | 5 / session end |
|
|
79
|
+
| `audit/HANDOFF_[topic].md` | **One per OPEN workstream, with or without volatile state** — it is the authored home of that workstream's registry row (frontmatter `workstream`/`level`/`branch`/`status`/`since`/`next`/`details`/`updated`), so no file means no row. Carries the resume logistics too; the ANALYSIS Diary keeps the durable narrative (DRY). DELETED at closure — deleting it *is* removing the row. | 4 / 5 / session end |
|
|
80
|
+
| `audit/project_notes.md` | A note true for the whole project rather than one workstream. Appended verbatim to the generated registry, so regenerating cannot destroy notes that belong to no workstream. | 5 / session end |
|
|
81
|
+
| `audit/handoff.md` — converting an existing project | **Lazily, at the first write — and then ALL AT ONCE.** Converting one row at a time is the state that loses the others, so `index` refuses to write while anything in the file is unaccounted for and names it. Until the first source exists nothing generates and nothing errors. | 5 / session end |
|
|
82
|
+
| `audit/audit_plan.md` (Standalone) | Bootstrap, and whenever a mapped area changes state (`sdlc_check.py mark`). | 1 |
|
|
83
|
+
| `reference/GUIDE_[topic].md` (`source_kind: document`) | Origin+purpose test (`guides.md`), or a proactive proposal accepted by user. | 4 / 5 |
|
|
84
|
+
| `reference/GUIDE_[topic].md` (`source_kind: code`/`domain`) | Recognized high-complexity domain/concept with no CURRENT guide $\rightarrow$ duty to write autonomously. | 4 / 5 |
|
|
85
|
+
| `audit/reviews/REVIEW_LOG.md` | Every completed review — recorded in log. | 3 / 5 |
|
|
86
|
+
| ADR / Decision Log — `architecture/` or devPNT DB | A strategic decision was taken (pattern, policy, structural change): record before DONE. | 5 |
|
|
87
|
+
| `strategic/architecture.md`, `strategic/existing_features.md` | Bootstrap; update at closure when the knowledge catalog actually changed. | 1 / 5 |
|
|
88
|
+
| `vision/project_vision.md`, `roadmap.md`, `principles.md` | Bootstrap as `Status: DRAFT`; promoted to APPROVED only by explicit user confirmation. | 1 / 2 |
|
|
89
|
+
| `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 |
|
|
90
|
+
| 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`). | — |
|
|
91
|
+
| `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 |
|
|
92
|
+
| `corpus/notes/*` | Something is said (`origin: elicited`), synthesised (`derived_from:`), or ruled (`basis:`). A note with none of the three is refused by the validator. | 4 / 5 |
|
|
93
|
+
| `solutions/PLAN_[topic].md` + its ledger | A source too long for one context is ingested: **one task per reading window** (30 pages by default; the plan states the window used), each ending at a declared `extracted_through:`. That ledger is the register the ingestion resumes from across sessions — ingestion never builds a second one (`distillation.md` §3, `templates.md`). | 4 |
|
|
94
|
+
| `corpus/given/*.meta.md` — `extracted_through:` | Every reading window closes by advancing it (`p=<n>`, `L<n>`, `complete`). Required once any claim cites the artifact: unstated, "I am finished" cannot be falsified, which is how a sampled 200-page manual passes for an ingested one. | 4 |
|
|
95
|
+
| `INDEX.md`, `reference/INDEX.md`, `topics/INDEX.md`, `corpus/INDEX.md` | Regenerated by `sdlc_check.py index` at closure — never by hand; `validate` fails on a hand-edited one. | 5 |
|
|
96
|
+
|
|
97
|
+
## Operating Modes
|
|
98
|
+
|
|
99
|
+
### Full Standalone
|
|
100
|
+
Use this mode when devPNT is unavailable, not configured for the current project, or the user explicitly asks for a filesystem-only workflow.
|
|
101
|
+
- Source of truth: `ai_docs/` (`vision/`, `solutions/`, `reference/`, `audit/`, `strategic/`).
|
|
102
|
+
|
|
103
|
+
### Hybrid in symbiosis with devPNT
|
|
104
|
+
Use this mode when `devpnt_*` tools are available and point at the current project.
|
|
105
|
+
- devPNT governs `M-VISION`, Master Plan, Action Plan, and versioned artifacts.
|
|
106
|
+
- Local `ai_docs/` serves as readable context, Standalone fallback, local handoff, or shadow copy.
|
|
107
|
+
|
|
108
|
+
## L3 Workflow
|
|
109
|
+
|
|
110
|
+
### 1. Audit and Alignment
|
|
111
|
+
- Read `ai_docs/audit/handoff.md` (workstream registry) to see active topics.
|
|
112
|
+
- 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.
|
|
113
|
+
- If `ai_docs/` is missing, create the bootstrap set: `README.md`, `vision/` docs, `strategic/` docs, and `audit/audit_plan.md`, then run `sdlc_check.py index`.
|
|
114
|
+
|
|
115
|
+
### 2. Vision Gate
|
|
116
|
+
- Read `project_vision.md`, `roadmap.md`, `principles.md` (or devPNT `M-VISION`).
|
|
117
|
+
- Verify request aligns with expected benefits, user goals, and success signals.
|
|
118
|
+
|
|
119
|
+
### 3. Request Analysis & Taxonomy Pass
|
|
120
|
+
- Run spec elicitation round (`elicitation.md`) before drafting analysis.
|
|
121
|
+
- Run taxonomy pass (`taxonomy.md`): verify whether topics, categories, or SOPs already exist in `ai_docs/`. Avoid duplication.
|
|
122
|
+
- Create or update `ai_docs/solutions/ANALYSIS_[topic].md`.
|
|
123
|
+
- **Design review gate (end of Phase 3, before any drafting):** the analysis is reviewed by somebody other than its author — a subagent with fresh context, or a declared self-pass when none is available. Follow `review.md`; log the outcome in `audit/reviews/REVIEW_LOG.md`. A knowledge structure reviewed only by the person who chose it is not reviewed.
|
|
124
|
+
|
|
125
|
+
### 4. Knowledge Processing & Distillation
|
|
126
|
+
- **Isolate the work (Branch/worktree hygiene).** Distillation rewrites existing notes: do it on a branch or a worktree, never directly on the shared corpus, so a half-finished reconciliation is never what the next reader finds.
|
|
127
|
+
- Before drafting (L2/L3; L1 exempt), **consult the guide router** for a guide covering the task and read it first (the consult trigger, `guides.md` §0). A targeted description match, not a blanket read. Its result is the router verdict already declared with the triage level (Rule Zero).
|
|
128
|
+
- Execute knowledge extraction using **Signal Distillation** (`distillation.md`).
|
|
129
|
+
- **Opt-in subagent execution**: for an L3 with an approved analysis, the work MAY be executed via subagents per `dispatch.md`; default stays same-session.
|
|
130
|
+
- Handle conflicting or outdated information via **Reconciliation** (`reconciliation.md`). Mark obsolete files `status: SUPERSEDED`.
|
|
131
|
+
|
|
132
|
+
### 5. Closure & Indexing
|
|
133
|
+
- Run verification checks (`sdlc_check.py check --root <project_root>`).
|
|
134
|
+
- If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
|
|
135
|
+
- Update `audit/handoff.md`.
|
|
136
|
+
- Regenerate manifests: `python <skill_dir>/scripts/sdlc_check.py index --root <project_root>`.
|
|
137
|
+
- Mark output clean and complete.
|
|
138
|
+
|
|
139
|
+
## Operative Guides & Router
|
|
140
|
+
Guides are consulted, created, and distilled per `guides.md`.
|
|
141
|
+
- **Consult (before acting)**: check `ai_docs/reference/INDEX.md` — the guide router — and declare the verdict with the triage level.
|
|
142
|
+
- **Propose proactively**: when the user hands over indications that will govern future work, propose distilling them into a guide. A proposal, never a silent write, and never from model knowledge — a guide's whole value is that every claim traces to what the user actually provided.
|
|
143
|
+
- Distill from user instructions into `ai_docs/reference/GUIDE_[topic].md`.
|
|
144
|
+
|
|
145
|
+
## Mechanical Enforcement
|
|
146
|
+
- `scripts/sdlc_check.py index`: updates `ai_docs/INDEX.md` and `ai_docs/reference/INDEX.md`.
|
|
147
|
+
- `scripts/sdlc_check.py validate`: validates YAML frontmatter (`status`, `description`).
|
|
148
|
+
- `scripts/sdlc_check.py check`: checks dirty closures and missing indexes.
|
|
@@ -168,6 +168,29 @@ When you are the reviewer:
|
|
|
168
168
|
mark ANALYZED, with no searches named**, is the finding that matters most on a
|
|
169
169
|
project the methodology arrived in recently — an unread map reported as an empty
|
|
170
170
|
one is how a duplicate of the existing codebase gets designed.
|
|
171
|
+
- **Interface Contract (same reviews; fires only in the lens whose template
|
|
172
|
+
defines the section — the code lens today).** When the change creates or
|
|
173
|
+
modifies an actor-facing surface (the trigger's owning definition is the code
|
|
174
|
+
lens's `templates.md` section comment — cite it, never restate it), **an
|
|
175
|
+
artifact carrying NO `## Interface Contract` is itself a finding** — "the
|
|
176
|
+
artifact does not have one" is what a skipped contract looks like, not a reason
|
|
177
|
+
to skip the check. When the contract is there, these findings live here: a
|
|
178
|
+
use-case with no named interaction flow realizing it; **a flow that is not
|
|
179
|
+
walkable at the responsibility level** — it jumps from the actor's action to
|
|
180
|
+
the outcome without naming the components it traverses; **a *how* inside the
|
|
181
|
+
contract** — a mechanism, algorithm, data structure, widget or file-level
|
|
182
|
+
design — which is Solution-leakage (the flow NAMES components as
|
|
183
|
+
responsibility-holders, it never designs them); **required feedback that omits
|
|
184
|
+
an error or intermediate state, or a software actor's return status** (feedback
|
|
185
|
+
is universal, not human-only); a design or diff element that alters a
|
|
186
|
+
contracted surface, flow or feedback with no explicit renegotiation note (after
|
|
187
|
+
design approval that is a scope change owed to the user, not a design detail);
|
|
188
|
+
a contracted flow the `## Test Strategy` does not cover; and a new interaction
|
|
189
|
+
idiom introduced where the contract's own as-is names an existing one, with no
|
|
190
|
+
declared reason. (The architectural constraints the surface must live with are
|
|
191
|
+
NOT checked here — architecture-awareness is the Capability Ledger / Impact
|
|
192
|
+
review's job; a clause for it would duplicate that.) A lens whose template
|
|
193
|
+
defines no such section (knowledge, marketing) never fires this clause.
|
|
171
194
|
|
|
172
195
|
## Anti-patterns
|
|
173
196
|
|
|
@@ -245,6 +245,7 @@ REQUIRED_CAPABILITIES = frozenset({
|
|
|
245
245
|
# Listed here so "this distribution does not claim it" is a visible decision.
|
|
246
246
|
OPTIONAL_CAPABILITIES = frozenset({
|
|
247
247
|
"architect_pass", # does the component already exist? (code overlay)
|
|
248
|
+
"interaction_contract", # actor-facing surface spec between use cases and solution (code overlay)
|
|
248
249
|
"taxonomy_pass", # do the categories/topics already exist? (knowledge overlay)
|
|
249
250
|
"comprehension_guides", # source_kind: code maps of complex components
|
|
250
251
|
"tdd", # test-first discipline
|
|
@@ -841,8 +842,11 @@ def registry_conversion_blockers(root):
|
|
|
841
842
|
if not hand.is_file():
|
|
842
843
|
return []
|
|
843
844
|
text = read_text(hand)
|
|
844
|
-
|
|
845
|
-
|
|
845
|
+
# "Already ours" = written by ANY family entry point: the header is WRITTEN
|
|
846
|
+
# with entry_script(), so recognition must not hard-code one distribution's
|
|
847
|
+
# script name (a registry generated by mkt_check.py is just as generated).
|
|
848
|
+
if re.search(r"GENERATED by \S+ index - do not edit by hand", text):
|
|
849
|
+
return []
|
|
846
850
|
blockers = []
|
|
847
851
|
known = {str(m.get("workstream")).strip() for _p, m in list_workstreams(root)}
|
|
848
852
|
orphans = [r for r in parse_registry_rows(text) if r not in known]
|