Add instruction-fidelity guardrail across prompts

.github/copilot-instructions.md

@@ -92,18 +92,20 @@ adding or modifying any component:
 
 1. Update the component's YAML frontmatter
 2. Update `manifest.yaml` to match
-3. The CI check (`tests/validate-manifest.py`) validates that every
-   template's `protocols` list in the manifest matches its frontmatter
+3. The CI checks (`tests/validate-manifest.py` and
+   `tests/validate-instruction-fidelity.py`) validate manifest/template
+   protocol sync and universal guardrail coverage
 
 ## CI
 
 ```bash
-# Validate manifest ↔ template protocol sync (the only CI check)
+# Validate manifest ↔ template protocol sync and universal guardrails
 python tests/validate-manifest.py
+python tests/validate-instruction-fidelity.py
 ```
 
-Triggered on push/PR when `manifest.yaml`, `templates/**`, or
-`tests/validate-manifest.py` change.
+Triggered on push/PR when `manifest.yaml`, component files, or the
+validation scripts change.
 
 ## Testing
 

.github/workflows/validate-manifest.yml

@@ -13,6 +13,7 @@ on:
       - 'taxonomies/**'
       - 'templates/**'
       - 'tests/validate-manifest.py'
+      - 'tests/validate-instruction-fidelity.py'
       - 'tests/validate-graph-integrity.py'
       - 'cli/**'
   pull_request:
@@ -24,6 +25,7 @@ on:
       - 'taxonomies/**'
       - 'templates/**'
       - 'tests/validate-manifest.py'
+      - 'tests/validate-instruction-fidelity.py'
       - 'tests/validate-graph-integrity.py'
       - 'cli/**'
 
@@ -59,6 +61,20 @@ jobs:
       - name: Validate graph integrity
         run: python tests/validate-graph-integrity.py
 
+  validate-instruction-fidelity:
+    name: Check instruction-fidelity coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Validate instruction-fidelity coverage
+        run: python tests/validate-instruction-fidelity.py
+
   cli-smoke-test:
     name: CLI smoke test (launch path)
     runs-on: ubuntu-latest

CATALOG.md

@@ -10,7 +10,7 @@
 | Layer | Count | Description |
 |-------|-------|-------------|
 | Personas | 15 | Domain expert identities |
-| Protocols | 56 | Guardrails (5), Analysis (18), Reasoning (33) |
+| Protocols | 57 | Guardrails (6), Analysis (18), Reasoning (33) |
 | Formats | 24 | Output structure definitions |
 | Taxonomies | 5 | Classification schemes |
 | Templates | 71 | Task orchestration prompts |
@@ -159,11 +159,12 @@
 
 ## Protocols
 
-### guardrails (5)
+### guardrails (6)
 
 | Protocol | Language | Used by | Description |
 |----------|----------|---------|-------------|
 | `anti-hallucination` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Prevents fabrication. Enforces epistemic labeling (KNOWN/INFERRED/ASSUMED), uncertainty disclosure, and source attribution. Apply to all tasks. |
+| `instruction-fidelity` | — | All templates | Universal execution contract. Requires the model to follow user intent, constraints, ambiguity-escalation rules, and approval gates as written instead of silently reinterpreting the task. |
 | `self-verification` | — | `author-requirements-doc`, `author-architecture-spec`, `interactive-design`, `author-north-star`, `author-design-doc`, `author-validation-plan`, `reverse-engineer-requirements`, `audit-traceability`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `audit-spec-invariants`, `diff-specifications`, `author-interface-contract`, `audit-interface-contract`, `validate-budget`, `extract-rfc-requirements`, `reconcile-requirements`, `extract-invariants`, `author-rfc`, `author-presentation`, `author-implementation-prompt`, `author-test-prompt`, `author-workflow-prompts`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `profile-session`, `classify-findings`, `review-code`, `review-cpp-code`, `exhaustive-bug-hunt`, `reconstruct-behavior`, `review-schematic`, `validate-simulation`, `review-bom`, `review-layout`, `audit-link-budget`, `review-enclosure`, `design-schematic`, `design-pcb-layout`, `emit-manufacturing-artifacts`, `hardware-design-workflow`, `discover-tests-for-changes`, `scaffold-test-project`, `plan-implementation`, `author-agent-instructions`, `extend-library`, `decompose-prompt`, `audit-library-consistency`, `audit-library-health`, `author-pipeline`, `triage-issues`, `triage-pull-requests`, `root-cause-ci-failure`, `author-release`, `review-infrastructure`, `generate-commit-message`, `evolve-protocol`, `analyze-protocol-conflicts`, `author-protocol-validation`, `engineering-workflow`, `collaborate-requirements-change`, `generate-spec-changes`, `generate-implementation-changes`, `audit-spec-alignment`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Quality gate requiring the LLM to verify its own output before finalizing. Sampling checks, citation audits, coverage confirmation, consistency checks. |
 | `operational-constraints` | — | `reverse-engineer-requirements`, `audit-code-compliance`, `audit-test-compliance`, `audit-integration-compliance`, `author-presentation`, `investigate-bug`, `find-and-fix-bugs`, `fix-compiler-warnings`, `investigate-security`, `review-code`, `review-cpp-code`, `reconstruct-behavior`, `discover-tests-for-changes`, `audit-library-health`, `engineering-workflow`, `generate-implementation-changes`, `audit-implementation-alignment`, `spec-extraction-workflow`, `maintenance-workflow` | Governs how the LLM scopes work, uses tools, manages context, and prefers deterministic analysis. Prevents over-ingestion and ensures reproducibility. |
 | `minimal-edit-discipline` | — | `find-and-fix-bugs`, `fix-compiler-warnings` | Constrains code modifications to be minimal, type-preserving, encoding-safe, and verifiable. Prevents collateral damage from automated fixes, refactoring, and code generation. |
