orchestr8 2.5.0 → 2.6.1

package/.blueprint/features/feature_adaptive-retry/story-retry-config.md

@@ -0,0 +1,89 @@
+# Story — Retry Configuration Management
+
+## User Story
+
+As a **developer using orchestr8**, I want to **view, modify, and reset retry configuration** so that **I can customize how the pipeline handles failures based on my project's needs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 2, retry configuration is managed via `.claude/retry-config.json`
+- Per FEATURE_SPEC.md:Section 3 (Actors), users retain final decision authority and can modify thresholds
+- Per FEATURE_SPEC.md:Section 11 (Handover), this story covers CLI commands for `retry-config` and `retry-config reset`
+- Configuration file is gitignored (per FEATURE_SPEC.md:Section 7)
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — View current configuration**
+- Given the retry configuration file exists at `.claude/retry-config.json`,
+- When I run `orchestr8 retry-config`,
+- Then the current configuration is displayed in a readable format showing thresholds, window size, max retries, and enabled strategies.
+
+**AC-2 — View defaults when no configuration exists**
+- Given no retry configuration file exists,
+- When I run `orchestr8 retry-config`,
+- Then the hardcoded default configuration is displayed,
+- And a message indicates "Using default configuration (no config file found)".
+
+**AC-3 — Modify configuration value**
+- Given I run `orchestr8 retry-config set <key> <value>` (e.g., `orchestr8 retry-config set maxRetries 5`),
+- When the key is valid and value is of correct type,
+- Then the configuration file is updated with the new value,
+- And a confirmation message shows the updated setting.
+
+**AC-4 — Reject invalid configuration key**
+- Given I run `orchestr8 retry-config set <invalidKey> <value>`,
+- When the key is not recognized,
+- Then an error message is displayed listing valid configuration keys,
+- And no file modification occurs.
+
+**AC-5 — Reset configuration to defaults**
+- Given the retry configuration file exists with custom values,
+- When I run `orchestr8 retry-config reset`,
+- Then the configuration file is replaced with default values,
+- And a confirmation message indicates "Retry configuration reset to defaults".
+
+**AC-6 — Create configuration file on first modification**
+- Given no retry configuration file exists,
+- When I run `orchestr8 retry-config set <key> <value>`,
+- Then the configuration file is created with default values plus the specified modification,
+- And the file is created in `.claude/retry-config.json`.
+
+**AC-7 — Handle corrupted configuration gracefully**
+- Given the retry configuration file exists but contains invalid JSON,
+- When I run `orchestr8 retry-config`,
+- Then an error message is displayed indicating the file is corrupted,
+- And a suggestion to run `orchestr8 retry-config reset` is shown.
+
+---
+
+## Configuration Schema
+
+Per FEATURE_SPEC.md:Section 6 (Rules), default configuration includes:
+
+```json
+{
+  "maxRetries": 3,
+  "windowSize": 10,
+  "highFailureThreshold": 0.2,
+  "strategies": {
+    "alex": ["simplify-prompt", "add-context"],
+    "cass": ["reduce-stories", "simplify-prompt"],
+    "nigel": ["simplify-tests", "add-context"],
+    "codey-plan": ["add-context", "simplify-prompt"],
+    "codey-implement": ["incremental", "rollback"]
+  }
+}
+```
+
+---
+
+## Out of Scope
+
+- Modifying strategy definitions themselves (strategies are code, not config)
+- Per-feature configuration overrides (configuration is global)
+- Configuration UI/interactive editor (CLI only)
+- Validating strategy effectiveness (config is just data; strategy logic is separate)

package/.blueprint/features/feature_adaptive-retry/story-should-retry.md

