@antoneeo/kb-agentic-skill 1.19.0 → 1.21.0

package/skills/kb-agentic-skill/portability.md

@@ -1,125 +1,125 @@
-# Portability — carrying knowledge between projects
-
-**For whom**: the agent moving a subgraph out of one project or into another.
-**Answers**: "what travels, what refuses to travel, and what an import may decide".
-**Does not answer**: where a claim's concept belongs (`taxonomy.md` — import *uses* that
-pass, it does not replace it) or how a disagreement is settled (`reconciliation.md`).
-
-## 0. The two commands, and what to tell the user
-
-A bundle is a **folder**, not an archive. Nothing here compresses or unpacks anything:
-the user moves the folder however they already move folders.
-
-**Sending side** — run from the project that owns the knowledge:
-
-```
-sdlc_check.py export --out ../kb-bundle                    # the whole KB
-sdlc_check.py export --out ../kb-bundle --topics pricing,licensing
-```
-
-Write it **outside the docs root**. A bundle sitting inside `ai_docs/` is a second copy
-of topics and corpus files in the tree the validator walks, and that confusion is free
-to avoid.
-
-**Receiving side** — run from the project that is to gain it:
-
-```
-sdlc_check.py import ../kb-bundle --dry-run     # see what would land
-sdlc_check.py import ../kb-bundle
-sdlc_check.py check                             # always, right after
-```
-
-**What to say to the user, in their words.** Say these four things and stop:
-
-1. *"I've written the bundle to `<path>`. It's a folder — move it to the other project
-   however you like."*
-2. *"It carries the source documents too, not just the notes, so it is not small. That is
-   the point: over there the claims can still be traced back to the page they came from."*
-3. After importing: *"Nothing was overwritten. Anything already there stayed as it was"* —
-   and, if a topic was skipped, *"a topic with the same name already exists; I have not
-   merged them, because they may not be the same subject. Do you want me to look?"*
-4. If an imported ruling arrived: *"one decision came from the other project. I have kept
-   it, marked as theirs, and it cannot settle anything here until you confirm it."*
-
-Do not explain the closure, the id hashing or the provenance model unless asked. The
-user asked to move their knowledge, not to learn how it is stored.
-
-## 1. What a bundle is
-
-A directory mirroring the docs-root layout:
-
-```
-<bundle>/
-  MANIFEST.md            kb_bundle: 1, source_project, topics, per-artifact sha256
-  topics/<slug>.md
-  corpus/given/<name>    + <name>.meta.md   (+ the .txt extraction, when there is one)
-  corpus/notes/<name>.md
-```
-
-The layout is mirrored **on purpose**. Claim `source` cells are docs-root-relative, so
-nothing is rewritten on import — and because `kb_claim_id` hashes
-`path#locator#qty` with the text excluded, the same artifact cited at the same span
-mints **the same id in every project**. De-duplication is therefore mechanical, not a
-judgement call, and importing the same bundle twice is a provable no-op.
-
-## 2. Export is a closure, not a selection
-
-You choose topics; the export decides what must travel with them.
-
-- **Every artifact a selected claim cites**, plus its sidecar and its stored extraction.
-  A claim whose source cannot be reopened is model knowledge arriving by another route —
-  the validator would reject it in the target, and correctly.
-- **Every row a `CONTESTED` row points at.** The symmetry check refuses a set that lost
-  half its members, so a partial export ships a tree that cannot pass its own checks.
-  When a partner row lives in an unselected topic, that topic is **added and reported** —
-  never dropped, never silently.
-
-If a conflict partner resolves to no row at all, the export **refuses**: exporting a
-broken set is worse than exporting nothing.
-
-## 3. Import is additive, and decides nothing
-
-`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
-
-- **Never overwrites a topic.** A slug that already exists is reported and skipped: two
-  projects using the word `pricing` may mean two different things, and that judgement is
-  the placement pass's (`taxonomy.md`, five verdicts, `owns:` against double placement).
-- **Never deletes.** The doctrine is tombstones over deletion; an additive import has no
-  business removing anything.
-- **All or nothing.** The whole plan is computed before a byte is written. An import that
-  half-applies leaves a tree whose checks fail and whose owner cannot tell what landed.
-
-It refuses on: a missing or unmarked `MANIFEST.md`; a path that escapes the docs root; an
-artifact whose name matches an existing one **with different bytes** (content-addressed
-names must mean equal content — a mismatch means one of the two is lying about its
-origin); an incomplete conflict set; a dangling `supersedes:`.
-
-After importing, run `check`. The import is deliberately not a validator.
-
-## 4. Knowledge crosses; authority does not
-
-`RULING` means *the fact you know and the corpus does not*, with a `basis:` you gave. It
-is the only thing that settles a `CONTESTED` set. A ruling from another project carries
-another owner's decision, and importing it unchanged would make that decision binding
-here without anyone here granting it — the machine deciding, which reconciliation
-refuses everywhere else.
-
-So an imported ruling arrives as **`prov: IMPORTED`** (owner ruling, 2026-08-03):
-
-- its text, span and original `basis:` travel **verbatim** — the knowledge is not lost,
-  and pretending it is a `DERIVED` synthesis would make the row lie about where it came
-  from;
-- its note carries `imported_from:`, and the validator refuses an `IMPORTED` row without
-  it: unnamed, the class says nothing and the row is a `RULING` with the label filed off;
-- **it cannot supersede a local row.** The validator errors on `SUPERSEDED <id>` when
-  that id is `IMPORTED`.
-
-**Re-ratification** is one act: read it, write your own note with your own `basis:`, and
-set the row's `prov` to `RULING`. That is you deciding, which is the only thing that ever
-settles anything here.
-
-## 5. Triage
-
-Exporting is L1 — it writes nothing into the corpus and changes no knowledge. Importing
-is **L3**: a source enters the corpus and nodes are created, which is the L3 definition
-in Rule Zero, and the bundle is external input, which is never L1 whatever its size.
+# Portability — carrying knowledge between projects
+
+**For whom**: the agent moving a subgraph out of one project or into another.
+**Answers**: "what travels, what refuses to travel, and what an import may decide".
+**Does not answer**: where a claim's concept belongs (`taxonomy.md` — import *uses* that
+pass, it does not replace it) or how a disagreement is settled (`reconciliation.md`).
+
+## 0. The two commands, and what to tell the user
+
+A bundle is a **folder**, not an archive. Nothing here compresses or unpacks anything:
+the user moves the folder however they already move folders.
+
+**Sending side** — run from the project that owns the knowledge:
+
+```
+sdlc_check.py export --out ../kb-bundle                    # the whole KB
+sdlc_check.py export --out ../kb-bundle --topics pricing,licensing
+```
+
+Write it **outside the docs root**. A bundle sitting inside `ai_docs/` is a second copy
+of topics and corpus files in the tree the validator walks, and that confusion is free
+to avoid.
+
+**Receiving side** — run from the project that is to gain it:
+
+```
+sdlc_check.py import ../kb-bundle --dry-run     # see what would land
+sdlc_check.py import ../kb-bundle
+sdlc_check.py check                             # always, right after
+```
+
+**What to say to the user, in their words.** Say these four things and stop:
+
+1. *"I've written the bundle to `<path>`. It's a folder — move it to the other project
+   however you like."*
+2. *"It carries the source documents too, not just the notes, so it is not small. That is
+   the point: over there the claims can still be traced back to the page they came from."*
+3. After importing: *"Nothing was overwritten. Anything already there stayed as it was"* —
+   and, if a topic was skipped, *"a topic with the same name already exists; I have not
+   merged them, because they may not be the same subject. Do you want me to look?"*
+4. If an imported ruling arrived: *"one decision came from the other project. I have kept
+   it, marked as theirs, and it cannot settle anything here until you confirm it."*
+
+Do not explain the closure, the id hashing or the provenance model unless asked. The
+user asked to move their knowledge, not to learn how it is stored.
+
+## 1. What a bundle is
+
+A directory mirroring the docs-root layout:
+
+```
+<bundle>/
+  MANIFEST.md            kb_bundle: 1, source_project, topics, per-artifact sha256
+  topics/<slug>.md
+  corpus/given/<name>    + <name>.meta.md   (+ the .txt extraction, when there is one)
+  corpus/notes/<name>.md
+```
+
+The layout is mirrored **on purpose**. Claim `source` cells are docs-root-relative, so
+nothing is rewritten on import — and because `kb_claim_id` hashes
+`path#locator#qty` with the text excluded, the same artifact cited at the same span
+mints **the same id in every project**. De-duplication is therefore mechanical, not a
+judgement call, and importing the same bundle twice is a provable no-op.
+
+## 2. Export is a closure, not a selection
+
+You choose topics; the export decides what must travel with them.
+
+- **Every artifact a selected claim cites**, plus its sidecar and its stored extraction.
+  A claim whose source cannot be reopened is model knowledge arriving by another route —
+  the validator would reject it in the target, and correctly.
+- **Every row a `CONTESTED` row points at.** The symmetry check refuses a set that lost
+  half its members, so a partial export ships a tree that cannot pass its own checks.
+  When a partner row lives in an unselected topic, that topic is **added and reported** —
+  never dropped, never silently.
+
+If a conflict partner resolves to no row at all, the export **refuses**: exporting a
+broken set is worse than exporting nothing.
+
+## 3. Import is additive, and decides nothing
+
+`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
+
+- **Never overwrites a topic.** A slug that already exists is reported and skipped: two
+  projects using the word `pricing` may mean two different things, and that judgement is
+  the placement pass's (`taxonomy.md`, five verdicts, `owns:` against double placement).
+- **Never deletes.** The doctrine is tombstones over deletion; an additive import has no
+  business removing anything.
+- **All or nothing.** The whole plan is computed before a byte is written. An import that
+  half-applies leaves a tree whose checks fail and whose owner cannot tell what landed.
+
+It refuses on: a missing or unmarked `MANIFEST.md`; a path that escapes the docs root; an
+artifact whose name matches an existing one **with different bytes** (content-addressed
+names must mean equal content — a mismatch means one of the two is lying about its
+origin); an incomplete conflict set; a dangling `supersedes:`.
+
+After importing, run `check`. The import is deliberately not a validator.
+
+## 4. Knowledge crosses; authority does not
+
+`RULING` means *the fact you know and the corpus does not*, with a `basis:` you gave. It
+is the only thing that settles a `CONTESTED` set. A ruling from another project carries
+another owner's decision, and importing it unchanged would make that decision binding
+here without anyone here granting it — the machine deciding, which reconciliation
+refuses everywhere else.
+
+So an imported ruling arrives as **`prov: IMPORTED`** (owner ruling, 2026-08-03):
+
+- its text, span and original `basis:` travel **verbatim** — the knowledge is not lost,
+  and pretending it is a `DERIVED` synthesis would make the row lie about where it came
+  from;
+- its note carries `imported_from:`, and the validator refuses an `IMPORTED` row without
+  it: unnamed, the class says nothing and the row is a `RULING` with the label filed off;
+- **it cannot supersede a local row.** The validator errors on `SUPERSEDED <id>` when
+  that id is `IMPORTED`.
+
+**Re-ratification** is one act: read it, write your own note with your own `basis:`, and
+set the row's `prov` to `RULING`. That is you deciding, which is the only thing that ever
+settles anything here.
+
+## 5. Triage
+
+Exporting is L1 — it writes nothing into the corpus and changes no knowledge. Importing
+is **L3**: a source enters the corpus and nodes are created, which is the L3 definition
+in Rule Zero, and the bundle is external input, which is never L1 whatever its size.

package/skills/kb-agentic-skill/review.md

@@ -1,8 +1,11 @@
 # Review Discipline
 
-The single definition of how to request, receive, and perform a review. Other
-places that need review behavior point here instead of restating it (DRY) —
-including devPNT's §4.5/§4.6 gates and any future review step.
+The single definition of how to request, receive, and perform an agent review,
+in Standalone and in Hybrid alike. Other places that need review behavior point
+here instead of restating it (DRY) — including devPNT doctrine §4.5/§4.6, which
+invoke this same review, and any future review step. **devPNT performs no
+review**: it hosts the governed artifacts and is where the human reviews and
+approves them — after the agent review this file defines, never instead of it.
 
 ## When a review is due
 
@@ -14,6 +17,20 @@ Two moments, and they review different things:
 | **1b. Late arrival** | Work that became L3 *after* code existed — an L1/L2 reclassified mid-flight, or a design increment on a feature already implemented — runs moment 1 **now**, before any further implementation, logged `design (late)` | same | L3 |
 | **2. Closure review** | Phase 5, before DONE | the actual diff, against that approved design | L2 / L3 — the L2 closure review is optional; every review that runs logs its row |
 
+**The agent review comes first, the human's after — never instead (Hybrid).**
+No governed artifact that this file reviews — the design (`E-ISP`, `E-TDD`),
+and whatever else the client's devPNT doctrine §4.5/§4.6 sends to review — is
+proposed to devPNT before an agent review of it under this file has a final
+verdict of PASS; the proposal's notes cite that
+REVIEW_LOG row (date, doc_key, verdict), so the human sees which review it
+passed. When the round cap is reached with findings still standing, the artifact
+goes back to the user in chat with those findings, and it reaches devPNT only on
+the user's explicit decision — with the open findings attached to the proposal
+and the decision recorded. Where the client also follows devPNT doctrine
+§4.5/§4.6, that invocation IS this review: one review, one REVIEW_LOG row in the
+Hybrid realization below, and the doctrine's extra requirements add to this
+mandate, never replace it.
+
 **Why the design review is its own moment, and not a nicety.** The closure review
 can only tell you the code matches the design; it cannot tell you the design was
 wrong. An omission in the design — an impacted file nobody listed, a threat with no
@@ -165,7 +182,7 @@ policy pays — could not be drawn.
 **mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
 `tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.
 Around it, Standalone adds `reviewer` and Hybrid adds `instrument` and `notes` —