@@ -446,4 +447,3 @@ Domain-agnostic incremental engineering workflow with human-in-the-loop review.
 - **`triage-report`** → `discover-tests-for-changes`, `triage-issues`, `triage-pull-requests`
 - **`validation-plan`** → `author-validation-plan`, `author-test-prompt`
 
-

CONTRIBUTING.md

@@ -117,9 +117,9 @@ NOT mean "can optionally be added to". Use the following values:
 
 | Value | Meaning |
 |-------|---------|
-| `all` | Every template should apply this protocol (reserved for cross-cutting guardrails such as `anti-hallucination`). |
+| `all` | Every template should apply this protocol (reserved for cross-cutting guardrails such as `anti-hallucination` and `instruction-fidelity`). |
 | `[]` *(empty list)* | This protocol is intended for standalone / manual composition and is not automatically included by any template. Document this in the protocol file itself. |
-| `[template-a, template-b]` | These specific templates always include this protocol in their `protocols:` frontmatter. Keep this list in sync with the template definitions and their `protocols` entries in `manifest.yaml`. The CI check (`tests/validate-manifest.py`) currently validates only that `manifest.yaml` and template `protocols:` frontmatter match; it does not enforce `applicable_to` bidirectionally. |
+| `[template-a, template-b]` | These specific templates always include this protocol in their `protocols:` frontmatter. Keep this list in sync with the template definitions and their `protocols` entries in `manifest.yaml`. The CI checks (`tests/validate-manifest.py` and `tests/validate-instruction-fidelity.py`) validate manifest/frontmatter sync and required universal guardrails, but they do not enforce `applicable_to` bidirectionally. |
 
 **Optional protocols** — protocols a template can optionally include via
 `additional_protocols` in an assembled prompt — should NOT be listed in

README.md

@@ -412,6 +412,7 @@ personas, analysis protocols, and task templates.
 | Name | Description |
 |------|-------------|
 | `anti-hallucination` | Prevents fabrication, enforces epistemic labeling |
+| `instruction-fidelity` | Follow user intent and prompt constraints as written; ask on material ambiguity |
 | `self-verification` | Quality gate — LLM verifies its own output before finalizing |
 | `operational-constraints` | Scoping, tool usage, deterministic analysis, reproducibility |
 | `minimal-edit-discipline` | Minimal, type-preserving, encoding-safe code modifications |

bootstrap.md

@@ -25,6 +25,25 @@ You are the **composition engine** for PromptKit. Your job is to:
 3. Assemble them into a complete, ready-to-use prompt.
 4. Present the assembled prompt to the user for review and customization.
 
+## Instruction Fidelity Contract
+
+These rules govern the entire bootstrap workflow and every prompt you
+assemble from this repository:
+
+1. **Follow the user's requested outcome literally.** Do NOT substitute a
+   nearby task, a broader audit, a narrower artifact, or a "better"
+   interpretation than what the user asked for.
+2. **Treat constraints and non-goals as binding.** Output mode, scope,
+   exclusions, approval gates, and required artifact types are not optional.
+3. **Escalate material ambiguity instead of improvising.** If unresolved
+   ambiguity would change template choice, output mode, scope, non-goals,
+   implementation approach, or deliverable structure, STOP and ask.
+4. **Obey phase ordering and wait states exactly as written.** Do NOT skip,
+   merge, reorder, or condense away steps, gates, or STOP / WAIT rules.
+5. **Self-check compliance before finalizing.** Verify that every active
+   MUST / MUST NOT and approval gate remains satisfied in the assembled
+   prompt or generated instruction file.
+
 ## How to Begin
 
 1. **Read the manifest** at `manifest.yaml` to discover all available components.