@@ -0,0 +1,98 @@
+# Story — Should Retry Decision Logic
+
+## User Story
+
+As a **developer using orchestr8**, I want the **pipeline to intelligently decide whether to recommend retrying** so that **I receive useful guidance based on attempt count, failure history, and system state**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Happy Path), retry module is consulted when an agent fails
+- Per FEATURE_SPEC.md:Section 5 (State & Lifecycle), this operates within the transition from any agent state to FAILED
+- Per FEATURE_SPEC.md:Section 8 (Resilience), graceful degradation is required when history/config is corrupted
+- Per SYSTEM_SPEC.md:Section 8 (Failure Handling), each agent spawn currently offers retry, skip, abort
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Consult retry module on agent failure**
+- Given an agent fails during pipeline execution,
+- When the error handling flow is triggered,
+- Then the retry module is consulted before displaying options to the user,
+- And the module returns a recommendation (strategy name or "abort-recommended").
+
+**AC-2 — Record retry attempts in history**
+- Given the user chooses to retry (with or without strategy),
+- When the retry completes (success or failure),
+- Then the outcome is recorded in `.claude/pipeline-history.json`,
+- And the record includes: `retryAttempts` count and `strategiesUsed[]` array.
+
+**AC-3 — Track attempt count per stage per feature**
+- Given an agent fails and user retries,
+- When tracking retry state,
+- Then the attempt count is incremented for the current stage and feature combination,
+- And the count persists across retries within the same pipeline run.
+
+**AC-4 — Degrade gracefully with corrupted history**
+- Given the history file at `.claude/pipeline-history.json` is corrupted or missing,
+- When the retry module is consulted,
+- Then the module defaults to simple retry recommendation,
+- And a warning is logged: "History file unavailable; defaulting to simple retry".
+
+**AC-5 — Degrade gracefully with corrupted configuration**
+- Given the configuration file at `.claude/retry-config.json` is corrupted or missing,
+- When the retry module calculates strategy,
+- Then hardcoded defaults are used for thresholds and strategies,
+- And a warning is logged: "Config file unavailable; using default settings".
+
+**AC-6 — Preserve state transitions**
+- Given a retry is in progress,
+- When the retry attempt completes successfully,
+- Then the pipeline continues to the next stage as normal,
+- And the state transitions per SYSTEM_SPEC.md:Section 6 (e.g., CASS to NIGEL).
+
+**AC-7 — Support abort without retry**
+- Given the user is shown retry options,
+- When the user selects "abort",
+- Then the feature is moved to the failed list in the queue,
+- And no retry is attempted,
+- And the failure is recorded with reason "user-aborted".
+
+---
+
+## Integration Points
+
+Per FEATURE_SPEC.md:Section 7 (Dependencies):
+
+- **src/history.js:** `readHistoryFile()` provides failure data
+- **src/insights.js:** `analyzeFailures()` calculates failure rates by stage
+- **src/orchestrator.js:** Queue management receives retry module functions
+- **SKILL.md:** Error handling section references retry recommendations
+
+---
+
+## History Record Schema
+
+Per FEATURE_SPEC.md:Section 8 (Audit/Logging), new fields in history entries:
+
+```json
+{
+  "featureSlug": "adaptive-retry",
+  "stage": "cass",
+  "outcome": "success",
+  "timestamp": "2026-02-24T10:30:00Z",
+  "retryAttempts": 2,
+  "strategiesUsed": ["retry", "reduce-stories"]
+}
+```
+
+---
+
+## Out of Scope
+
+- Automatic retry without user prompt (user always has final say)
+- Retry across different features (each feature's retry state is independent)
+- Persistent retry state across pipeline invocations (state is per-run only; history is persistent)
+- Batch retry of multiple failed features (single-feature focus per SYSTEM_SPEC.md:Section 10)

package/.blueprint/features/feature_adaptive-retry/story-strategy-recommendation.md

@@ -0,0 +1,85 @@
+# Story — Strategy Recommendation
+
+## User Story
+
+As a **developer using orchestr8**, I want the **pipeline to recommend a retry strategy based on failure history** so that **I can make informed decisions about how to handle failures more effectively**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Behaviour Overview), recommendations are advisory only; user retains final choice
+- Per FEATURE_SPEC.md:Section 6 (Rule 1 & Rule 2), strategy selection is based on failure rate calculation
+- Per FEATURE_SPEC.md:Section 3 (Actors), the History Module provides failure data (read-only)
+- Per FEATURE_SPEC.md:Section 7 (Dependencies), uses `src/history.js` and `src/insights.js`
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Calculate failure rate from history**
+- Given an agent fails during pipeline execution,
+- When the retry module is consulted,
+- Then the failure rate is calculated as `failedRunsAtStage / totalRecentRuns` over the configured window (default 10 runs),
+- And the calculation uses data from `.claude/pipeline-history.json`.
+
+**AC-2 — Recommend simple retry for low failure rate**
+- Given the calculated failure rate is at or below the threshold (default 20%),
+- When displaying retry options to the user,
+- Then the recommendation is "retry" with no prompt modification suggested,
+- And the message format is: "Recommended: Simple retry. Retry? (y/n/skip/abort)".
+
+**AC-3 — Recommend alternative strategy for high failure rate**
+- Given the calculated failure rate exceeds the threshold (default 20%),
+- When displaying retry options to the user,
+- Then an alternative strategy from the stage's strategy list is recommended,
+- And the message format is: "Recommended strategy: {strategyName}. Retry with this approach? (y/apply/skip/abort)".
+
+**AC-4 — Escalate strategy on subsequent attempts**
+- Given a retry attempt has already been made at the current stage,
+- When another failure occurs and the user is prompted again,
+- Then the next strategy in the stage's strategy list is recommended,
+- And if all strategies have been exhausted, "abort-recommended" is suggested.
+
+**AC-5 — Default to simple retry with no history**
+- Given this is the first recorded run or no history exists for the current stage,
+- When an agent fails,
+- Then the recommendation is "retry" (simple retry),
+- And a note indicates "No failure history for this stage; defaulting to simple retry".
+
+**AC-6 — Warn when max retries exceeded**
+- Given the current attempt count exceeds `maxRetries` (default 3) for the same feature and stage,
+- When displaying options to the user,
+- Then the recommendation is "abort-recommended" or "skip-recommended",
+- And a warning is displayed: "Max retries ({count}) exceeded for {stage}. Consider skipping or aborting."
+
+**AC-7 — Display recommendation without forcing choice**
+- Given a strategy recommendation is displayed,
+- When the user selects a different option (e.g., chooses "skip" when "retry" was recommended),
+- Then the user's choice is respected,
+- And no error or warning is shown for overriding the recommendation.
+
+---
+
+## Session State
+
+During pipeline execution, retry state is tracked:
+
+```js
+retryState = {
+  stage: 'cass',
+  featureSlug: 'adaptive-retry',
+  attemptCount: 2,
+  strategiesUsed: ['retry', 'reduce-stories'],
+  failureRate: 0.3
+}
+```
+
+---
+
+## Out of Scope
+
+- Machine learning or predictive models for strategy selection (per FEATURE_SPEC.md:Section 2)
+- Cross-feature failure correlation (per FEATURE_SPEC.md:Section 2)
+- Automatic retry without user confirmation (user choice is paramount)
+- Modifying the agent prompts (that is story-prompt-modification)