-a devPNT row carries no `reviewer` column at all, so "one identical column list"
+a Hybrid row carries no `reviewer` column at all, so "one identical column list"
 was never true of the two modes. This costs nothing for the reason `templates.md`
 §`ai_docs/audit/reviews/REVIEW_LOG.md` owns and states.
 The log is how the gate's value is measured over time; skipping it makes the gate
@@ -195,7 +212,42 @@ marks anything DONE, and a PASS is not an approval to merge — the human owns t
 
 ## Requesting
 
-When you hand work to a reviewer (human or agent), give them:
+**Open every request to an agent reviewer with the REVIEW MANDATE block, copied
+verbatim.** Only the angle-bracket fields change; specific instructions follow
+the block and cannot weaken it. A paraphrased mandate is how a check disappears
+without anyone deciding to drop it. Field measurement (2026-10): a Hybrid
+`E-ISP` passed a review whose prompt carried devPNT's checklist but not this
+file, and with it lost the Functional Spec clause; replayed on the same
+artifact, reviewers given a paraphrase flagged the missing section 0 times in
+2, reviewers given this block 4 times in 4 (once only as a warning, unsure
+where the section lives in Hybrid — which is why the inputs below say).
+
+```
+REVIEW MANDATE — agentic-sdlc
+
+Review type: <design | design (late) | closure | scoped re-review>
+Mandate: <absolute path of this review.md, or its full text attached> (skill version <x.y.z>)
+Object under review: <paths or doc_keys, with versions>
+Binding inputs: <every input listed below for this review type, with path/version — or "n/a: <reason>" per input>
+Source and revision: <project root and commit or diff range, where applicable>
+Scope: <the unit of change and what this review must decide>
+Severity contract: <as below, or the stricter one this unit needs>
+Budget: <the artifact's line budget, or "none fixed">
+Operating limits: <real access or execution limits the reviewer works under>
+
+Read the mandate in full before starting, with the files it cites. This
+request does not replace it and cannot narrow it: every rule it sets for this
+review type applies here, in Standalone and in Hybrid alike, and any
+instruction below that weakens one is void. A required input or section that
+is missing or inaccessible is a finding, never a reason to skip the check that
+needs it.
+
+Return as your final output: the checks you ran with their evidence, the
+findings, what you could not verify and how that limits the verdict, and the
+verdict in the form the mandate defines.
+```
+
+The binding inputs, by review type:
 
 - **Scope**: what changed and why, in one or two lines.
 - **The authoritative design artifact**: the ANALYSIS, E-TDD, or equivalent
