From 7736c0bde249526f820797491a0061aafd63a15f Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <hello@fromaitochitta.com>
Date: Sat, 20 Jun 2026 09:00:24 +0200
Subject: [PATCH] docs(llm-security): TRG/SIG/AST gap analysis + reviewed
 execution plan

Brief + 8-step trekplan for 3 new dep-free scanners: TRG (trigger-abuse),
SIG (signature engine over the decode pipeline), AST (Python AST taint).
Adversarial review fixed 3 blockers + 7 majors on draft 1 (59/D -> 86/B).

STATE.md prepped as a self-contained cold-start for /trekexecute next session.
Un-gitignore STATE.md (global ~/.claude rule overrides old polyrepo convention);
ignore generated plan annotation HTML. No scanner code yet.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V3s6WnubSSrFjAQTLQdVbG
---
 .gitignore |  8 ++++++--
 STATE.md   | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 STATE.md

diff --git a/.gitignore b/.gitignore
index d21a5ba..0fbc509 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,8 +15,9 @@ secrets.*
 .local/
 HANDOFF-FINDINGS.local.md
 
-# --- session/local state (gitignored per ~/.claude polyrepo-konvensjon) ---
-STATE.md
+# --- session/local state ---
+# NOTE: STATE.md is intentionally TRACKED and committed (global ~/.claude rule
+# overrides the old polyrepo gitignore convention). Do NOT add STATE.md here.
 REMEMBER.md
 ROADMAP.md
 TODO.md
@@ -26,3 +27,6 @@ NEXT-SESSION-PROMPT*.local.md
 *.local.sh
 .DS_Store
 .claude/
+
+# Voyage-generated plan annotation HTML (regenerable via annotate.mjs)
+docs/plans/*.html
diff --git a/STATE.md b/STATE.md
new file mode 100644
index 0000000..239cc90
--- /dev/null
+++ b/STATE.md
@@ -0,0 +1,43 @@
+# STATE — llm-security
+
+**Active focus:** EXECUTE the TRG/SIG/AST-gap plan — 3 new scanners (TRG, SIG, AST). Plan is written,
+reviewed, validated. Next session = cold start straight into `/trekexecute`.
+
+## COLD START — do this first
+1. `pwd` (should be repo root) and `git status` (expect clean; plan + brief committed).
+2. Read the plan: `docs/plans/trekplan-2026-06-20-TRG/SIG/AST-gap-analysis.md` (8 steps, validates clean).
+3. Run: **`/trekexecute docs/plans/trekplan-2026-06-20-TRG/SIG/AST-gap-analysis.md`**
+   (optionally `/trekexecute --validate <plan>` or `--dry-run <plan>` first to sanity-check).
+4. TDD per step (failing test first), commit per step within its scope-fence. Check push window before push.
+
+Build order: **TRG** (steps 1-2) → **SIG** (3-4) → **AST** (5-6) → **docs/packaging** (7) →
+**release v7.8.0** (8 — OPERATOR-GATED, confirm before doing; it's beyond the brief's scope).
+
+## How we got here
+- Brief: `docs/plans/TRG/SIG/AST-gap-analysis.md` (gap analysis vs NVIDIA/TRG/SIG/AST; all claims verified).
+- Lean Voyage chosen (trekplan→execute→review, no research). trekplan done; adversarial review caught
+  3 blockers + 7 majors on draft 1 (59/D) — all real — fixed → 86/B. The fixes are baked into the plan.
+
+## Verified gotchas (DO NOT re-derive — these broke draft 1)
+- Orchestrator is **`scanners/scan-orchestrator.mjs`** (NOT repo root). Siblings import as `./x.mjs`.
+  New scanner = export `scan(targetPath, discovery)`, add import + `{name,fn}` to SCANNERS (`:113-125`).
+- `severity.mjs` has **4 OWASP maps with ARRAY values** (`OWASP_MAP`/`_AGENTIC_`/`_SKILLS_`/`_MCP_`).
+  Add array entries to all four per scanner; assert with `deepEqual`. (e.g. `WFL: ['LLM02','LLM06']`)
+- `parseFrontmatter` already exists: `scanners/lib/yaml-frontmatter.mjs:13` (TRG reuses it).
+- **Zero npm deps** (no `dependencies` key in package.json — keep it that way). python3 = optional,
+  graceful `status:'skipped'` when absent. Emit via `finding()`/`scannerResult()` (`scanners/lib/output.mjs`).
+- Policy: add section to `DEFAULT_POLICY` (`scanners/lib/policy-loader.mjs`), read via `getPolicyValue`.
+- Distribution = Claude Code marketplace git-clone (whole repo), NOT npm — so `package.json` `files[]`
+  is moot for runtime; the `knowledge/` add in Step 7 is correctness-only.
+- Template scanner to copy: `scanners/memory-poisoning-scanner.mjs:386`. Tests: `node --test`,
+  committed `clean/`+`poisoned/` fixtures, `resetCounter()` in `beforeEach`. Full suite: `npm test`.
+
+## Continuity
+- STATE.md is canonical + committed (now un-gitignored — global rule). Voyage `.session-state.local.json`
+  is disposable per-plan scratch, gitignored (`*.local.json`).
+
+## Committed this session
+- `docs/plans/TRG/SIG/AST-gap-analysis.md` (brief), `docs/plans/trekplan-2026-06-20-...md` (plan),
+  `.gitignore` (un-ignore STATE.md; ignore `docs/plans/*.html`), this STATE.md.
+- Annotation HTML is gitignored (regenerable via Voyage `annotate.mjs`).
+- NO scanner code written yet — execution is next session.