package/.blueprint/features/feature_agent-guardrails/FEATURE_SPEC.md

@@ -0,0 +1,328 @@
+# Feature Specification — Agent Guardrails
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+The orchestr8 framework relies on four AI agents (Alex, Cass, Nigel, Codey) operating autonomously within a pipeline. Without explicit guardrails, these agents may:
+
+- Generate content based on training data rather than provided inputs
+- Reference external sources (social media, forums, web content) that are unreliable or inappropriate
+- Expose confidential business context in outputs
+- Produce non-deterministic or hallucinated content that cannot be traced to authoritative sources
+
+**Problem being addressed:**
+Uncontrolled information sourcing and output generation creates risks around accuracy, confidentiality, and auditability in automated feature development.
+
+**User need:**
+Users need confidence that agent outputs are grounded exclusively in provided inputs (specs, code, business_context, templates) and that confidential information is protected.
+
+**System purpose alignment:**
+Per `.blueprint/system_specification/SYSTEM_SPEC.md`: "What must not be compromised: Explicit specification before implementation" and "All artifacts (specs, stories, tests, code) are aligned and consistent." Guardrails directly support these principles by ensuring agents produce traceable, consistent outputs.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- **Source restrictions**: Rules governing what information sources agents may and may not use
+- **Grounding requirements**: Citation and traceability standards for all agent assertions
+- **Confidentiality constraints**: Rules for protecting `.business_context/` content and preventing data leakage
+- **Determinism expectations**: Standards for reproducible, consistent agent behaviour
+- **Escalation protocols**: Clear rules for when agents must stop and ask the user
+- **Anti-hallucination measures**: Explicit preference for "I don't have this information" over guessing
+
+### Out of Scope
+
+- Technical enforcement mechanisms (runtime validation, content filtering)
+- Monitoring or auditing infrastructure for guardrail compliance
+- Changes to the pipeline flow or agent sequencing
+- Modifications to CLI tooling or queue management
+- Integration with external guardrail services or APIs
+
+---
+
+## 3. Actors Involved
+
+### Alex (System Specification & Chief-of-Staff)
+- **What they can do**: Define system and feature specifications grounded in provided inputs; cite sources for all assertions; flag missing information
+- **What they cannot do**: Use external sources; invent business rules not found in inputs; expose confidential context in specifications
+
+### Cass (Story Writer & Business Analyst)
+- **What they can do**: Translate specifications into user stories citing the feature spec; make explicit assumptions when information is missing
+- **What they cannot do**: Reference external examples or implementations; introduce behaviour not derived from specifications
+
+### Nigel (Tester)
+- **What they can do**: Create tests based on user stories and acceptance criteria; note assumptions explicitly
+- **What they cannot do**: Use external testing patterns without attribution; invent requirements beyond what stories specify
+
+### Codey (Developer)
+- **What they can do**: Implement against tests and specifications; make implementation assumptions explicit
+- **What they cannot do**: Use code from external sources without flagging; modify behaviour beyond what tests require
+
+### Human User
+- **What they can do**: Provide source materials; respond to escalations; approve assumptions
+- **What they cannot do**: N/A (human user is the authority)
+
+---
+
+## 4. Behaviour Overview
+
+**Happy-path behaviour:**
+
+1. Agent receives task with explicit inputs (specs, stories, tests, code, business_context)
+2. Agent processes ONLY the provided inputs to produce outputs
+3. Agent cites sources for all assertions using standard format: "Per [filename]: [claim]" or "[filename:section] states..."
+4. Agent flags any gaps or assumptions explicitly rather than filling them silently
+5. Agent produces self-contained outputs that do not leak confidential context
+6. Given identical inputs, agent produces consistent outputs
+
+**Key alternatives or branches:**
+
+- **Missing information path**: When required information is not in provided inputs, agent explicitly states "This information is not available in the provided inputs" and either (a) makes an explicit assumption labelled as such, or (b) escalates to the user
+- **Ambiguity path**: When inputs are ambiguous, agent lists possible interpretations and asks the user to clarify
+- **Confidentiality conflict path**: When an output would require exposing confidential context, agent flags this and asks for guidance
+
+**User-visible outcomes:**
+
+- All agent outputs contain traceable citations to source files
+- Assumptions are explicitly labelled and distinguishable from facts
+- Outputs are self-contained and do not reference confidential details by name
+- Re-running the pipeline with identical inputs produces consistent results
+
+---
+
+## 5. State & Lifecycle Interactions
+
+This feature is **state-constraining** rather than state-creating or state-transitioning.
+
+**States affected:**
+- All pipeline stages (alex, cass, nigel, codey-plan, codey-implement) are constrained by guardrails
+- Guardrails apply regardless of whether a feature is pending, in_progress, or being resumed
+
+**No new states introduced:**
+The feature adds behavioural constraints to existing states without modifying the state model defined in `.blueprint/system_specification/SYSTEM_SPEC.md` section 6.
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule 1: Source Restriction Rule
+
+**Description:** Agents must use ONLY information from explicitly provided inputs.
+
+**Inputs:** Task context, file references, `.business_context/` directory contents
+
+**Outputs:** Agent output grounded exclusively in provided inputs
+
+**Deterministic:** Yes
+
+**Allowed sources:**
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`)
+- Test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`)
+- Agent specifications (`.blueprint/agents/AGENT_*.md`)
+
+**Prohibited sources:**
+- Social media (Twitter/X, Reddit, LinkedIn, Facebook, etc.)
+- Forums, blog posts, or user-generated web content
+- Web searches or external APIs
+- Training data for domain-specific facts
+- External project implementations or company references
+
+---
+
+### Rule 2: Citation Rule
+
+**Description:** All assertions about requirements, behaviour, or domain knowledge must cite their source.
+
+**Inputs:** Agent assertions about the system or domain
+
+**Outputs:** Assertion with citation in format: "Per [filename]: [claim]" or "[filename:section] states..."
+
+**Deterministic:** Yes
+
+**Examples:**
+- "Per FEATURE_SPEC.md: Users must authenticate before accessing the dashboard"
+- "Per story-login.md:AC-3: Failed login attempts are logged"
+- ".business_context/glossary.md defines 'tenant' as..."
+
+---
+
+### Rule 3: Confidentiality Rule
+
+**Description:** Agents must treat `.business_context/` content as confidential and prevent data leakage.
+
+**Inputs:** Any content from `.business_context/` directory
+
+**Outputs:** Outputs that do not expose confidential details
+
+**Deterministic:** Yes
+
+**Constraints:**
+- Do not reference external projects, companies, or implementations by name
+- Do not use external services that would expose project data
+- Output artifacts should be self-contained
+- Generic descriptions preferred over specific confidential details
+
+---
+
+### Rule 4: Assumption Declaration Rule
+
+**Description:** When information is not available in provided inputs, agents must explicitly declare assumptions.
+
+**Inputs:** Gap in provided information
+
+**Outputs:** Explicit assumption statement labelled as such
+
+**Deterministic:** Yes
+
+**Format:**
+- "ASSUMPTION: [statement] - This is not specified in the provided inputs"
+- "NOTE: Assuming [X] in absence of explicit guidance"
+
+---
+
+### Rule 5: Escalation Rule
+
+**Description:** Agents must escalate to the user under defined conditions rather than proceeding with guesses.
+
+**Inputs:** Trigger conditions (listed below)
+
+**Outputs:** Escalation request to user
+
+**Deterministic:** Yes
+
+**Escalation triggers:**
+- Information required for the task is not in provided inputs AND cannot be safely assumed
+- Ambiguity in inputs that significantly affects output
+- Conflict between different input sources
+- Request would require violating confidentiality constraints
+- Uncertainty that could lead to material misalignment
+
+---
+
+### Rule 6: Determinism Rule
+
+**Description:** Same inputs should produce consistent outputs across runs.
+
+**Inputs:** Identical task context and input files
+
+**Outputs:** Consistent agent outputs
+
+**Deterministic:** Yes (by definition)
+
+**Implications:**
+- Avoid incorporating timestamps or random elements unless explicitly required
+- Avoid referencing volatile or external state
+- Structure outputs to be reproducible
+
+---
+
+## 7. Dependencies
+
+### System Components
+- Agent specifications (`.blueprint/agents/AGENT_*.md`) - must be updated to incorporate guardrails
+- Pipeline orchestration (`SKILL.md` / `/implement-feature`) - no changes required, but agents must apply guardrails
+
+### External Systems
+- None (guardrails specifically prohibit external dependencies)
+
+### Policy Dependencies
+- None identified
+
+### Operational Dependencies
+- Users must provide adequate input materials (business_context, specs) for agents to work from
+- Teams adopting orchestr8 must understand that agents will escalate when information is insufficient
+
+---
+
+## 8. Non-Functional Considerations
+
+### Auditability
+- Citation format enables traceability from outputs back to source inputs
+- Assumption labels enable review of agent decisions
+- Escalation log provides audit trail of human decisions
+
+### Reliability
+- Determinism rule supports reproducible builds and debugging
+- Explicit assumptions reduce hidden failure modes
+
+### Security / Confidentiality
+- Confidentiality constraints protect business-sensitive information
+- Prohibition on external services prevents data exposure
+
+### Performance
+- No significant performance impact expected
+- Guardrails are behavioural constraints, not runtime checks
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+1. **Input sufficiency**: Users will provide adequate input materials for agents to complete tasks without excessive escalation
+2. **Agent compliance**: Guardrails are specification-level constraints that agents will follow; no technical enforcement mechanism is assumed
+3. **Citation overhead**: The additional effort of citing sources is acceptable given the traceability benefits
+4. **Escalation tolerance**: Users accept that agents will ask clarifying questions rather than guessing
+
+### Open Questions
+
+1. **Granularity of citation**: Should citations reference file-level or section-level? (Recommendation: section-level where feasible)
+2. **Assumption threshold**: What level of assumption is acceptable before escalation is required? (Recommendation: err on the side of escalation for domain-specific matters)
+3. **Confidentiality scope**: Should confidentiality constraints extend beyond `.business_context/` to include implementation code? (Recommendation: yes, treat all project content as confidential by default)
+
+---
+
+## 10. Impact on System Specification
+
+**Does this feature reinforce, stretch, or contradict existing system assumptions?**
+
+This feature **reinforces** existing system assumptions, particularly:
+
+- Per SYSTEM_SPEC.md section 7 (Governing Rules & Invariants): "No silent changes: Agents flag deviations; do not silently alter specifications" - guardrails extend this principle
+- Per SYSTEM_SPEC.md section 8 (Cross-Cutting Concerns): "Traceability" - citation requirements directly support traceability goals
+- Per SYSTEM_SPEC.md section 9 (Non-Functional Expectations): "Deterministic output given same inputs" - determinism rule makes this explicit
+
+**Potential system spec enhancement:**
+
+Section 7 (Governing Rules & Invariants) could be extended with a new subsection "Agent Guardrails" that codifies these constraints at the system level. This is a **non-breaking enhancement** that strengthens existing principles.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+
+Cass should derive stories around four main themes:
+
+1. **Source Restriction Stories**: Stories covering what agents can and cannot reference when producing outputs
+2. **Citation & Traceability Stories**: Stories defining how agents cite sources and maintain traceability
+3. **Confidentiality Stories**: Stories ensuring business context remains protected
+4. **Escalation & Assumption Stories**: Stories defining when and how agents escalate vs. assume
+
+### Expected Story Boundaries
+
+- Each guardrail rule (Rules 1-6 in section 6) likely maps to one or more stories
+- Stories should be agent-agnostic where possible (guardrails apply to all agents)
+- Stories should include acceptance criteria that can be verified by reviewing agent outputs
+
+### Areas Needing Careful Story Framing
+
+- **Balancing thoroughness vs. practicality**: Citation requirements should not create excessive overhead
+- **Escalation threshold**: Stories should clarify when escalation is warranted vs. when reasonable assumption is acceptable
+- **Confidentiality boundaries**: What exactly constitutes "confidential" and what is acceptable to reference
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-02-24 | Initial feature specification | Define comprehensive guardrails for agent behaviour | Alex |

