@antoneeo/kb-agentic-skill 1.31.0 → 1.33.0

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

@@ -39,7 +39,8 @@ sdlc_check.py check                             # always, right after
    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."*
+   it, marked as theirs, and it cannot settle anything here until you confirm it. The
+   question it had closed is open again here, with their decision beside the sources."*
 
 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.
@@ -74,6 +75,11 @@ You choose topics; the export decides what must travel with them.
   When a partner row lives in an unselected topic, that topic is **added and reported** —
   never dropped, never silently.
 - **Not the `not-yet-honored-by` markers.** They describe this project's code, so the export drops them and says so, without a number.
+- **Not the declarations.** A `DECLARED` row is this project's commitment to its own
+  recipient; carried elsewhere it would read as the importer's. The export leaves the
+  rows and the artifacts only they cite behind and says so in one line, without a
+  number. Nothing else is lost: no other row may point at a declaration, and the export
+  refuses one that does (run `check`).
 
 If a conflict partner resolves to no row at all, the export **refuses**: exporting a
 broken set is worse than exporting nothing.
@@ -83,7 +89,8 @@ tombstone sidecar stays home.
 
 ## 3. Import is additive, and decides nothing
 
-`import` writes files. It does not place concepts, merge bodies, or settle disagreements.
+`import` writes files. It does not place concepts, merge bodies, or settle disagreements —
+and it refuses to let the bundle settle them either: a ruling arrives foreign (§4).
 
 - **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
