git:20261006.fe13693 to git:20261007.aa8e844

38 added, 8 removed. Audit A to A.

---

name: Transitrix Knowledge Store

description: Ingest raw source material into the OKF single-repo MVP knowledge store — assess, archive, route to the OKF track (extract drafts → verify → human review → promote to knowledge/) and/or the Canon track (extract Transitrix primitives → PR to canon/), and log every decision.

when_to_use: User says "ingest this document", "add this to the knowledge store", "extract knowledge objects from this", "route this to canon", or drops a file into `_intake/inbox/` and wants it processed.

min_version: "6.0.0"

allowed-tools: Read, Write, Edit, Bash, Glob, Grep

---

# Transitrix Knowledge Store Skill

- Processes raw source material through the OKF single-repo MVP knowledge store. All work is done by the agent using Read/Write/Edit tools — no external CLI required. A human reviews and approves before anything lands in `knowledge/` or `canon/`.

+ Processes raw source material through the OKF single-repo MVP knowledge store. Extraction and curation use the agent's Read/Write/Edit tools; setup requires the shared intake-profile preflight from `@transitrix/ingest-cli`. A human reviews and approves before anything lands in `knowledge/` or `canon/`.

---

## The one rule

**Propose, never promote unilaterally.** For the OKF track, the agent writes drafts to `_intake/drafts/` only — never directly to `knowledge/`. For the Canon track, the agent opens a PR to `canon/` — it never merges it. The human gate is the only admission authority.

**Run the quality gates before and after promotion.** After writing drafts (Step 4a) and again after promoting approved objects to `knowledge/` (Step 4d), run the knowledge-store linter and fix every error:

```bash

python3 tools/knowledge_store_lint.py .

```

The linter enforces Gates 1–6 from [patterns/knowledge-store.md §Quality gates](../../../patterns/knowledge-store.md). Errors block promotion; warnings require explicit human acknowledgment in `_intake/log.md`. See [tests/README.md](tests/README.md) for the KS-001..017 code reference.

---

## Step 0 — Check the MVP structure

+ Before any write, select the **knowledge-store** deployment profile using the