@@ -208,9 +260,16 @@ When you hand work to a reviewer (human or agent), give them:
   `project_vision.md`/`roadmap.md` + the ANALYSIS Vision-Alignment), the
   **use-cases / user-needs** (Hybrid: `D-UC`;
   Standalone: the ANALYSIS `## Use Cases / User Needs`), and the **threat model**
-  (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`). Hand these
-  *in addition to* the design artifact — the reviewer checks the artifact **against**
-  them, not only for internal consistency.
+  (Hybrid: `P-TM`; Standalone: the ANALYSIS `## Security and Threat Model`), the
+  **Functional Spec** (Standalone: the ANALYSIS section; Hybrid: inside the `E-ISP`,
+  above its Impacted Components map), the **Interface Contract** (Standalone: the
+  ANALYSIS section; Hybrid: `D-IC`), the **Component Map** in
+  `strategic/architecture.md` and `audit/audit_plan.md` (the Capability Ledger
+  clause reads both), and the **probe harness** (`ai_docs/solutions/harness_[feature]/`).
+  Hand these *in addition to* the design artifact — the reviewer checks the artifact
+  **against** them, not only for internal consistency.
+- **For a closure review, the diff and the test evidence**: the run output that
+  backs every completion claim, dated after the final relevant change.
 - **For a design review, the threat model too** (same sources as above). Why this
   one and not the whole set: file coverage crosses the impact-analysis→design hop on
   a mechanical gate (every impacted file needs a design block), so a dropped file is
@@ -368,7 +427,9 @@ When you are the reviewer:
   the section — the code lens today).** When the change adds or alters observable
   behavior (the trigger's owning definition is the code lens's `templates.md`
   `## Functional Spec` section comment — cite it, never restate it), **an L3