@@ -96,7 +103,12 @@ tombstone sidecar stays home.
 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:`.
+origin); an incomplete conflict set — a `CONTESTED` or `SUPERSEDED` pointer that would
+resolve to no row, or to a row of this project that does not name it back (an import
+never edits an existing topic); a row settled by a ruling the import does not write, or
+by a row this project holds as `IMPORTED`; a ruling it cannot carry foreign (§4); a
+`DECLARED` row (an export never ships one, so the bundle was edited by hand). Each
+refusal names the row and writes nothing.
 
 After importing, run `check`. The import is deliberately not a validator.
 
@@ -108,19 +120,43 @@ another owner's decision, and importing it unchanged would make that decision bi
 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.
+So `import` makes every `RULING` row of a topic it writes arrive as **`prov: IMPORTED`**
+(owner rulings 2026-08-03 and 2026-10-23):
+
+- **its note arrives as a renamed copy**, `corpus/notes/imported_<source project>_<name>`,
+  whose frontmatter adds `imported_from: <source project> — <original path>` and reads
+  `origin: imported`. Its text 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. The note is never edited under its own name: a line inserted into
+  it would move the line every locator cites. The row cites the copy at the same text
+  (its locator and id move with it), and a bundle note `derived_from:` the ruling names
+  the copy. The original name is never written, so a row copied by hand out of a skipped
+  topic cannot cite a foreign note as local;
+- **the question it had closed reopens.** The rows it superseded and the ruling itself
+  arrive as one `CONTESTED` set; a ruling already contested with a newer source keeps
+  that partner, one that superseded nothing arrives `OK`;
+- the validator refuses an `IMPORTED` row whose note lacks `imported_from:` (unnamed,
+  the class says nothing), a `SUPERSEDED <id>` pointing at an `IMPORTED` row, and a
+  `RULING` row on a note that names a foreign origin.
+
+**Ratification** is the ordinary ruling of `reconciliation.md`, and it is you deciding,
+which is the only thing that ever settles anything here: write your own note with your
+own `basis:`, add a `RULING` row on it, and mark every row `CONTESTED` with the imported
+one — following the sets transitively — `SUPERSEDED <your id>`, the `IMPORTED` row
+included. Relabelling the `IMPORTED` row `RULING` is refused: another project's note
+cannot carry your decision.
+
+Any bundle note that declares a `basis:` lands this way, renamed, even when its ruling row
+does not travel with it — otherwise it would land first under its own name and a later
+import of its ruling would find it there. A ruling `import` cannot carry this way is
+refused, never copied: one not resting on a note cited by line, on a note with no
+frontmatter, or on a note that already names a foreign origin (the source relabelled an
+imported row); a row superseded both by a ruling and by a row that is not one; a ruling
+another row superseded while rows still depend on it. A tree imported before this
+conversion existed (≤ kb 1.31.0) holds the foreign ruling as `RULING` on its original
+note: delete the imported topic and its files and import again, or convert it by hand as
+above. The origin is named after the exporting folder (`source_project`), so two clones
+of one project in differently named folders name it differently.
 
 ## 5. Triage
 

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

@@ -24,6 +24,15 @@ Subject-sameness is semantic judgement; no query performs it. Classify:
 | **coexistence** | contradictory only if scopes overlapped — and by the half-open rule they do not | both rows stay `OK`. "12k until March" and "15k from March" are two truths, not a conflict |
 | **conflict** | contradictory, scopes overlap | **every** row in the set becomes `CONTESTED` listing all counterparts. Nothing is picked |
 
+**A declaration is not a source.** A `DECLARED` row (`distillation.md` §1: what this
+project sent) never joins the five outcomes with a fact: it never corroborates a row,
+never refines or supersedes one, never contests one. Against the ledger it is either
+consistent (`OK`) or it **diverges**: its assertion contradicts a non-superseded,
+non-DECLARED row, scopes overlapping → the DECLARED row alone becomes
+`DIVERGES <id>[, ..]`; the ledger row is not touched, because our own wrong statement
+puts nothing about the product in doubt. Two declarations that contradict each other
+are `CONTESTED` — both are still held by their recipients.
+
 The machine then verifies (the `graph` check): ids recompute, sources resolve and their
 spans exist, `CONTESTED` is **symmetric** (editing one cell to `OK` fails the check —
 the cheapest laundering), a `CONTESTED` pointer at a `SUPERSEDED` row is an error,
@@ -73,6 +82,9 @@ premise: signed amendments arrive later.
 | newer source vs a ruling | new set {new row, ruling row}; escalation shows the `basis:` |
 | member refined | the refining row inherits the member's contested relations (re-judged); counterparts rewritten to the new id |
 | corroboration of a contested member | source appended; the set untouched — more evidence is not new information, and the escalation form shows source counts |
+| a declaration contradicts the ledger | the DECLARED row → `DIVERGES <ledger ids>`; the ledger rows stay as they are; escalation names it |
+| a new send corrects it | the new DECLARED row; the divergent one → `SUPERSEDED <new-id>` (a declaration is superseded only by a later declaration) |
+| a ruling changes the decision | the ledger row → `SUPERSEDED <ruling-id>`; `check` then refuses the stale `DIVERGES` until the declaration is re-judged against the ruling: `OK` if it now agrees, `DIVERGES <ruling-id>` if not |
 | bundled row split (`distillation.md` §3) | N atomic rows `OK`, each on its narrowed span; the bundle → `SUPERSEDED <id1>[, <id2> ..]`, text intact; contested relations re-judged per successor |
 
 A superseded row keeps its `not-yet-honored-by` marker with its text. Copy the marker to each successor that still states behavior the code does not have; the analysis or shadow citing the predecessor's id satisfies the successor.
@@ -103,7 +115,11 @@ record like any claim-table edit.
 Escalations are presented **once, at the end of a run** — the pipeline never stops
 mid-ingest to ask. Each escalation names: the claims in the set, each one's source
 (reopenable), date and provenance, and one line on why the machine cannot decide
-("same subject, overlapping validity, GIVEN vs GIVEN, no newer source"). **A question
+("same subject, overlapping validity, GIVEN vs GIVEN, no newer source"). A divergence
+is escalated the same way, naming the recipient and the day it was sent: the
+practitioner corrects it with a new send or changes the decision. One limit stated
+out loud: `DIVERGES` is one-way, so unlike `CONTESTED` a hand edit back to `OK` has
+no counterpart to fail on — the diff review is what catches it. **A question
 that cannot fill this form is not askable** — it is the symptom that the answer is in
 the corpus and was not searched. Generic confirmations are not questions.
 
@@ -122,10 +138,15 @@ An `IMPORTED` row is a ruling made by the owner of a different project
 
 - It keeps its text, its span and its original `basis:` verbatim — the knowledge is not
   lost, and relabelling it `DERIVED` would make the row lie about its origin.
-- Its note must carry `imported_from:`. Unnamed, the class says nothing and the row is a
-  `RULING` with the label filed off; the validator refuses it.
-- **It cannot settle anything here.** `SUPERSEDED <id>` pointing at an `IMPORTED` row is
-  an error: nobody in this project granted that decision its authority.
-
-Re-ratification is one act, and it is you deciding: read it, write your own note with
-your own `basis:`, set `prov` to `RULING`.
+- It rests on a renamed copy of its note (`imported_<project>_<name>`) that carries
+  `imported_from:`. Unnamed, the class says nothing and the row is a `RULING` with the
+  label filed off; the validator refuses it.
+- **It cannot settle anything here.** `import` reopens the set it had settled: its former
+  members and the ruling arrive `CONTESTED` with each other. `SUPERSEDED <id>` pointing at
+  an `IMPORTED` row is an error: nobody in this project granted that decision its
+  authority.
+
+Ratification is the ruling procedure above, and it is you deciding: your own note with
+your own `basis:`, a `RULING` row on it, and every row `CONTESTED` with the imported one —
+transitively, when it sits in more than one set — `SUPERSEDED <your id>`, the imported row
+included. A `RULING` on a note that names a foreign origin is refused.

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

@@ -187,7 +187,10 @@ can block forever gets removed. **Log one row per completed review, PASS or FAIL
 logging only passes would erase exactly that evidence. The row goes in
 `ai_docs/audit/reviews/REVIEW_LOG.md` (create it if absent — `templates.md`):
 `| date | doc_key | tier | model | reviewer | findings_raised | findings_real | verdict | revise_rounds |`,
-with `tier` = `design` or `closure` in Standalone. **`model` records the capability
+with `tier` = `design` or `closure` in Standalone. In the code lens, a wrong behaviour
+the owner reports in a merged L3 change is one row too, tier `post-merge`, `model`
+`none (owner report)`, reviewer `owner`, the owner quoted in the notes: a defect
+record, not a review, so `benefit` keeps it out of every review figure. **`model` records the capability
 tier that actually ran** — `deep`, `light`, `economy`, `single (client exposes no
 choice)`, `below floor: <reason>`, or `none (not due)` on a NOT DUE row — never a provider name in doctrine (a project
 may of course write its own model names in its own log). Without it the floor above
@@ -195,6 +198,34 @@ is a belief: the row would say a gate ran and never whether it could do its job,
 the correlation with `revise_rounds` and `findings_real` — the only evidence the
 policy pays — could not be drawn.
 
+**The owner approves the design before the work starts (L3).** The reviewer judges
+whether the design holds and serves the Vision; only the owner can say whether it is
+what they meant beyond what the Vision wrote, and an intent error costs least before
+the work exists. So the final design PASS — final once any scoped re-review it owed
+has passed (§Review-driven corrections) — does not start the work: the agent
+presents the design and asks the owner whether to proceed, in the form
+`elicitation.md` §The form of a question gives a reserved approval. The presentation
+is a short summary — what the change does (the Functional Spec, or the lens's
+equivalent), for whom and through which surfaces (use cases, contract), what it
+touches (Impact), the threats and their mitigations, the review's verdict with any
+open findings — and the path of the full design. At the round cap, the hand-over the
+cap prescribes, followed by this one question, takes the place of the form, and the
+owner's answer settles both. An approval is recorded verbatim in the request record
+under a label that begins `design approved`; a no or a correction takes its own
+label, and the design goes back — where the revision changes what the review judged,
+moment 1 runs again on that part first (the delta rule above). Only after the
+approval does the ANALYSIS go `PLANNED` → `IN_PROGRESS` and the work start: code,
+drafting or production, by lens. An instruction given before the design was shown
+("carry on", "do the whole unit") does not approve it. Where a lens's own phases
+already have the owner approve the design — the marketing lens's strategy USER GATE
+— that gate is this approval, never a second question, and the lens's own unattended
+path applies. Otherwise, unattended, the unit is `BLOCKED on the user`
+(`elicitation.md` Unattended path), never approved by assumption; a late arrival
+(moment 1b) asks before any further work. Hybrid: the owner's approval of the
+`E-ISP`/`E-TDD` proposal in devPNT, under devPNT's own authorization rules, is this
+approval. In Standalone, `validate` notes an L3 ANALYSIS in implementation, started
+on or after 2026-10-31, whose request record holds no `design approved` entry.
+
 **One schema for both modes**, meaning one required CORE plus each mode's own
 **mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
 `tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.