@@ -168,6 +187,10 @@ You are the **composition engine** for PromptKit. Your job is to:
    not edit template or component body text to store these notes. Skip
    this check for trivial inputs (file paths, yes/no, platform
    selections).
+   If the ambiguity would change template selection, output mode,
+   deliverable structure, scope boundaries, or non-goals, do NOT proceed
+   with prompt assembly until it is resolved or explicitly preserved as
+   an `[OPEN QUESTION]` in a mode that allows unresolved branches.
 7. **Ask for the target project directory.** The output files must be written
    to the **user's project**, not to the PromptKit repository. Ask the user
    for the path to their target project root. Suggest a sensible default
@@ -219,6 +242,10 @@ known-safe patterns, checklists, and operational guidance — MUST be preserved
 **exactly as written** in the source file (apart from the parameter values
 you substitute).
 
+This preservation requirement explicitly includes instruction-priority
+rules, ambiguity-escalation rules, approval gates, and STOP / WAIT
+directives. Do NOT paraphrase or compress them.
+
 **Do NOT summarize, abbreviate, or condense** component content when
 assembling raw prompts. If a protocol has 8 phases with detailed sub-steps,
 all 8 phases and all sub-steps must appear in the assembled output. If a
@@ -273,6 +300,9 @@ skill file:
 - Opens with `<!-- Generated by PromptKit — edit with care -->`
 - Contains condensed persona or protocol directives (condensation applies
   **only** to this output mode, never to raw prompt output)
+- Preserves the `instruction-fidelity` execution contract verbatim in the
+  root / global instruction file. Do NOT condense, paraphrase, or merge
+  away its priority rules, ambiguity rules, or approval-gate language.
 - Uses second-person directives throughout ("You are…", "When you encounter…")
 - Does **NOT** include PromptKit section headers (`# Identity`, `# Reasoning Protocols`, etc.)
 - Is self-contained and independently coherent

docs/architecture.md

@@ -214,8 +214,9 @@ When adding or modifying any component:
 
 1. Update the component's YAML frontmatter
 2. Update `manifest.yaml` to match
-3. CI (`tests/validate-manifest.py`) validates that every template's
-   `protocols` list in the manifest matches its frontmatter
+3. CI validates both manifest/template protocol sync
+   (`tests/validate-manifest.py`) and universal instruction-fidelity
+   coverage (`tests/validate-instruction-fidelity.py`)
 
 ## The Assembly Engine
 
@@ -316,13 +317,15 @@ See [Pipeline Guide](pipeline-guide.md) for a detailed walkthrough.
 
 ## CI
 
-The only automated CI check is `tests/validate-manifest.py`, triggered on
-push/PR when `manifest.yaml`, `templates/**`, or the test script change. It
-validates that every template's `protocols` list in the manifest matches its
-frontmatter.
+The prompt-library validation workflow runs `tests/validate-manifest.py`
+and `tests/validate-instruction-fidelity.py` on push/PR when PromptKit
+components or validation scripts change. These checks validate manifest ↔
+template protocol sync and enforce the universal instruction-fidelity
+guardrail across templates and critical formats.
 
 ```bash
 python tests/validate-manifest.py
+python tests/validate-instruction-fidelity.py
 ```
 
 ## File Layout
@@ -345,7 +348,8 @@ promptkit/
 │   ├── lib/manifest.js       # Manifest parser
 │   └── lib/launch.js         # LLM CLI launcher
 ├── tests/
-│   ├── validate-manifest.py  # CI check
+│   ├── validate-manifest.py  # Manifest ↔ template protocol sync
+│   ├── validate-instruction-fidelity.py  # Universal guardrail coverage
 │   ├── references/           # Hand-crafted reference prompts
 │   └── generated/            # PromptKit-generated prompts (gitignored)
 └── docs/                     # Documentation and presentations

docs/contributing-components.md

@@ -277,14 +277,16 @@ protocols: [anti-hallucination, my-protocol]
 
 These must correspond. CI validates this.
 
-### Step 4: Run the CI check
+### Step 4: Run the CI checks
 
 ```bash
 python tests/validate-manifest.py
+python tests/validate-instruction-fidelity.py
 ```
 
 This verifies that every template's protocol list in the manifest matches