-  artifact carrying NO `## Functional Spec` is itself a finding** — absence is
+  artifact carrying NO `## Functional Spec` is itself a finding** — in Hybrid the
+  section lives inside the `E-ISP`, above its Impacted Components map, so an
+  `E-ISP` without it is that finding. Absence is
   what a skipped spec looks like, not a reason to skip the check. When the spec
   is there, these findings live here: **a component, file or mechanism named
   inside it** — the spec is component-free by construction; that is

package/skills/kb-agentic-skill/routing.md

@@ -17,6 +17,7 @@ family, identified by the `name:` in their `SKILL.md`:
 | code | `agentic-sdlc` | this repository's code |
 | knowledge | `kb-agentic` | documents the user supplied |
 | marketing | `mkt-agentic-sdlc` | market evidence |
+| course | `course-creator` | a defined learner's progressive understanding |
 
 - **No sibling installed, or the directory cannot be read** → the router does NOT run.
   Work under the loaded lens; read no further. This is the normal single-lens case and
@@ -36,6 +37,11 @@ Run the steps in order. Stop at the first one that decides.
    - *This repository's code* → provisional **code**; continue to step 2.
    - *Documents the user supplied* → **knowledge**. Decided.
    - *Market evidence* → **marketing**. Decided.
+   - *A deliverable whose purpose is to teach a defined audience through progressive
+     explanations and modules* → **course**. Decided, regardless of whether its
+     sources came from a supplied corpus, web research or this repository's code.
+     Acquiring and checking that corpus is a separate knowledge unit. Course
+     content is not routed through the provisional code branch below.
    - *A deliverable whose purpose is market-facing persuasion* (copy, positioning,
      campaign material) → **marketing regardless of source**. Decided. Without this
      branch the marketing lens is reachable only when the *source* is market evidence,