@@ -285,6 +316,11 @@ The binding inputs, by review type:
   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.
+- **The constraint view comes last.** Where the ANALYSIS carries ids, the reviewer
+  derives the callers and behaviours first, then compares with
+  `sdlc_check.py constraints --unit <id>`: a constraint the design states and the
+  diff breaks is a finding. The view never replaces the ANALYSIS or the diff in the
+  request.
 - **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 or closure review of an L3/E3 unit, the request record**

package/skills/kb-agentic-skill/scripts/docs_site.py

@@ -615,6 +615,11 @@ class Grounds:
             return [{"kind": "untraceable", "path": rel}]
         seen = seen | {rel}
         if rel.startswith("corpus/given/"):
+            # F-084: a document this project SENT is our own declaration, not
+            # ground for a fact about the product.
+            side = self._meta(rel + ".meta.md")
+            if _v(side, "provenance").upper() == "DECLARED":
+                return [{"kind": "declared", "path": rel}]
             return [{"kind": "document", "path": rel}]
         if not _inside(self.docs, rel) or not (self.docs / rel).is_file():
             return [{"kind": "untraceable", "path": rel}]
@@ -643,6 +648,8 @@ def ground_class(leaves):
         return "statement"
     if "untraceable" in kinds:
         return "untraceable"