+ [compatibility contract](../../../patterns/knowledge-store.md#deployment-profiles-and-intake-compatibility).

+ Run the shared CLI preflight (see that contract for local installation):

+ ```bash

+ transitrix-intake-profile check <repo-root> --profile knowledge-store

+ transitrix-intake-profile select <repo-root> --profile knowledge-store

+ ```

+ Stop if unavailable or refused; do not scaffold, move sources or change ignore

+ rules to bypass a conflict. Ordinary ingest/reg-intel belongs in a separate

+ workspace. Commit `_intake/profile.json` with setup. On later runs repeat the

+ read-only check before any write, including when the marker already exists.

Verify the repo has the expected layout:

```

_intake/

inbox/ ← source files waiting for processing

originals/ ← raw source files (gitignored)

processed/ ← OKF source-document records (committed)

drafts/ ← proposer output (Gate 6 — not cited; not promoted)

log.md ← all events: [route] / [admit] / [ambig] / [conflicts] / [assert]

knowledge/

index.md ← bundle index (auto-maintained)

<concept>.md ← individual OKF knowledge objects

```

- If `_intake/` or `knowledge/` are missing, scaffold them now. Create `_intake/drafts/` if absent. Copy the initialisation content from [patterns/knowledge-store.md §Templates](../../../patterns/knowledge-store.md). Add gitignore entries for `_intake/inbox/*` and `_intake/originals/*` (drafts MAY be committed for audit or gitignored for ephemeral runs).

+ If `_intake/` or `knowledge/` are missing, scaffold them now. Create `_intake/drafts/` if absent. Copy the initialisation content from [patterns/knowledge-store.md §Templates](../../../patterns/knowledge-store.md). Add gitignore entries for `_intake/inbox/*` and `_intake/originals/*` (drafts MAY be committed for audit or gitignored for ephemeral runs). Never ignore `_intake/processed/`. Re-run the profile check after setup and before committing; explicitly verify each new source-record path is not ignored before writing it.

---

## Step 1 — Assess the document

Read the source document from `_intake/inbox/`. Determine:

- **`confidence:`** — curator's epistemic assessment of the signal quality:

- `observed` — first-hand account, direct evidence, system output

- `inferred` — derived from evidence; logical but not stated explicitly

- `assumed` — working assumption, hearsay, or low-corroboration claim

- **`tracks:`** — which ingestion tracks apply (one or both):

- `okf` — contains knowledge objects: insights, findings, concepts, questions worth curating

- `canon` — contains Transitrix primitives: DRIVERs, GOALs, CHANGEs, CAPABILITYs, etc.

- **Proposed `description:`** — one-sentence summary of the document

State your assessment to the user before proceeding.

---

## Step 2 — Archive to processed/

Copy the source file reference to `_intake/processed/` as an OKF source-document record using the template at [patterns/knowledge-store-templates/okf-source-document.md](../../../patterns/knowledge-store-templates/okf-source-document.md).

Fill in:

- `title:` — document filename or stated title

- `description:` — one-sentence summary from Step 1

- `source:` — original file path or URI (e.g. `_intake/inbox/filename.md` or a web URL)

- `source_hash:` — SHA-256 of the source file (`sha256sum` / `Get-FileHash`)

- `created_at:` — today's date

- `confidence:` — from Step 1

- `tags:` — inferred topic tags

- `tracks:` — from Step 1

Filename convention: `YYYY-MM-DD-<slug>.md` where slug is a 3–5 word kebab-case summary.

For a reissued source, use a fresh processed-record and original-file path even when the date or filename matches an earlier revision. Preserve the earlier record, original, and hash.

Move the source file from `_intake/inbox/` to `_intake/originals/` (gitignored, kept for traceability).

---

## Step 3 — Log the routing decision

Append to `_intake/log.md`:

```markdown

## YYYY-MM-DD

- [route] `<processed-filename>` → tracks: [okf, canon] | confidence: observed | <one-line reason>

```

---

## Step 4 — OKF track (if `okf` in tracks)

### 4a — Propose drafts (Gate 6)

Read the source document from `_intake/originals/` (or the processed record). Using the extraction prompt at [prompts/extract-okf.md](prompts/extract-okf.md), extract candidate knowledge objects and **write each to `_intake/drafts/<slug>.md`** using the template at [patterns/knowledge-store-templates/okf-knowledge-object-draft.md](../../../patterns/knowledge-store-templates/okf-knowledge-object-draft.md).

Each draft:

- has a clear, discrete idea (one concept per file)

- carries `type:`, `confidence:`, `source:`, `description:` as for promoted objects

- carries `review_status:` — `ready` (grounded, linter-clean candidate), `ambiguous` (needs human judgement; set non-empty `ambiguity_note:`), or `blocked` (too vague to review; skip by default)

- carries `mapping:` / `conflicts_with:` when relating to existing knowledge (Gate 2)

For re-curation, choose a fresh filename and set `supersedes` to the current admitted object. Leave that object unchanged during drafting; a missing-backlink `KS-019` warning is expected until admission (Gate 2.1).

Do **not** write to `knowledge/` at this step.

### 4b — Verify drafts

Follow [prompts/verify-drafts.md](prompts/verify-drafts.md). Run `python3 tools/knowledge_store_lint.py .` and fix every **error** on draft paths before presenting the batch. Then present drafts grouped by `review_status` (ready / ambiguous / blocked). State what was skipped and why.

### 4c — User review gate

Wait for the user to approve, reject, or revise each draft. Do not promote anything to `knowledge/` until you have explicit approval. For ambiguous drafts, log a hold (Step 4f) until resolved.

### 4d — Dispose approved drafts

For each approved draft, copy to `knowledge/<slug>.md` using [patterns/knowledge-store-templates/okf-knowledge-object.md](../../../patterns/knowledge-store-templates/okf-knowledge-object.md). **Remove** `review_status` and `ambiguity_note` from frontmatter. Delete the corresponding file under `_intake/drafts/`.

Never overwrite an existing knowledge-object path. For approved re-curation, create the successor and add `superseded_by` to its predecessor in the same change, updating only that predecessor’s lifecycle `timestamp` alongside the pointer. Preserve its body and all assertion metadata, including any earlier `supersedes`. Record the source revision and both object paths in the `[admit]` log entry; keep both index rows.

Run `python3 tools/knowledge_store_lint.py .` again. Fix every **error** before proceeding. Surface **warnings** (KS-008, KS-010, KS-013) for explicit acknowledgment.

### 4e — Regenerate knowledge/index.md

After all approved objects are promoted, update `knowledge/index.md` to include new or updated rows. Do not remove rows for existing objects not touched in this ingestion.

### 4f — Log admit decisions

Append to `_intake/log.md` for each promoted object:

```markdown

- [admit] `<knowledge-object-filename>` ← `<source-document-filename>` | approved | <one-line note>

```

For each rejected draft:

```markdown

- [admit] rejected: "<title>" | reason: <one-line reason>

```

For each ambiguous draft held for review:

```markdown

- [ambig] `<draft-filename>` | <ambiguity_note one-liner> | held for review

```

For each object held because it **conflicts** with existing knowledge (not admitted until reviewed):

```markdown

- [conflicts] `<knowledge-object-filename>` vs `<conflicts_with-target>` | held for review | <one-line note>

```

---

## Step 5 — Canon track (if `canon` in tracks)

### 5a — Extract Transitrix primitives

Using the extraction prompt at [prompts/extract-canon.md](prompts/extract-canon.md), identify candidate Transitrix elements (DRIVER, GOAL, CHANGE, CAPABILITY, ACTOR, ROLE, PROCESS, APPLICATION, PRODUCT, etc.) and typed relations. Be conservative on relations — only propose a relation when the source explicitly states the connection.

- For each candidate, draft a YAML block in the format expected by `canon/elements/<type>/`:

+ Draft candidate YAML blocks in a YAML review file under `_intake/drafts/` (for example `canon-candidates.yaml`), outside `canon/`. These are extraction proposals, not valid canonical elements yet:

```yaml

type: DRIVER

- id: DRIV-NNN # assign the next available integer

+ id: <TYPE>-TBD # review placeholder, never an admitted ID

name: ""

description: ""

derived_from: [<processed-source-document-path>]

admitted_to: pending

extraction_confidence: high | medium | low

```

- ### 5b — Open PR

+ ### 5b — Review IDs, validate, then open PR

- Create a branch `knowledge-store/ingest-<YYYY-MM-DD>-<slug>` and commit the candidate YAML files. Open a PR titled `[Knowledge Store] Ingest: <source-document-title>`.

+ 1. Present the draft candidates to the human reviewer. Keep `admitted_to: pending`;

+ no admission record is invented. Resolve duplicate candidates against existing

+ canon before reserving IDs.

+ 2. During review, replace every `*-TBD` placeholder with a unique ID under

+ [IDS_AND_REFERENCES §§1–2](../../../notations/IDS_AND_REFERENCES.md), including

+ the CAPABILITY V/H exception. Resolve every relation endpoint to a reviewed ID.

+ A placeholder is never a canonical ID, filename or admitted reference.

+ 3. Prepare reviewed candidates at the TYPE's canonical placement from

+ [ELEMENT_PRIMITIVES §4](../../../notations/ELEMENT_PRIMITIVES.md), not a generic

+ per-type path. Apply the required envelope and TYPE fields; retain provenance

+ and pending status until human admission under [CONTRACT §6](../../../notations/CONTRACT.md).

+ 4. Run the adopter's canonical validators for ID uniqueness, reference consistency,

+ required fields and placement. Unresolved placeholders or failed checks block

+ the canon PR; keep those proposals in the draft YAML review file. Review flags

+ such as `extraction_confidence` never become admitted canon fields.

+ Create a branch `knowledge-store/ingest-<YYYY-MM-DD>-<slug>` and commit only the reviewed, validated candidate files for human admission. Open a PR titled `[Knowledge Store] Ingest: <source-document-title>`.

PR body must include:

- Link to the processed source-document record

- Table of proposed elements with type, name, and extraction_confidence

- Note on any relations proposed

- - Instruction: "Review, revise IDs to avoid conflicts, and merge when satisfied."

+ - Instruction: "Review the assigned IDs, resolved references, provenance and validation results; complete admission only when satisfied. Never merge unresolved placeholders or pending proposals as admitted canon."

### 5c — Log assertion outcome (after PR is merged or closed)

Once the user reports the PR outcome, append to `_intake/log.md`:

```markdown

- [assert] PR #<number> merged | admitted: [<DRIVER-NNN>, <GOAL-NNN>, ...] | source: <processed-filename>

```

Or for rejected:

```markdown

- [assert] PR #<number> closed without merge | reason: <one-line>

```

---

## What this skill does NOT do

- Does not merge PRs. The canon gate is always a human.

- Does not write to `knowledge/` before user review of drafts (Gate 6 — drafts land in `_intake/drafts/` only).

- - Does not assign `extraction_confidence: high` to relations — relations are flagged `medium` or lower unless the source text is unambiguous.

+ - Does not assign `extraction_confidence: high` to relations — relations are always flagged `medium` or lower and require human validation.

- Does not remove or rewrite existing knowledge objects. Re-curation adds a successor and lifecycle metadata under Gate 2.1.

- Does not process multiple documents in the same run unless explicitly asked — one source per run keeps the log clean.