@@ -52,14 +58,15 @@ Run the steps in order. Stop at the first one that decides.
      **knowledge**. Decided; step 3 is not reached.
 
 3. **Build-consumed override** — only on the provisional `code` branch, never
-   overriding a *marketing* or *supplied-documents* verdict. *Is the deliverable a
+   overriding a *marketing*, *course* or *supplied-documents* verdict. *Is the deliverable a
    file the project's build or test toolchain consumes?* Executable or imported
    source: yes. Committed Markdown: no. A yes confirms **code**.
 
-4. **Split rule.** A request whose work must be faithful to two sources is **two units
-   of work**, split before routing: the distillation (knowledge) and the design that
-   cites it (code) each route alone. The router returns one lens per unit; it never
-   returns two lenses for one unit.
+4. **Split rule.** A request with distinct deliverables is split before routing:
+   corpus ingestion (knowledge) and a course based on it (course), or campaign
+   material (marketing) and training (course), are separate units. The same applies
+   to distillation (knowledge) and a technical design that cites it (code). The
+   router returns one lens per unit; it never returns two lenses for one unit.
 
 5. **Owning tree.** A straddling artifact keeps its lens for *method* and takes this
    repository's tree and validator for *storage*. Lens and location are separate
@@ -81,14 +88,18 @@ Run the steps in order. Stop at the first one that decides.
 | "turn these vendor specs into a technical design" | split (step 4): spec = supplied docs; design = this repo | — | — | **knowledge** for the distillation; **code** for the design, citing it |
 | "write the pricing page copy from our market research" | **purpose: market-facing → marketing** | never reached | never reached | **marketing**; stored in this repo's tree (step 5) |
 | "write the launch blog post from the release notes" | purpose: market-facing → marketing | never reached | never reached | **marketing** |