+    if "declared" in kinds:
+        return "declared"
     if "kb" in kinds:
         return "imported"
     return "documents"
@@ -707,12 +714,15 @@ def build_kb(docs):
             kind, rest = _kind(r)
             f = {"text": r["claim"], "valid": r["valid"], "qty": r["qty"], "about": r["about"],
                  "origin": (r["prov"] or "").strip().lower(), "topic": slug,
-                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested"}.get(kind, "ok")}
+                 "state": {"SUPERSEDED": "superseded", "CONTESTED": "contested",
+                           "DIVERGES": "diverges"}.get(kind, "ok")}
             if kind == "SUPERSEDED":
                 f["successors"] = _ids(rest)
                 f["chain_ends"] = chain_ends(r["id"], by_id)
             if kind == "CONTESTED":
                 f["with"] = _ids(rest)
+            if kind == "DIVERGES":
+                f["diverges_from"] = _ids(rest)
             srcs = []
             for src in r["source"].split(";"):
                 src = src.strip()
@@ -1246,7 +1256,9 @@ def chronology(docs, pages):
     text = _text(docs / rel) if (docs / rel).is_file() else None
     if text is not None:
         for row in sdlc_core.parse_review_log(text)[0]:
-            add(row["date"], "review", "%s — %s: %s" % (
+            # F-085: a `post-merge` row is the owner's defect report, not a review
+            kind = "defect" if row["tier"].lower().startswith("post-merge") else "review"
+            add(row["date"], kind, "%s — %s: %s" % (
                 row["doc_key"], row["tier"], row["verdict"]), rel)
     for p in sorted(docs.glob("architecture/ADR_*.md")):
         rel = "architecture/" + p.name
@@ -1269,7 +1281,9 @@ def chronology(docs, pages):
                 continue
             if kind == "source":
                 name = p.name[:-len(suffix)]
-                add(date, kind, name, rel, source=name)
+                # F-084: a DECLARED sidecar's date is the day it was SENT
+                sent = _v(fm, "provenance").upper() == "DECLARED"
+                add(date, "sent" if sent else kind, name, rel, source=name)
             else:
                 add(date, kind, title_of(rel, text), rel)
     # Most recent first. Within one day a document's later entry is the more recent