-its frontmatter.
+its frontmatter and that the universal instruction-fidelity guardrail is
+present where required.
 
 ## Quality Checklist Before Submitting
 
@@ -298,6 +300,7 @@ its frontmatter.
       structured rules (guardrails)
 - [ ] Templates have Non-Goals and Quality Checklist sections
 - [ ] `python tests/validate-manifest.py` passes
+- [ ] `python tests/validate-instruction-fidelity.py` passes
 - [ ] Assembled prompt produces coherent output when tested
 
 ## Example: Adding a New Template
@@ -317,7 +320,9 @@ Here's a concrete example of adding a `review-api` template:
      format: investigation-report
    ```
 
-3. **Run** `python tests/validate-manifest.py` to verify sync.
+3. **Run** `python tests/validate-manifest.py` and
+   `python tests/validate-instruction-fidelity.py` to verify sync and
+   universal guardrail coverage.
 
 4. **Test** with `npx promptkit assemble review-api -p …`
    to verify the assembled prompt is coherent.

docs/faq.md

@@ -175,7 +175,8 @@ Separate Markdown files make components independently:
    protocols, and format
 2. Add an entry to `manifest.yaml`
 3. Run `python tests/validate-manifest.py`
-4. Submit a PR
+4. Run `python tests/validate-instruction-fidelity.py`
+5. Submit a PR
 
 See [Contributing Components](contributing-components.md) for full details.
 
@@ -215,3 +216,4 @@ Check that:
 1. The component file exists at the path specified in `manifest.yaml`
 2. The template's frontmatter references the correct component names
 3. `python tests/validate-manifest.py` passes
+4. `python tests/validate-instruction-fidelity.py` passes

formats/agent-instructions.md

@@ -47,7 +47,7 @@ recommended decomposition is:
 
 | Skill file | Contents | `applyTo` example |
 |------------|----------|-------------------|
-| `<persona>.instructions.md` | Condensed persona identity and guardrail protocols (anti-hallucination, self-verification) | `**` |
+| `<persona>.instructions.md` | Condensed persona identity and guardrail protocols (anti-hallucination, instruction-fidelity, self-verification) | `**` |
 | `<analysis-protocol>.instructions.md` | A single analysis protocol's checks and phases | Language-specific glob (e.g., `**/*.c`) |
 | `<reasoning-protocol>.instructions.md` | A single reasoning protocol | `**` or task-specific glob |
 
@@ -81,11 +81,28 @@ applyTo: '<glob pattern>'
 - Write in **second person** ("You are…", "When you encounter…").
 - Condense protocol phases into standing directives — preserve all specific
   checks but omit meta-commentary about protocol structure.
+- Preserve the `instruction-fidelity` execution contract verbatim in a
+  dedicated section titled `## Instruction Fidelity Contract`. Its
+  priority rules, ambiguity handling, phase discipline, forbidden
+  behaviors, and compliance check are **non-condensable**.
 - Do NOT include PromptKit-internal headers (`# Identity`,
   `# Reasoning Protocols`, `# Output Format`, etc.).
 - Each skill file must be **self-contained** — it should make sense when
   loaded independently by the agent runtime.
 
+## Non-Condensable Execution Contract
+
+If the assembled content includes the `instruction-fidelity` guardrail,
+the output file MUST copy that contract as a verbatim operating section.
+You may adapt surrounding headings to the target platform, but you MUST
+NOT paraphrase, compress, merge away, or partially restate the contract's:
+
+- instruction priority order
+- ambiguity escalation rule
+- phase / gate discipline
+- forbidden-behavior list
+- pre-finalization compliance check
+
 ### 3. File Content — Custom Agent (`.github/agents/*.agent.md`)
 
 When the user requests a **custom agent** (a specialized persona with
@@ -131,6 +148,8 @@ tools: ['<tool1>', '<tool2>']
 - Write in **second person** ("You are…", "Your task is to…").
 - Include the condensed PromptKit persona as the agent's identity.
 - Include protocol directives as the agent's operating instructions.
+- If `instruction-fidelity` is present, include its `## Instruction
+  Fidelity Contract` section verbatim.
 - Each agent file must be self-contained — it is loaded as the agent's
   complete system prompt.
 
@@ -185,6 +204,8 @@ description: '<one-line summary of what this skill does>'
 - Write in **second person** directed at the agent.
 - Include clear instructions for what the skill does, what inputs it
   expects, and what outputs it produces.
+- If `instruction-fidelity` is present, include its `## Instruction
+  Fidelity Contract` section verbatim near the top of the skill.
 - If the skill requires tool access (file editing, shell commands),
   document this clearly so the user understands what permissions are
   needed.