+| "create a beginner course from these API docs" | purpose: teaching → course | never reached | never reached | **course** |
+| "research sources and teach a newcomer a topic" | purpose: teaching → course | never reached | never reached | **course** |
+| "ingest these manuals, then create a course" | split: corpus = supplied docs; training = teaching | never reached | never reached | **knowledge** for ingestion; **course** for training |
+| "write sales copy and an onboarding course" | split: persuasion and teaching | never reached | never reached | **marketing** for copy; **course** for training |
 
-## 3. Acting on the verdict
-
-Memory is not a competing verdict. Every lens ships `memory.md` and the shared
-knowledge machinery: consult across domains without switching the work's owner or
-running a second workflow. Resolve an ambiguous owner before applying its definitive
-risk scale; a provisional level is not a second mandatory triage. Split only distinct
-deliverables, not the act of reading another domain's evidence.
+## 3. Acting on the verdict
+
+Memory is not a competing verdict. Every lens ships `memory.md` and the shared
+knowledge machinery: consult across domains without switching the work's owner or
+running a second workflow. Resolve an ambiguous owner before applying its definitive
+risk scale; a provisional level is not a second mandatory triage. Split only distinct
+deliverables, not the act of reading another domain's evidence.
 
 The verdict binds the **method and the validation rules**, not the storage:
 
@@ -96,11 +107,12 @@ The verdict binds the **method and the validation rules**, not the storage:
 - **Verdict = a sibling lens** → say so, and work that unit under the sibling's method
   and its rule set (its templates, its mandatory risk section — code
   `## Security and Threat Model`, knowledge `## Sources and Verification`, marketing
-  `## Threat Map / Plan Risks`). The artifact is written with an explicit
+  `## Threat Map / Plan Risks`, course `## Learning and Content Risks`). The artifact is written with an explicit
   `domain:` field so the answer survives the session, and it stays in this project's
   `ai_docs/` tree (step 5).
 - **The unit was split** (step 4) → route and declare each half separately.
 
-Documents under `vision/` — the project vision, principles, the roadmap — sit **above**
-the domain split: they belong to no lens and are validated by the core's structural
-rules only. The router is not consulted for them.
+The project vision, principles and roadmap under `vision/` sit **above** the domain
+split and receive the core's structural rules. A feature Vision under
+`vision/features/` belongs to its explicit domain; a course Vision declares
+`domain: course`. The router is not consulted for project-wide vision files.