From 1df20703074192e80056bbc065e9040c6d2d51c7 Mon Sep 17 00:00:00 2001 From: Nathaniel Ramm Date: Tue, 28 Apr 2026 08:21:46 +1000 Subject: [PATCH 1/5] Add verification gates design spec LOAD_AND_VERIFY pattern for every phase with external references. Forces Read, extracts proof value, halts on failure. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-04-28-verification-gates-design.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-28-verification-gates-design.md diff --git a/docs/superpowers/specs/2026-04-28-verification-gates-design.md b/docs/superpowers/specs/2026-04-28-verification-gates-design.md new file mode 100644 index 0000000..e705932 --- /dev/null +++ b/docs/superpowers/specs/2026-04-28-verification-gates-design.md @@ -0,0 +1,194 @@ +# Reference Verification Gates + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add LOAD_AND_VERIFY gates to every phase in SKILL.md that depends on external references, ensuring the LLM reads each file, proves it read it, and follows its instructions. + +**Architecture:** A `LOAD_AND_VERIFY` pseudocode pattern inserted before each phase's logic. Each gate names the file, forces a Read, extracts a proof value, displays a checkpoint, and halts if the file is missing or unreadable. No changes to the external reference files themselves. + +**Tech Stack:** Pseudocode in SKILL.md. + +--- + +## The Pattern + +```pseudocode +LOAD_AND_VERIFY(path, proof): + content = Read(path) + IF content IS empty OR unreadable: + HALT "Cannot proceed: {path} not found or empty" + extracted = proof(content) + DISPLAY "Loaded {path}: {extracted}" +``` + +The `proof` function is phase-specific — it extracts something that can only +come from actually reading the file. + +--- + +## Gates by Phase + +### Phase 1: Detect + +Currently says: `Follow lib/patterns/detection-algorithm.md.` + +Replace with: + +```pseudocode +DETECT(plugin_path): + LOAD_AND_VERIFY("lib/patterns/detection-algorithm.md", + proof: content contains FUNCTION definitions for + SCAN_METADATA_SOURCES, ELECT_CANONICAL, BUILD_METADATA_MODEL, + PRINT_INFERENCE_SUMMARY, CLASSIFY_SHAPE) + + # Execute the algorithm as defined in detection-algorithm.md + computed.sources = scan_metadata_sources(plugin_path) + IF len(computed.sources) == 0: DISPLAY "No plugin signals found."; EXIT + computed.canonical = elect_canonical(computed.sources) + computed.metadata = build_metadata_model(computed.sources) + computed.shape = classify_shape(computed.sources) + print_inference_summary(computed.metadata, computed.canonical) +``` + +### Phase 2: Inventory + +Currently says: `Follow lib/patterns/inventory.md.` + +Replace with: + +```pseudocode +INVENTORY(plugin_path, computed): + LOAD_AND_VERIFY("lib/patterns/inventory.md", + proof: content contains substeps 2.1 through 2.8) + + # Execute the inventory as defined in inventory.md + # Populates: computed.skills, computed.agents, computed.commands, + # computed.hooks, computed.manifest_results, computed.context_results, + # computed.sidecar_results, computed.frontmatter_results, + # computed.hook_results, computed.injection_results, + # computed.existing_files +``` + +### Phase 0b: Uplift Target + +Currently references UPLIFT_TARGETS inline. Add a gate: + +```pseudocode +INTENT_UPLIFT_TARGET(computed): + IF intent.mode != "uplift": RETURN + + LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: UPLIFT_TARGETS contains 3 entries: + skill-first, full-portable-plugin, curated-note-only) + + # Derive recommendation from shape (unchanged) + ... +``` + +### Phase 3: Score + +Currently says: `References lib/rubrics/rubric-framework.md and lib/rubrics/*.yaml.` + +Replace with: + +```pseudocode +SCORE(computed, platforms): + LOAD_AND_VERIFY("lib/rubrics/rubric-framework.md", + proof: content contains scoring formula with critical_pass/critical_count + threshold and 4 bands: strong, viable, partial, weak) + + FOR platform IN platforms: + LOAD_AND_VERIFY("lib/rubrics/" + platform + ".yaml", + proof: file parses as YAML with categories containing conditions + with id, type, check fields) + + rubric = load_yaml("lib/rubrics/" + platform + ".yaml") + ... +``` + +### Phase 5: Generate + +Currently uses `allowed_categories()` and `template_for_path()`. Add gates: + +```pseudocode +GENERATE(computed, intent): + LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: allowed_categories(computed.uplift_target) returns a non-empty list) + + LOAD_AND_VERIFY("lib/references/templates/registry.md", + proof: TEMPLATE_REGISTRY contains 12 entries) + + LOAD_AND_VERIFY("lib/patterns/manifest-generation.md", + proof: content contains 3 rendering modes: plain, conditional, builder + and per-schema GENERATE functions) + + allowed = allowed_categories(computed.uplift_target) + ... +``` + +### Phase 6: Port + +Currently says: `lib/patterns/hook-merging.md` + +Replace with: + +```pseudocode +PORT(computed, intent): + IF "4_hooks" NOT IN allowed: SKIP + + LOAD_AND_VERIFY("lib/patterns/hook-merging.md", + proof: content contains GENERATE_CURSOR_HOOKS, + GENERATE_CODEX_HOOKS, GENERATE_GEMINI_HOOK_GUIDANCE) + + # Execute hook porting as defined in hook-merging.md +``` + +### Phase 7: Document + +Currently says: `lib/templates/install-docs/` + +Replace with: + +```pseudocode +DOCUMENT(computed, intent): + LOAD_AND_VERIFY("lib/templates/install-docs/", + proof: directory contains install doc templates; + list files found) + + # Generate install documentation per platform from templates +``` + +### Phase 8: Bootstrap + +Currently says: `lib/patterns/bootstrapping.md` + +Replace with: + +```pseudocode +BOOTSTRAP(computed, intent): + IF computed.uplift_target == "curated-note-only": SKIP + + LOAD_AND_VERIFY("lib/patterns/bootstrapping.md", + proof: content contains steps 4.1 through 4.8) + + # Execute bootstrapping as defined in bootstrapping.md +``` + +--- + +## What Does NOT Change + +- **External reference files** — No changes to patterns, rubrics, registries, or templates +- **Phase pseudocode summaries** — The brief algorithm outlines stay as orientation +- **External references index** — The `> **External references:**` block at the top of SKILL.md stays + +--- + +## Verification + +After all edits: + +1. Every phase that previously said "Follow ..." or "References ..." now has a `LOAD_AND_VERIFY` block +2. `grep -c 'LOAD_AND_VERIFY' skills/plugin-portability/SKILL.md` returns at least 10 +3. No phase begins executing logic before its gate passes +4. Each gate's proof value is specific enough that it can only be satisfied by reading the actual file From a9e7ed0a5a07479cb57ac6a03d068d0082831679 Mon Sep 17 00:00:00 2001 From: Nathaniel Ramm Date: Tue, 28 Apr 2026 08:24:57 +1000 Subject: [PATCH 2/5] Fix verification gates spec per Codex adversarial review - Add GLOB_AND_VERIFY pattern for directories (Phase 7) - Add platform-api.md and per-platform spec gates to Phase 3 - Update verification checks Co-Authored-By: Claude Opus 4.6 (1M context) --- .../2026-04-28-verification-gates-design.md | 40 +++++++++++++++---- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/docs/superpowers/specs/2026-04-28-verification-gates-design.md b/docs/superpowers/specs/2026-04-28-verification-gates-design.md index e705932..e378c1e 100644 --- a/docs/superpowers/specs/2026-04-28-verification-gates-design.md +++ b/docs/superpowers/specs/2026-04-28-verification-gates-design.md @@ -10,7 +10,9 @@ --- -## The Pattern +## The Patterns + +### For files ```pseudocode LOAD_AND_VERIFY(path, proof): @@ -21,8 +23,19 @@ LOAD_AND_VERIFY(path, proof): DISPLAY "Loaded {path}: {extracted}" ``` +### For directories + +```pseudocode +GLOB_AND_VERIFY(pattern, proof): + files = Glob(pattern) + IF files IS empty: + HALT "Cannot proceed: no files matching {pattern}" + extracted = proof(files) + DISPLAY "Found {pattern}: {extracted}" +``` + The `proof` function is phase-specific — it extracts something that can only -come from actually reading the file. +come from actually reading the file or listing the directory. --- @@ -97,7 +110,15 @@ SCORE(computed, platforms): proof: content contains scoring formula with critical_pass/critical_count threshold and 4 bands: strong, viable, partial, weak) + LOAD_AND_VERIFY("lib/references/platform-api.md", + proof: content contains TYPE PlatformSpec and FUNCTION definitions for + tool_name, hook_event, strip_fields, supported_tools) + FOR platform IN platforms: + LOAD_AND_VERIFY("lib/references/platforms/" + platform + ".md", + proof: content contains REGISTRY[platform] with tools, hooks, + manifest, frontmatter sections) + LOAD_AND_VERIFY("lib/rubrics/" + platform + ".yaml", proof: file parses as YAML with categories containing conditions with id, type, check fields) @@ -151,11 +172,12 @@ Replace with: ```pseudocode DOCUMENT(computed, intent): - LOAD_AND_VERIFY("lib/templates/install-docs/", - proof: directory contains install doc templates; - list files found) + GLOB_AND_VERIFY("lib/templates/install-docs/**/*.md", + proof: list template files found, at least one per target platform) - # Generate install documentation per platform from templates + FOR platform IN intent.platforms: + LOAD_AND_VERIFY install doc template for platform + # Generate install documentation from template ``` ### Phase 8: Bootstrap @@ -188,7 +210,9 @@ BOOTSTRAP(computed, intent): After all edits: -1. Every phase that previously said "Follow ..." or "References ..." now has a `LOAD_AND_VERIFY` block -2. `grep -c 'LOAD_AND_VERIFY' skills/plugin-portability/SKILL.md` returns at least 10 +1. Every phase that previously said "Follow ..." or "References ..." now has a `LOAD_AND_VERIFY` or `GLOB_AND_VERIFY` block +2. `grep -c 'LOAD_AND_VERIFY\|GLOB_AND_VERIFY' skills/plugin-portability/SKILL.md` returns at least 12 3. No phase begins executing logic before its gate passes 4. Each gate's proof value is specific enough that it can only be satisfied by reading the actual file +5. Phase 3 gates include platform-api.md and per-platform spec files before rubric evaluation +6. Phase 7 uses GLOB_AND_VERIFY for the install-docs directory, not Read From 600054b54e839f2ff8373608ea8568866df85610 Mon Sep 17 00:00:00 2001 From: Nathaniel Ramm Date: Tue, 28 Apr 2026 08:26:44 +1000 Subject: [PATCH 3/5] Add verification gates implementation plan 8 tasks: gate pattern definitions, then gates for phases 1, 2, 0b, 3, 5, 6, 7, 8. Single file change in SKILL.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../plans/2026-04-28-verification-gates.md | 473 ++++++++++++++++++ 1 file changed, 473 insertions(+) create mode 100644 docs/superpowers/plans/2026-04-28-verification-gates.md diff --git a/docs/superpowers/plans/2026-04-28-verification-gates.md b/docs/superpowers/plans/2026-04-28-verification-gates.md new file mode 100644 index 0000000..ad995d2 --- /dev/null +++ b/docs/superpowers/plans/2026-04-28-verification-gates.md @@ -0,0 +1,473 @@ +# Verification Gates Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add LOAD_AND_VERIFY and GLOB_AND_VERIFY gates to every phase in SKILL.md that depends on external references, ensuring the LLM reads each file and proves it did. + +**Architecture:** Single file change — all edits in `skills/plugin-portability/SKILL.md`. Each task adds gates to one phase. The gate patterns (LOAD_AND_VERIFY for files, GLOB_AND_VERIFY for directories) are introduced in a new section before Phase 0a, then used throughout. + +**Tech Stack:** Markdown pseudocode. + +--- + +## File Map + +| File | Action | What changes | +|------|--------|-------------| +| `skills/plugin-portability/SKILL.md` | Modify | Add gate pattern definitions + gates to 8 phases | + +--- + +### Task 1: Add gate pattern definitions + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` (between External references block and Overview table) + +- [ ] **Step 1: Insert the gate patterns section** + +Find (lines 26-29): + +``` +--- + +## Overview +``` + +Replace with: + +``` +--- + +## Verification Gates + +Every phase that depends on an external reference must read the file and +prove it was loaded before executing phase logic. Two patterns: + +```pseudocode +LOAD_AND_VERIFY(path, proof): + content = Read(path) + IF content IS empty OR unreadable: + HALT "Cannot proceed: {path} not found or empty" + extracted = proof(content) + DISPLAY "Loaded {path}: {extracted}" + +GLOB_AND_VERIFY(pattern, proof): + files = Glob(pattern) + IF files IS empty: + HALT "Cannot proceed: no files matching {pattern}" + extracted = proof(files) + DISPLAY "Found {pattern}: {extracted}" +``` + +--- + +## Overview +``` + +- [ ] **Step 2: Verify** + +Run: `grep -n 'LOAD_AND_VERIFY\|GLOB_AND_VERIFY' skills/plugin-portability/SKILL.md | head -5` +Expected: lines showing the pattern definitions + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY and GLOB_AND_VERIFY gate pattern definitions" +``` + +--- + +### Task 2: Add gate to Phase 1 (Detect) + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Replace Phase 1 content** + +Find: + +``` +## Phase 1: Detect + +Follow `lib/patterns/detection-algorithm.md`. + +```pseudocode +DETECT(plugin_path): + computed.sources = scan_metadata_sources(plugin_path) + IF len(computed.sources) == 0: DISPLAY "No plugin signals found."; EXIT + computed.canonical = elect_canonical(computed.sources) + computed.metadata = build_metadata_model(computed.sources) + computed.shape = classify_shape(computed.sources) + print_inference_summary(computed.metadata, computed.canonical) +``` +``` + +Replace with: + +``` +## Phase 1: Detect + +```pseudocode +DETECT(plugin_path): + LOAD_AND_VERIFY("lib/patterns/detection-algorithm.md", + proof: content contains FUNCTION definitions for + SCAN_METADATA_SOURCES, ELECT_CANONICAL, BUILD_METADATA_MODEL, + PRINT_INFERENCE_SUMMARY, CLASSIFY_SHAPE) + + # Execute the algorithm as defined in detection-algorithm.md + computed.sources = scan_metadata_sources(plugin_path) + IF len(computed.sources) == 0: DISPLAY "No plugin signals found."; EXIT + computed.canonical = elect_canonical(computed.sources) + computed.metadata = build_metadata_model(computed.sources) + computed.shape = classify_shape(computed.sources) + print_inference_summary(computed.metadata, computed.canonical) +``` +``` + +- [ ] **Step 2: Verify** + +Run: `grep -A1 'Phase 1: Detect' skills/plugin-portability/SKILL.md` +Expected: no "Follow" line — gate is inside the pseudocode block + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY gate to Phase 1 (Detect)" +``` + +--- + +### Task 3: Add gate to Phase 2 (Inventory) + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Replace Phase 2 content** + +Find: + +``` +## Phase 2: Inventory + +Follow `lib/patterns/inventory.md`. Populates: + +- `computed.skills`, `computed.agents`, `computed.commands`, `computed.hooks` +- `computed.manifest_results`, `computed.context_results`, `computed.sidecar_results` +- `computed.frontmatter_results`, `computed.hook_results`, `computed.injection_results` +- `computed.existing_files` (for conflict detection during uplift) +``` + +Replace with: + +``` +## Phase 2: Inventory + +```pseudocode +INVENTORY(plugin_path, computed): + LOAD_AND_VERIFY("lib/patterns/inventory.md", + proof: content contains substeps 2.1 through 2.8) + + # Execute the inventory as defined in inventory.md + # Populates: computed.skills, computed.agents, computed.commands, + # computed.hooks, computed.manifest_results, computed.context_results, + # computed.sidecar_results, computed.frontmatter_results, + # computed.hook_results, computed.injection_results, + # computed.existing_files +``` +``` + +- [ ] **Step 2: Verify** + +Run: `grep -A1 'Phase 2: Inventory' skills/plugin-portability/SKILL.md` +Expected: no "Follow" line + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY gate to Phase 2 (Inventory)" +``` + +--- + +### Task 4: Add gate to Phase 0b (Uplift Target) + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Insert gate after the mode check** + +Find: + +``` +INTENT_UPLIFT_TARGET(computed): + IF intent.mode != "uplift": RETURN + + # Derive recommendation from shape +``` + +Replace with: + +``` +INTENT_UPLIFT_TARGET(computed): + IF intent.mode != "uplift": RETURN + + LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: UPLIFT_TARGETS contains 3 entries: + skill-first, full-portable-plugin, curated-note-only) + + # Derive recommendation from shape +``` + +- [ ] **Step 2: Verify** + +Run: `grep -A5 'INTENT_UPLIFT_TARGET' skills/plugin-portability/SKILL.md | grep 'LOAD_AND_VERIFY'` +Expected: one line with the uplift-targets gate + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY gate to Phase 0b (Uplift Target)" +``` + +--- + +### Task 5: Add gates to Phase 3 (Score) + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Replace Phase 3 intro and pseudocode opening** + +Find: + +``` +## Phase 3: Score + +Always runs full scoring. References `lib/rubrics/rubric-framework.md` and `lib/rubrics/*.yaml`. + +```pseudocode +SCORE(computed, platforms): + FOR platform IN platforms: + rubric = load_yaml("lib/rubrics/" + platform + ".yaml") +``` + +Replace with: + +``` +## Phase 3: Score + +Always runs full scoring. + +```pseudocode +SCORE(computed, platforms): + LOAD_AND_VERIFY("lib/rubrics/rubric-framework.md", + proof: content contains scoring formula with critical_pass/critical_count + threshold and 4 bands: strong, viable, partial, weak) + + LOAD_AND_VERIFY("lib/references/platform-api.md", + proof: content contains TYPE PlatformSpec and FUNCTION definitions for + tool_name, hook_event, strip_fields, supported_tools) + + FOR platform IN platforms: + LOAD_AND_VERIFY("lib/references/platforms/" + platform + ".md", + proof: content contains REGISTRY[platform] with tools, hooks, + manifest, frontmatter sections) + + LOAD_AND_VERIFY("lib/rubrics/" + platform + ".yaml", + proof: file parses as YAML with categories containing conditions + with id, type, check fields) + + rubric = load_yaml("lib/rubrics/" + platform + ".yaml") +``` + +- [ ] **Step 2: Verify** + +Run: `grep -c 'LOAD_AND_VERIFY' skills/plugin-portability/SKILL.md` +Expected: count increased (should be at least 8 at this point) + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY gates to Phase 3 (Score) including platform API" +``` + +--- + +### Task 6: Add gates to Phase 5 (Generate) + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Insert gates before the allowed_categories call** + +Find: + +``` +### Phase 5: Generate + +```pseudocode +allowed = allowed_categories(computed.uplift_target) +``` + +Replace with: + +``` +### Phase 5: Generate + +```pseudocode +LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: allowed_categories(computed.uplift_target) returns a non-empty list) + +LOAD_AND_VERIFY("lib/references/templates/registry.md", + proof: TEMPLATE_REGISTRY contains 12 entries) + +LOAD_AND_VERIFY("lib/patterns/manifest-generation.md", + proof: content contains 3 rendering modes: plain, conditional, builder + and per-schema GENERATE functions) + +allowed = allowed_categories(computed.uplift_target) +``` + +- [ ] **Step 2: Verify** + +Run: `grep -B1 -A1 'allowed = allowed_categories' skills/plugin-portability/SKILL.md` +Expected: LOAD_AND_VERIFY lines above the allowed= line + +- [ ] **Step 3: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add LOAD_AND_VERIFY gates to Phase 5 (Generate)" +``` + +--- + +### Task 7: Add gates to Phases 6, 7, 8 + +**Files:** +- Modify: `skills/plugin-portability/SKILL.md` + +- [ ] **Step 1: Replace Phase 6 (Port)** + +Find: + +``` +### Phase 6: Port -- `lib/patterns/hook-merging.md` + +Skipped if `"4_hooks" NOT IN allowed`. +``` + +Replace with: + +``` +### Phase 6: Port + +```pseudocode +PORT(computed, intent): + IF "4_hooks" NOT IN allowed: SKIP + + LOAD_AND_VERIFY("lib/patterns/hook-merging.md", + proof: content contains GENERATE_CURSOR_HOOKS, + GENERATE_CODEX_HOOKS, GENERATE_GEMINI_HOOK_GUIDANCE) + + # Execute hook porting as defined in hook-merging.md +``` +``` + +- [ ] **Step 2: Replace Phase 7 (Document)** + +Find: + +``` +### Phase 7: Document -- `lib/templates/install-docs/` + +Always runs (`"6_install"` is in all allowed sets). +``` + +Replace with: + +``` +### Phase 7: Document + +```pseudocode +DOCUMENT(computed, intent): + GLOB_AND_VERIFY("lib/templates/install-docs/**/*.md", + proof: list template files found, at least one per target platform) + + FOR platform IN intent.platforms: + LOAD_AND_VERIFY install doc template for platform + # Generate install documentation from template +``` + +Always runs (`"6_install"` is in all allowed sets). +``` + +- [ ] **Step 3: Replace Phase 8 (Bootstrap)** + +Find: + +``` +### Phase 8: Bootstrap -- `lib/patterns/bootstrapping.md` + +Skipped if `uplift_target == "curated-note-only"`. +``` + +Replace with: + +``` +### Phase 8: Bootstrap + +```pseudocode +BOOTSTRAP(computed, intent): + IF computed.uplift_target == "curated-note-only": SKIP + + LOAD_AND_VERIFY("lib/patterns/bootstrapping.md", + proof: content contains steps 4.1 through 4.8) + + # Execute bootstrapping as defined in bootstrapping.md +``` +``` + +- [ ] **Step 4: Verify total gate count** + +Run: `grep -c 'LOAD_AND_VERIFY\|GLOB_AND_VERIFY' skills/plugin-portability/SKILL.md` +Expected: at least 12 + +- [ ] **Step 5: Verify no bare "Follow" or "References" directives remain** + +Run: `grep -n '^Follow \|^References ' skills/plugin-portability/SKILL.md` +Expected: no output + +- [ ] **Step 6: Commit** + +```bash +git add skills/plugin-portability/SKILL.md +git commit -m "Add gates to Phases 6 (Port), 7 (Document), 8 (Bootstrap)" +``` + +--- + +### Task 8: Final verification + +- [ ] **Step 1: Run all verification commands** + +```bash +echo "=== 1. Gate count ===" && grep -c 'LOAD_AND_VERIFY\|GLOB_AND_VERIFY' skills/plugin-portability/SKILL.md +echo "=== 2. No bare Follow/References ===" && grep -n '^Follow \|^References ' skills/plugin-portability/SKILL.md +echo "=== 3. Pattern definitions present ===" && grep -n 'LOAD_AND_VERIFY(path, proof)' skills/plugin-portability/SKILL.md +echo "=== 4. GLOB pattern present ===" && grep -n 'GLOB_AND_VERIFY(pattern, proof)' skills/plugin-portability/SKILL.md +echo "=== 5. Platform API gate in Phase 3 ===" && grep -n 'platform-api.md' skills/plugin-portability/SKILL.md +echo "=== 6. GLOB in Phase 7 ===" && grep -n 'GLOB_AND_VERIFY.*install-docs' skills/plugin-portability/SKILL.md +echo "=== DONE ===" +``` + +Expected: check 1 returns >= 12, check 2 returns nothing, checks 3-6 each show at least one line. + +- [ ] **Step 2: Commit verification passing (if any final fixups needed)** + +No commit needed if all checks pass from Task 7. From 62adfad31918711d4c00854733a44aef8b7f5b58 Mon Sep 17 00:00:00 2001 From: Nathaniel Ramm Date: Tue, 28 Apr 2026 08:29:57 +1000 Subject: [PATCH 4/5] Add LOAD_AND_VERIFY and GLOB_AND_VERIFY gates to all phases Every phase that depends on external references now forces a Read, extracts a proof value, and halts if the file is missing. 16 gates across 8 phases. Phase 3 includes platform-api.md and per-platform spec gates. Phase 7 uses GLOB_AND_VERIFY for the install-docs directory. Co-Authored-By: Claude Opus 4.6 (1M context) --- skills/plugin-portability/SKILL.md | 118 +++++++++++++++++++++++++---- 1 file changed, 104 insertions(+), 14 deletions(-) diff --git a/skills/plugin-portability/SKILL.md b/skills/plugin-portability/SKILL.md index 84de559..5b2076a 100644 --- a/skills/plugin-portability/SKILL.md +++ b/skills/plugin-portability/SKILL.md @@ -26,6 +26,29 @@ Assess or uplift a plugin for multi-platform portability. Single entry point for --- +## Verification Gates + +Every phase that depends on an external reference must read the file and +prove it was loaded before executing phase logic. Two patterns: + +```pseudocode +LOAD_AND_VERIFY(path, proof): + content = Read(path) + IF content IS empty OR unreadable: + HALT "Cannot proceed: {path} not found or empty" + extracted = proof(content) + DISPLAY "Loaded {path}: {extracted}" + +GLOB_AND_VERIFY(pattern, proof): + files = Glob(pattern) + IF files IS empty: + HALT "Cannot proceed: no files matching {pattern}" + extracted = proof(files) + DISPLAY "Found {pattern}: {extracted}" +``` + +--- + ## Overview | Phase | Description | Runs | @@ -96,10 +119,14 @@ INTENT_UPFRONT(): ## Phase 1: Detect -Follow `lib/patterns/detection-algorithm.md`. - ```pseudocode DETECT(plugin_path): + LOAD_AND_VERIFY("lib/patterns/detection-algorithm.md", + proof: content contains FUNCTION definitions for + SCAN_METADATA_SOURCES, ELECT_CANONICAL, BUILD_METADATA_MODEL, + PRINT_INFERENCE_SUMMARY, CLASSIFY_SHAPE) + + # Execute the algorithm as defined in detection-algorithm.md computed.sources = scan_metadata_sources(plugin_path) IF len(computed.sources) == 0: DISPLAY "No plugin signals found."; EXIT computed.canonical = elect_canonical(computed.sources) @@ -112,12 +139,18 @@ DETECT(plugin_path): ## Phase 2: Inventory -Follow `lib/patterns/inventory.md`. Populates: - -- `computed.skills`, `computed.agents`, `computed.commands`, `computed.hooks` -- `computed.manifest_results`, `computed.context_results`, `computed.sidecar_results` -- `computed.frontmatter_results`, `computed.hook_results`, `computed.injection_results` -- `computed.existing_files` (for conflict detection during uplift) +```pseudocode +INVENTORY(plugin_path, computed): + LOAD_AND_VERIFY("lib/patterns/inventory.md", + proof: content contains substeps 2.1 through 2.8) + + # Execute the inventory as defined in inventory.md + # Populates: computed.skills, computed.agents, computed.commands, + # computed.hooks, computed.manifest_results, computed.context_results, + # computed.sidecar_results, computed.frontmatter_results, + # computed.hook_results, computed.injection_results, + # computed.existing_files +``` --- @@ -129,6 +162,10 @@ Runs AFTER detection (needs shape). Uplift mode only. INTENT_UPLIFT_TARGET(computed): IF intent.mode != "uplift": RETURN + LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: UPLIFT_TARGETS contains 3 entries: + skill-first, full-portable-plugin, curated-note-only) + # Derive recommendation from shape IF computed.shape == "bare-skill-repo" AND len(computed.skills) <= 3: recommended = "skill-first" @@ -161,11 +198,27 @@ INTENT_UPLIFT_TARGET(computed): ## Phase 3: Score -Always runs full scoring. References `lib/rubrics/rubric-framework.md` and `lib/rubrics/*.yaml`. +Always runs full scoring. ```pseudocode SCORE(computed, platforms): + LOAD_AND_VERIFY("lib/rubrics/rubric-framework.md", + proof: content contains scoring formula with critical_pass/critical_count + threshold and 4 bands: strong, viable, partial, weak) + + LOAD_AND_VERIFY("lib/references/platform-api.md", + proof: content contains TYPE PlatformSpec and FUNCTION definitions for + tool_name, hook_event, strip_fields, supported_tools) + FOR platform IN platforms: + LOAD_AND_VERIFY("lib/references/platforms/" + platform + ".md", + proof: content contains REGISTRY[platform] with tools, hooks, + manifest, frontmatter sections) + + LOAD_AND_VERIFY("lib/rubrics/" + platform + ".yaml", + proof: file parses as YAML with categories containing conditions + with id, type, check fields) + rubric = load_yaml("lib/rubrics/" + platform + ".yaml") FOR category IN rubric.categories: FOR condition IN category.conditions: @@ -228,6 +281,16 @@ Derived from `lib/references/uplift-targets/registry.md`. ### Phase 5: Generate ```pseudocode +LOAD_AND_VERIFY("lib/references/uplift-targets/registry.md", + proof: allowed_categories(computed.uplift_target) returns a non-empty list) + +LOAD_AND_VERIFY("lib/references/templates/registry.md", + proof: TEMPLATE_REGISTRY contains 12 entries) + +LOAD_AND_VERIFY("lib/patterns/manifest-generation.md", + proof: content contains 3 rendering modes: plain, conditional, builder + and per-schema GENERATE functions) + allowed = allowed_categories(computed.uplift_target) FOR platform IN intent.platforms: @@ -249,17 +312,44 @@ FOR platform IN intent.platforms: render(condition.template, computed.metadata) # fixes: {condition.id} ``` -### Phase 6: Port -- `lib/patterns/hook-merging.md` +### Phase 6: Port + +```pseudocode +PORT(computed, intent): + IF "4_hooks" NOT IN allowed: SKIP + + LOAD_AND_VERIFY("lib/patterns/hook-merging.md", + proof: content contains GENERATE_CURSOR_HOOKS, + GENERATE_CODEX_HOOKS, GENERATE_GEMINI_HOOK_GUIDANCE) + + # Execute hook porting as defined in hook-merging.md +``` + +### Phase 7: Document -Skipped if `"4_hooks" NOT IN allowed`. +```pseudocode +DOCUMENT(computed, intent): + GLOB_AND_VERIFY("lib/templates/install-docs/**/*.md", + proof: list template files found, at least one per target platform) -### Phase 7: Document -- `lib/templates/install-docs/` + FOR platform IN intent.platforms: + LOAD_AND_VERIFY install doc template for platform + # Generate install documentation from template +``` Always runs (`"6_install"` is in all allowed sets). -### Phase 8: Bootstrap -- `lib/patterns/bootstrapping.md` +### Phase 8: Bootstrap -Skipped if `uplift_target == "curated-note-only"`. +```pseudocode +BOOTSTRAP(computed, intent): + IF computed.uplift_target == "curated-note-only": SKIP + + LOAD_AND_VERIFY("lib/patterns/bootstrapping.md", + proof: content contains steps 4.1 through 4.8) + + # Execute bootstrapping as defined in bootstrapping.md +``` ### Phase 9: Summary From f6e207784aec2b7a458d966ac63663fd07918386 Mon Sep 17 00:00:00 2001 From: Nathaniel Ramm Date: Tue, 28 Apr 2026 08:32:13 +1000 Subject: [PATCH 5/5] Add verification gates principle to pseudocode-principles.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit External references must be read, proven, and followed — not just hinted at. LOAD_AND_VERIFY for files, GLOB_AND_VERIFY for directories. Documents what makes a good proof and when gates are needed. Co-Authored-By: Claude Opus 4.6 (1M context) --- lib/principles/pseudocode-principles.md | 45 +++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/lib/principles/pseudocode-principles.md b/lib/principles/pseudocode-principles.md index 1b62730..6f85b3a 100644 --- a/lib/principles/pseudocode-principles.md +++ b/lib/principles/pseudocode-principles.md @@ -1,8 +1,9 @@ # Pseudocode & Registry Principles -Decision frameworks for how structured data and pseudocode are organized -in this repo. Two concerns: when to create a registry, and how to write -pseudocode in rubric checks and pattern files. +Decision frameworks for how structured data, pseudocode, and external +references are organized in this repo. Three concerns: when to create a +registry, how to write pseudocode, and how to enforce that external +references are actually read. --- @@ -95,3 +96,41 @@ Inlining examples: | `uses_mcp_servers(".")` | `file_exists(".mcp.json") or config references MCP servers` | | `contains_verification_guidance(content)` | `content includes steps to verify the plugin loaded` | | `skill_name_referenced(content, skill)` | `name from parse_frontmatter(skill) appears in content` | + +--- + +## Verification Gates + +When a skill or pattern file delegates to an external reference ("follow +detection-algorithm.md", "see hook-merging.md"), the executing LLM may +skip reading the file and hallucinate the algorithm. A prose hint like +"Follow X" is not a directive — it's a suggestion the LLM can ignore. + +### The principle + +Every phase that depends on an external reference must **read the file, +prove it read it, and then follow the instructions**. No phase logic +executes before its gate passes. + +### Two patterns + +**LOAD_AND_VERIFY** — for files. Read the file, extract a proof value +that can only come from actually reading it (function names, entry counts, +structural markers), display a checkpoint. + +**GLOB_AND_VERIFY** — for directories. Glob for expected files, verify +the list is non-empty and covers the expected scope, display what was found. + +### What makes a good proof + +The proof must be **specific enough that it cannot be guessed**. Bad proofs: +"file exists" (trivially true). Good proofs: "content contains FUNCTION +definitions for X, Y, Z" or "YAML parses with N conditions across 7 +categories." + +### When to use + +- A skill phase says "follow" or "see" an external file — add a gate +- A pseudocode block calls functions defined in another file — gate that file +- A phase iterates over files in a directory — GLOB_AND_VERIFY first +- A phase only uses self-contained logic (no external refs) — no gate needed