package/.blueprint/features/feature_agent-guardrails/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,90 @@
+# Implementation Plan — Agent Guardrails
+
+## Summary
+
+Add a standardised "Guardrails" section to all four agent specification files (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md). The section covers source restrictions, citation requirements, confidentiality constraints, and escalation protocols. This is a documentation-only change with no runtime code modifications.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `.blueprint/agents/AGENT_SPECIFICATION_ALEX.md` | Modify | Add Guardrails section |
+| `.blueprint/agents/AGENT_BA_CASS.md` | Modify | Add Guardrails section |
+| `.blueprint/agents/AGENT_TESTER_NIGEL.md` | Modify | Add Guardrails section |
+| `.blueprint/agents/AGENT_DEVELOPER_CODEY.md` | Modify | Add Guardrails section |
+
+---
+
+## Implementation Steps
+
+1. **Read each agent spec file** to identify the best insertion point for the Guardrails section (after existing content, before any skills section if present).
+
+2. **Add Guardrails section to AGENT_SPECIFICATION_ALEX.md** using the template below.
+
+3. **Add Guardrails section to AGENT_BA_CASS.md** using the template below.
+
+4. **Add Guardrails section to AGENT_TESTER_NIGEL.md** using the template below.
+
+5. **Add Guardrails section to AGENT_DEVELOPER_CODEY.md** using the template below.
+
+6. **Run tests** (`node --test test/feature_agent-guardrails.test.js`) to verify all 21 test assertions pass.
+
+7. **Review outputs** to ensure no test failures remain.
+
+---
+
+## Guardrails Section Template
+
+```markdown
+## Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
+```
+
+---
+
+## Risks/Questions
+
+- **Insertion point consistency**: Each agent file has slightly different structure; insert before "Skills available" section if present, otherwise at end.
+- **Test phrase matching**: Tests use case-insensitive substring matching; template wording must include trigger phrases from test file.