From 60a27a9d5a543488b643f7a18dbc82e7e1663be6 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Sun, 29 Mar 2026 20:05:32 -0700 Subject: [PATCH 1/5] Add dev-workflow: domain-agnostic incremental development pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a complete incremental development workflow that propagates changes through requirements, specifications, and implementation with adversarial audits and human-in-the-loop review at each transition. New components (8): - formats/structured-patch — traceable diff/patch output format - protocols/reasoning/change-propagation — 5-phase change propagation - templates/dev-workflow — interactive orchestration entry point - templates/collaborate-requirements-change — requirements discovery - templates/generate-spec-changes — requirements to design/validation - templates/generate-implementation-changes — specs to implementation - templates/audit-spec-alignment — adversarial spec audit (D1-D7) - templates/audit-implementation-alignment — adversarial impl audit (D8-D13) Key design decisions: - Domain-agnostic: configurable personas let users apply the workflow to software, hardware, mechanical, RF, or protocol engineering - Two audit cycles: spec audit (D1-D7) and implementation audit (D8-D13) using the existing specification-drift taxonomy - Loop-back capability: audit verdicts (PASS/REVISE/RESTART) drive iteration between phases - Standalone phase templates: each phase can be used independently Pipeline: dev-workflow (5 stages with structured-patch artifact flow) Closes #115 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/structured-patch.md | 154 ++++++++++ manifest.yaml | 105 +++++++ protocols/reasoning/change-propagation.md | 104 +++++++ templates/audit-implementation-alignment.md | 149 +++++++++ templates/audit-spec-alignment.md | 151 +++++++++ templates/collaborate-requirements-change.md | 140 +++++++++ templates/dev-workflow.md | 303 +++++++++++++++++++ templates/generate-implementation-changes.md | 146 +++++++++ templates/generate-spec-changes.md | 132 ++++++++ 9 files changed, 1384 insertions(+) create mode 100644 formats/structured-patch.md create mode 100644 protocols/reasoning/change-propagation.md create mode 100644 templates/audit-implementation-alignment.md create mode 100644 templates/audit-spec-alignment.md create mode 100644 templates/collaborate-requirements-change.md create mode 100644 templates/dev-workflow.md create mode 100644 templates/generate-implementation-changes.md create mode 100644 templates/generate-spec-changes.md diff --git a/formats/structured-patch.md b/formats/structured-patch.md new file mode 100644 index 0000000..a5328f8 --- /dev/null +++ b/formats/structured-patch.md @@ -0,0 +1,154 @@ + + + +--- +name: structured-patch +type: format +description: > + Output format for traceable, structured patches to existing artifacts. + Each change entry links to its upstream motivation, enabling full + traceability from requirements through design, validation, and + implementation. Domain-agnostic — works for specifications, code, + schematics, test plans, or any versioned artifact. +produces: structured-patch +--- + +# Format: Structured Patch + +Use this format when producing **incremental changes** to existing artifacts +rather than generating documents from scratch. Every change MUST trace to +an upstream motivation (a requirement change, a design decision, a user +request) so reviewers can verify alignment at each transition. + +## Document Structure + +```markdown +# + +## 1. Change Context +## 2. Change Manifest +## 3. Detailed Changes +## 4. Traceability Matrix +## 5. Invariant Impact +## 6. Application Notes +``` + +## 1. Change Context + +Provide the context for this patch set: + +- **Upstream artifact**: what motivated these changes (e.g., requirements + patch, design revision, user request) +- **Target artifacts**: what is being changed (e.g., design document, + validation plan, source code, schematic) +- **Scope**: what areas are affected and what is explicitly unchanged + +## 2. Change Manifest + +A summary table of all changes in this patch: + +```markdown +| Change ID | Type | Target Artifact | Section / Location | Summary | +|------------|--------|-----------------|--------------------|---------------------| +| CHG-001 | Add | design-doc | §3.2 API Layer | New endpoint for... | +| CHG-002 | Modify | validation-plan | TC-012 | Update expected... | +| CHG-003 | Remove | design-doc | §4.1 Legacy API | Remove deprecated...| +``` + +**Change types**: +- **Add** — new content that did not previously exist +- **Modify** — alteration of existing content +- **Remove** — deletion of existing content + +## 3. Detailed Changes + +For each change in the manifest, provide a detailed entry: + +```markdown +### CHG-: + +- **Type**: Add | Modify | Remove +- **Upstream ref**: +- **Target**: +- **Rationale**: + +#### Before + + + +#### After + + + +#### Impact + + +``` + +**Rules for detailed changes**: + +- Every change MUST have an upstream ref. If the change is motivated by + the user's direct request (not a downstream propagation), use + `USER-REQUEST: `. +- Before/After sections MUST show enough context to apply the change + unambiguously. For code or structured documents, include surrounding + lines or section headers. +- For modifications, clearly mark what changed between Before and After. + Use **bold** for inserted text and ~~strikethrough~~ for removed text + when showing inline diffs in prose. + +## 4. Traceability Matrix + +Map every upstream change to its downstream changes: + +```markdown +| Upstream Ref | Downstream Changes | Status | +|-------------------|-----------------------------|-----------| +| REQ-FUNC-005 | CHG-001, CHG-002 | Complete | +| REQ-PERF-002 | CHG-003 | Complete | +| USER-REQUEST: ... | CHG-004 | Partial | +``` + +**Status values**: +- **Complete** — all necessary downstream changes are included +- **Partial** — some downstream changes are deferred (explain in notes) +- **Blocked** — downstream changes cannot be made yet (explain why) + +## 5. Invariant Impact + +For each invariant or constraint affected by this patch set: + +```markdown +| Invariant / Constraint | Effect | Verification | +|------------------------|-----------------------|-----------------------| +| CON-SEC-001: All... | Unchanged — preserved | Existing TC-008 valid | +| ASM-003: Network... | Modified — relaxed | New TC-025 added | +| INV-PERF-002: Resp... | Unchanged — preserved | No action needed | +``` + +If no invariants are affected, state explicitly: +`No existing invariants or constraints are affected by this patch set.` + +## 6. Application Notes + +Instructions for applying this patch: + +- **Method**: how to apply (e.g., "apply as git diff", "manually update + sections", "replace schematic sheet 3") +- **Order**: if changes must be applied in a specific sequence +- **Verification**: how to verify the patch was applied correctly +- **Rollback**: how to revert if needed + +## Formatting Rules + +1. Change IDs MUST use the format `CHG-` with zero-padded + three-digit numbers, sequential within the patch. +2. Every change MUST have exactly one upstream ref. +3. The traceability matrix MUST account for every upstream change — + no upstream change may be silently dropped. +4. Before/After sections MUST be unambiguous — a reviewer should be + able to locate and apply the change without additional context. +5. The invariant impact section MUST be present even if empty + (state "no invariants affected" explicitly). +6. Sections MUST appear in the order specified above. diff --git a/manifest.yaml b/manifest.yaml index 45a6ad6..193b61d 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -474,6 +474,14 @@ protocols: Maps execution back to PromptKit components and produces actionable optimization recommendations. + - name: change-propagation + path: protocols/reasoning/change-propagation.md + description: > + Systematic reasoning protocol for propagating changes through + artifact layers while maintaining alignment. Covers impact + analysis, change derivation, invariant checking, completeness + verification, and conflict detection. Domain-agnostic. + formats: - name: requirements-doc path: formats/requirements-doc.md @@ -644,6 +652,15 @@ formats: state, and cross-cutting implications (security, performance, management, observability, testing). + - name: structured-patch + path: formats/structured-patch.md + produces: structured-patch + description: > + Traceable, structured patch format for incremental changes to + existing artifacts. Each change entry links to its upstream + motivation with Before/After content, traceability matrix, and + invariant impact assessment. Domain-agnostic. + taxonomies: - name: stack-lifetime-hazards path: taxonomies/stack-lifetime-hazards.md @@ -1290,6 +1307,71 @@ templates: protocols: [anti-hallucination, self-verification, protocol-validation-design] format: protocol-validation-spec + dev-workflow: + - name: dev-workflow + path: templates/dev-workflow.md + description: > + Full incremental development workflow with human-in-the-loop + review. Guides an agent through requirements discovery, + specification changes, implementation changes, adversarial + audits, and deliverable creation. Domain-agnostic. + persona: configurable + protocols: [anti-hallucination, self-verification, adversarial-falsification, operational-constraints, requirements-elicitation, iterative-refinement, change-propagation, traceability-audit, code-compliance-audit, test-compliance-audit] + taxonomies: [specification-drift] + format: structured-patch + + - name: collaborate-requirements-change + path: templates/collaborate-requirements-change.md + description: > + Interactive requirements discovery for incremental changes. + Work with the user to understand, refine, and produce a + structured requirements patch. Domain-agnostic. + persona: configurable + protocols: [anti-hallucination, self-verification, requirements-elicitation, iterative-refinement] + format: structured-patch + + - name: generate-spec-changes + path: templates/generate-spec-changes.md + description: > + Generate design and validation specification changes from a + requirements patch. Propagates each requirement change to + design sections and validation entries. Domain-agnostic. + persona: configurable + protocols: [anti-hallucination, self-verification, change-propagation] + format: structured-patch + + - name: generate-implementation-changes + path: templates/generate-implementation-changes.md + description: > + Generate implementation and verification changes from a + specification patch. Propagates design and validation changes + to implementation artifacts. Domain-agnostic. + persona: configurable + protocols: [anti-hallucination, self-verification, change-propagation, operational-constraints] + format: structured-patch + + - name: audit-spec-alignment + path: templates/audit-spec-alignment.md + description: > + Adversarial audit of specification patches against user intent. + Verifies requirements, design, and validation changes faithfully + represent what the user asked for. Domain-agnostic. + persona: specification-analyst + protocols: [anti-hallucination, self-verification, adversarial-falsification, traceability-audit] + taxonomies: [specification-drift] + format: investigation-report + + - name: audit-implementation-alignment + path: templates/audit-implementation-alignment.md + description: > + Adversarial audit of implementation patches against specification + deltas. Verifies implementation and verification changes correctly + realize the specification changes. Domain-agnostic. + persona: specification-analyst + protocols: [anti-hallucination, self-verification, adversarial-falsification, operational-constraints, code-compliance-audit, test-compliance-audit] + taxonomies: [specification-drift] + format: investigation-report + pipelines: document-lifecycle: description: > @@ -1345,3 +1427,26 @@ pipelines: - template: review-layout consumes: requirements-document produces: investigation-report + + dev-workflow: + description: > + Domain-agnostic incremental development workflow with + human-in-the-loop review. Propagates changes through + requirements, specifications, and implementation with + adversarial audits at each transition. Phases can loop + back based on audit verdicts or user feedback. + stages: + - template: collaborate-requirements-change + produces: structured-patch + - template: generate-spec-changes + consumes: structured-patch + produces: structured-patch + - template: audit-spec-alignment + consumes: structured-patch + produces: investigation-report + - template: generate-implementation-changes + consumes: structured-patch + produces: structured-patch + - template: audit-implementation-alignment + consumes: structured-patch + produces: investigation-report diff --git a/protocols/reasoning/change-propagation.md b/protocols/reasoning/change-propagation.md new file mode 100644 index 0000000..7cd9101 --- /dev/null +++ b/protocols/reasoning/change-propagation.md @@ -0,0 +1,104 @@ + + + +--- +name: change-propagation +type: reasoning +description: > + Systematic reasoning protocol for propagating changes through artifact + layers while maintaining alignment. Ensures every upstream change + produces the correct downstream changes, no invariants are broken, + and no changes are silently dropped. Domain-agnostic — works for + specifications, code, schematics, test plans, or any layered artifacts. +applicable_to: + - generate-spec-changes + - generate-implementation-changes + - dev-workflow +--- + +# Protocol: Change Propagation + +Apply these phases **in order** when deriving downstream changes from +upstream changes. Do not skip phases. + +## Phase 1: Impact Analysis + +For each upstream change, determine which downstream artifacts are affected: + +1. **Direct impact** — downstream sections that explicitly reference or + implement the changed upstream content. +2. **Indirect impact** — downstream sections that depend on assumptions, + constraints, or invariants affected by the upstream change. +3. **No impact** — downstream sections verified to be unaffected. + State WHY they are unaffected (do not silently skip). + +Produce an impact map: + +``` +Upstream CHG- → + Direct: [list of downstream locations] + Indirect: [list of downstream locations] + Unaffected: [list with rationale] +``` + +## Phase 2: Change Derivation + +For each impacted downstream location: + +1. Determine the **minimal necessary change** — the smallest modification + that restores alignment with the upstream change. +2. Classify the change type: Add, Modify, or Remove. +3. Draft Before/After content showing the exact change. +4. Record the upstream ref that motivates this downstream change. + +**Constraints**: +- Do NOT introduce changes beyond what the upstream change requires. + If you identify an improvement opportunity unrelated to the upstream + change, note it separately as a recommendation — do not include it + in the patch. +- Do NOT silently combine multiple upstream changes into one downstream + change. If two upstream changes affect the same downstream location, + create separate change entries (they may be applied together, but + traceability requires distinct entries). + +## Phase 3: Invariant Check + +For every existing invariant, constraint, and assumption in the +downstream artifact: + +1. Verify it is **preserved** by the combined set of downstream changes. +2. If an invariant is **modified** by the changes, flag it explicitly + and verify the modification is justified by the upstream change. +3. If an invariant is **violated** by the changes, STOP and report + the conflict. Do not proceed with a patch that breaks invariants + without explicit acknowledgment. + +## Phase 4: Completeness Check + +Verify that every upstream change has at least one corresponding +downstream change (or an explicit "no downstream impact" justification): + +1. Walk the upstream change manifest entry by entry. +2. For each upstream change, confirm it appears in the traceability + matrix with status Complete, Partial (with explanation), or + No-Impact (with rationale). +3. Flag any upstream change that has no downstream entry as + **DROPPED** — this is an error that must be resolved before + the patch is finalized. + +## Phase 5: Conflict Detection + +Check for conflicts within the downstream change set: + +1. **Internal conflicts** — two downstream changes that modify the + same location in contradictory ways. +2. **Cross-artifact conflicts** — a change in one downstream artifact + that contradicts a change in another (e.g., a design change that + conflicts with a validation change). +3. **Upstream-downstream conflicts** — a downstream change that + contradicts the intent of its upstream motivator. + +For each conflict found: +- Describe the conflicting changes +- Identify the root cause (usually an ambiguity or gap in the upstream) +- Recommend resolution diff --git a/templates/audit-implementation-alignment.md b/templates/audit-implementation-alignment.md new file mode 100644 index 0000000..d7c0ce9 --- /dev/null +++ b/templates/audit-implementation-alignment.md @@ -0,0 +1,149 @@ + + + +--- +name: audit-implementation-alignment +description: > + Adversarial audit of implementation patches against specification + deltas. Verifies that implementation and verification changes + correctly realize the specification changes, with no drift, + omissions, or undocumented behavior. Domain-agnostic. +persona: specification-analyst +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - guardrails/adversarial-falsification + - guardrails/operational-constraints + - reasoning/code-compliance-audit + - reasoning/test-compliance-audit +taxonomies: + - specification-drift +format: investigation-report +params: + project_name: "Name of the project, product, or system" + spec_patch: "The structured specification patch (design + validation changes)" + implementation_patch: "The structured implementation patch (code/artifact + verification changes)" + existing_artifacts: "Existing implementation and verification artifacts for context" +input_contract: + type: structured-patch + description: > + Structured patches for specifications and implementation, to be + audited for alignment. +output_contract: + type: investigation-report + description: > + An adversarial audit report classifying alignment findings using + the specification-drift taxonomy (D8–D13), with severity ratings + and remediation recommendations. +--- + +# Task: Adversarial Audit of Implementation Alignment + +You are tasked with performing an **adversarial audit** of the +implementation patches against the specification deltas. Your goal +is to find every way the implementation might NOT correctly realize +the specification changes. + +**Your default stance is skepticism.** Assume every implementation +change is wrong until you can prove it matches the specification. + +## Inputs + +**Project**: {{project_name}} + +**Specification Patch**: +{{spec_patch}} + +**Implementation Patch**: +{{implementation_patch}} + +**Existing Artifacts (for context)**: +{{existing_artifacts}} + +## Instructions + +### Step 1 — Audit Implementation Against Design Changes + +Apply the **code-compliance-audit protocol**: + +1. **Forward traceability** — every design change MUST have a + corresponding implementation change. Flag gaps as D8 + (unimplemented requirement). +2. **Backward traceability** — every implementation change MUST + trace to a design change. Flag undocumented behavior as D9. +3. **Constraint verification** — verify implementation does not + violate any stated constraint. Flag violations as D10. +4. Apply **operational-constraints** — focus on the behavioral + surface (APIs, interfaces, entry points) first, then trace + inward for verification. + +### Step 2 — Audit Verification Against Validation Changes + +Apply the **test-compliance-audit protocol**: + +1. **Forward traceability** — every validation change MUST have a + corresponding verification change (test, simulation, inspection). + Flag gaps as D11 (unimplemented test case). +2. **Acceptance criteria coverage** — verify verification artifacts + exercise ALL acceptance criteria from the validation changes. + Flag gaps as D12 (untested acceptance criterion). +3. **Assertion accuracy** — verify verification artifacts assert the + correct conditions and thresholds. Flag mismatches as D13 + (assertion mismatch). + +### Step 3 — Cross-Cutting Checks + +1. **Implementation-verification consistency** — does the + verification actually test the implementation change, or does + it test something else? +2. **Invariant preservation** — are all existing invariants and + contracts maintained by the implementation changes? +3. **Side effects** — does the implementation change introduce + behavior not covered by any specification change? + +### Step 4 — Adversarial Falsification + +Apply the **adversarial-falsification protocol**: + +1. For each finding candidate, attempt to **disprove it**. +2. For each "no issues found" area, attempt to **find an issue**. +3. Rate confidence: High / Medium / Low with justification. + +### Step 5 — Report + +Produce an investigation report with: + +1. **Executive Summary** — overall implementation alignment + assessment with key findings. +2. **Findings** — each classified with D8–D13 label, severity, + evidence (specific locations in both spec and implementation + patches), and remediation. +3. **Recommendations** — prioritized fixes. +4. **Verdict** — one of: + - **PASS** — implementation faithfully realizes the specification + changes, proceed to user review + - **REVISE-IMPLEMENTATION** — implementation issues found, loop + back to regenerate implementation patches + - **REVISE-SPEC** — specification issues discovered during + implementation audit, loop back to fix specifications + - **RESTART** — fundamental misalignment, loop back to + requirements discovery + +## Non-Goals + +- Do NOT evaluate code quality, style, or performance beyond what + the specification requires. +- Do NOT suggest improvements unrelated to spec alignment. +- Do NOT rewrite the patches — only identify issues and recommend fixes. + +## Quality Checklist + +- [ ] Every finding has a D8–D13 classification +- [ ] Every finding has specific evidence from both spec and + implementation patches +- [ ] Every finding has a concrete remediation +- [ ] Adversarial falsification was applied +- [ ] All specification changes accounted for in implementation +- [ ] All validation changes accounted for in verification +- [ ] Verdict clearly states PASS, REVISE-IMPLEMENTATION, + REVISE-SPEC, or RESTART diff --git a/templates/audit-spec-alignment.md b/templates/audit-spec-alignment.md new file mode 100644 index 0000000..a990b15 --- /dev/null +++ b/templates/audit-spec-alignment.md @@ -0,0 +1,151 @@ + + + +--- +name: audit-spec-alignment +description: > + Adversarial audit of specification patches against the user's + original intent. Verifies that requirements, design, and validation + changes faithfully represent what the user asked for, with no + drift, omissions, or scope creep. Domain-agnostic. +persona: specification-analyst +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - guardrails/adversarial-falsification + - reasoning/traceability-audit +taxonomies: + - specification-drift +format: investigation-report +params: + project_name: "Name of the project, product, or system" + user_intent: "The user's original description of what they wanted to change" + requirements_patch: "The structured requirements patch" + spec_patch: "The structured specification patch (design + validation changes)" + existing_artifacts: "Existing requirements, design, and validation documents for context" +input_contract: + type: structured-patch + description: > + Structured patches for requirements and specifications, plus the + user's original intent description. +output_contract: + type: investigation-report + description: > + An adversarial audit report classifying alignment findings using + the specification-drift taxonomy (D1–D7), with severity ratings + and remediation recommendations. +--- + +# Task: Adversarial Audit of Specification Alignment + +You are tasked with performing an **adversarial audit** of the +specification patches against the user's original intent. Your goal +is to find every way the patches might NOT faithfully represent what +the user asked for. + +**Your default stance is skepticism.** Assume every change is wrong +until you can prove it is correct. + +## Inputs + +**Project**: {{project_name}} + +**User's Original Intent**: +{{user_intent}} + +**Requirements Patch**: +{{requirements_patch}} + +**Specification Patch**: +{{spec_patch}} + +**Existing Artifacts (for context)**: +{{existing_artifacts}} + +## Instructions + +### Step 1 — Reconstruct Intent + +Before examining the patches, restate the user's intent in your own +words. Identify: + +1. What the user explicitly asked for +2. What the user implied but did not state +3. What the user explicitly excluded or constrained +4. Success criteria — how would the user judge whether the change + is correct? + +### Step 2 — Audit Requirements Patch Against Intent + +For each requirement change in the requirements patch: + +1. **Verify alignment** — does this change faithfully represent + part of the user's intent? +2. **Check for drift** — does this change go beyond what the user + asked for (scope creep)? Classify as D3 (orphaned design decision). +3. **Check for omissions** — is any part of the user's intent NOT + represented in the requirements changes? Classify as D1 (untraced + requirement). +4. **Check acceptance criteria** — are they specific, measurable, + and aligned with what the user would consider "done"? + Classify mismatches as D7. + +### Step 3 — Audit Specification Patch Against Requirements + +Apply the **traceability-audit protocol**: + +1. **Forward traceability** — every requirement change MUST have + corresponding design and validation changes. Flag gaps as D1 + (untraced) or D2 (untested). +2. **Backward traceability** — every design/validation change MUST + trace to a requirement change. Flag orphans as D3 or D4. +3. **Cross-document consistency** — verify assumptions, constraints, + and terminology are consistent across all patches. Flag drift + as D5 or D6. +4. **Acceptance criteria coverage** — verify test cases cover all + acceptance criteria including negative cases and boundaries. + Flag gaps as D7. + +### Step 4 — Adversarial Falsification + +Apply the **adversarial-falsification protocol**: + +1. For each finding candidate, attempt to **disprove it** before + reporting. Can you construct a reasonable interpretation where + the change IS aligned? +2. For each "no issues found" area, attempt to **find an issue**. + Challenge your own conclusion. +3. Rate confidence: High (verified through direct evidence), + Medium (reasonable but uncertain), Low (plausible but weak). + +### Step 5 — Report + +Produce an investigation report with: + +1. **Executive Summary** — overall alignment assessment (Aligned / + Partially Aligned / Misaligned) with key findings. +2. **Findings** — each classified with a D1–D7 label, severity, + evidence, and specific remediation. +3. **Recommendations** — prioritized list of changes needed to + restore alignment. +4. **Verdict** — one of: + - **PASS** — patches faithfully represent user intent, proceed + to user review + - **REVISE** — specific issues found, loop back to fix patches + - **RESTART** — fundamental misalignment, loop back to + requirements discovery + +## Non-Goals + +- Do NOT suggest improvements unrelated to alignment. +- Do NOT evaluate implementation quality — only alignment. +- Do NOT rewrite the patches — only identify issues and recommend fixes. + +## Quality Checklist + +- [ ] Every finding has a D1–D7 classification +- [ ] Every finding has specific evidence (not vague concerns) +- [ ] Every finding has a concrete remediation +- [ ] Adversarial falsification was applied — findings survived disproof +- [ ] User's original intent was fully accounted for +- [ ] Verdict clearly states PASS, REVISE, or RESTART diff --git a/templates/collaborate-requirements-change.md b/templates/collaborate-requirements-change.md new file mode 100644 index 0000000..9aab2bb --- /dev/null +++ b/templates/collaborate-requirements-change.md @@ -0,0 +1,140 @@ + + + +--- +name: collaborate-requirements-change +mode: interactive +description: > + Interactive requirements discovery for incremental changes. + Work with the user to understand what they want to change, + refine the requirements, and produce a structured requirements + patch. Domain-agnostic — works for software, hardware, + protocol, or any engineering domain. +persona: "{{persona}}" +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - reasoning/requirements-elicitation + - reasoning/iterative-refinement +format: structured-patch +params: + persona: "Persona to use — select from library or describe a custom one" + project_name: "Name of the project, product, or system being changed" + change_description: "Natural language description of the desired change" + existing_artifacts: "Existing requirements, design docs, specs — paste or reference" + context: "Additional context — system architecture, constraints, domain conventions" +input_contract: null +output_contract: + type: structured-patch + description: > + A structured requirements patch with traceable change entries, + each linked to the user's stated intent. Ready for downstream + propagation to design, validation, and implementation artifacts. +--- + +# Task: Collaborative Requirements Change Discovery + +You are tasked with working **interactively** with the user to produce +a structured requirements patch. You do NOT generate the patch +immediately. Instead, you follow a multi-phase process to ensure the +requirements changes are clear, complete, and traceable. + +## Inputs + +**Project**: {{project_name}} + +**Desired Change**: +{{change_description}} + +**Existing Artifacts**: +{{existing_artifacts}} + +**Additional Context**: +{{context}} + +## Phase 1 — Understand Intent + +Before producing any patch, engage the user interactively: + +1. **Restate the change** in your own words and ask the user to confirm + or correct your understanding. +2. **Ask clarifying questions** — probe for specifics, edge cases, + acceptance criteria, and unstated constraints. +3. **Identify affected requirements** — which existing REQ-IDs are + impacted? Are new requirements needed? Are any requirements + being retired? +4. **Surface implicit requirements** — changes often have ripple + effects. Identify secondary requirements the user may not have + considered (e.g., backward compatibility, migration, validation). +5. **Challenge scope** — is the user asking for the right change? + Are there simpler alternatives? Are there hidden costs? + +### Critical Rule + +**Do NOT produce the requirements patch until the user explicitly +says the discovery phase is complete** (e.g., "READY", "proceed", +"generate the patch"). If you are unsure, ask. + +Continue until: +- You have no remaining ambiguities, OR +- The user declares Phase 1 complete. + +## Phase 2 — Generate Requirements Patch + +Once the user declares Phase 1 complete: + +1. **Apply the requirements-elicitation protocol** to decompose + changes into atomic, testable requirement modifications. +2. **Apply the anti-hallucination protocol** — ground every change + in what was discussed. Flag assumptions with `[ASSUMED]`. +3. **Format the output** according to the structured-patch format: + - Change manifest summarizing all requirement changes + - Detailed change entries with Before/After content + - Each change traces to `USER-REQUEST: ` + - Invariant impact assessment +4. **Include a Pre-Patch Analysis** section before the patch: + - Ambiguities resolved during Phase 1 (and how) + - Ambiguities that remain unresolved + - Existing requirements affected + - New requirements introduced + - Requirements retired or modified + +**Requirement change entry rules**: +- New requirements MUST use the next available REQ-ID in the + existing numbering scheme. +- Modified requirements MUST preserve the original REQ-ID. +- Retired requirements MUST be marked as removed, not renumbered. +- Every requirement MUST have acceptance criteria. + +## Phase 3 — Refinement + +After producing the patch, enter a refinement loop: + +1. The user will review and request changes. +2. **Apply the iterative-refinement protocol**: + - Make surgical changes to the patch + - Preserve change IDs and traceability + - Justify every modification +3. Continue until the user declares the patch **FINAL**. + +## Non-Goals + +Define at the start of the session (or ask the user) what is +explicitly out of scope for this change: + +- What parts of the system are NOT being changed? +- Are we changing requirements only, or also design/implementation? +- What backward compatibility constraints exist? + +## Quality Checklist + +Before presenting the patch in Phase 2, verify: + +- [ ] Every change has a unique CHG-ID +- [ ] Every change traces to a user request or discussed requirement +- [ ] Every new/modified requirement has acceptance criteria +- [ ] Every new/modified requirement uses RFC 2119 keywords +- [ ] No existing requirement IDs are renumbered +- [ ] Invariant impact section is present and complete +- [ ] No fabricated requirements — all unknowns marked with [UNKNOWN] +- [ ] Traceability matrix accounts for every discussed change diff --git a/templates/dev-workflow.md b/templates/dev-workflow.md new file mode 100644 index 0000000..65d0838 --- /dev/null +++ b/templates/dev-workflow.md @@ -0,0 +1,303 @@ + + + +--- +name: dev-workflow +mode: interactive +description: > + Full incremental development workflow with human-in-the-loop review. + Guides an agent through requirements discovery, specification changes, + implementation changes, adversarial audits, and deliverable creation. + Domain-agnostic — works for software, hardware, protocol, or any + engineering domain. Users select their domain by choosing a persona. +persona: "{{persona}}" +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - guardrails/adversarial-falsification + - guardrails/operational-constraints + - reasoning/requirements-elicitation + - reasoning/iterative-refinement + - reasoning/change-propagation + - reasoning/traceability-audit + - reasoning/code-compliance-audit + - reasoning/test-compliance-audit +taxonomies: + - specification-drift +format: structured-patch +params: + persona: "Persona to use — select from library (e.g., software-architect, electrical-engineer, mechanical-engineer)" + project_name: "Name of the project, product, or system being changed" + change_description: "Natural language description of the desired change" + existing_artifacts: "Existing requirements, design, validation, implementation, and verification artifacts" + context: "Additional context — architecture, constraints, domain conventions, toolchain" +input_contract: null +output_contract: + type: structured-patch + description: > + A set of structured patches covering requirements, specifications, + and implementation changes, each fully traceable. Accompanied by + adversarial audit reports at each transition. +--- + +# Task: Incremental Development Workflow + +You are tasked with guiding the user through a **complete incremental +development cycle** — from understanding what they want to change, +through specifications and implementation, to a deliverable. + +This is a multi-phase, interactive workflow. You will cycle through +two major loops (specification and implementation), with adversarial +audits and user reviews at each transition. + +## Inputs + +**Project**: {{project_name}} + +**Desired Change**: +{{change_description}} + +**Existing Artifacts**: +{{existing_artifacts}} + +**Additional Context**: +{{context}} + +--- + +## Workflow Overview + +``` +Phase 1: Requirements Discovery (interactive) + ↓ +Phase 2: Specification Changes (requirements + design + validation) + ↓ +Phase 3: Specification Audit (adversarial) + ↓ ← loop back to Phase 1 or 2 if REVISE/RESTART +Phase 4: User Review of Specifications + ↓ ← loop back to Phase 1, 2, or 3 if user requests +Phase 5: Implementation Changes (implementation + verification) + ↓ +Phase 6: Implementation Audit (adversarial) + ↓ ← loop back to Phase 1, 2, or 5 if REVISE/RESTART +Phase 7: User Review of Implementation + ↓ ← loop back to Phase 1, 2, 5, or 6 if user requests +Phase 8: Create Deliverable +``` + +--- + +## Phase 1 — Requirements Discovery + +**Goal**: Understand what the user wants to change and produce a +structured requirements patch. + +1. **Restate** the desired change and confirm understanding. +2. **Ask clarifying questions** — probe for specifics, edge cases, + acceptance criteria, and unstated constraints. +3. **Identify affected requirements** — which existing REQ-IDs are + impacted? New requirements needed? Any retired? +4. **Surface implicit requirements** — ripple effects the user may + not have considered. +5. **Challenge scope** — is this the right change? Simpler + alternatives? Hidden costs? + +### Critical Rule + +**Do NOT proceed to Phase 2 until the user explicitly says the +discovery phase is complete** (e.g., "READY", "proceed"). + +### Output + +A structured requirements patch with: +- Change manifest +- Detailed change entries (Before/After with REQ-IDs) +- Each change linked to `USER-REQUEST: ` +- Invariant impact assessment + +--- + +## Phase 2 — Specification Changes + +**Goal**: Propagate requirements changes to design and validation +specifications. + +Apply the **change-propagation protocol**: + +1. **Impact analysis** — identify affected design sections and + validation entries. +2. **Design changes** — derive minimal design changes for each + requirement change. +3. **Validation changes** — update or add test cases for each + requirement change. +4. **Invariant check** — verify no existing invariants are broken. +5. **Completeness check** — every requirement change has downstream + specification changes. +6. **Conflict detection** — no contradictions between design and + validation changes. + +### Output + +A structured specification patch with full traceability to the +requirements patch. + +--- + +## Phase 3 — Specification Audit + +**Goal**: Adversarially verify that specifications faithfully +represent the user's intent. + +Apply the **traceability-audit** and **adversarial-falsification** +protocols: + +1. **Reconstruct intent** — restate what the user originally asked for. +2. **Audit requirements against intent** — check for drift, omissions, + scope creep. Use D1–D7 classifications. +3. **Audit specs against requirements** — forward and backward + traceability, consistency, acceptance criteria coverage. +4. **Adversarial falsification** — try to disprove each finding AND + try to find issues in "clean" areas. + +### Verdict + +- **PASS** → proceed to Phase 4 (user review) +- **REVISE** → state specific issues, return to Phase 2 (or Phase 1 + if requirements need changes), fix, and re-audit +- **RESTART** → fundamental misalignment, return to Phase 1 + +Present the audit report to the user with the verdict. + +--- + +## Phase 4 — User Review of Specifications + +**Goal**: Get user approval of specification changes before +proceeding to implementation. + +Present to the user: +1. The requirements patch (from Phase 1) +2. The specification patch (from Phase 2) +3. The audit report (from Phase 3) +4. A summary of what will change and what is unaffected + +Ask the user to review and respond with one of: +- **APPROVED** → proceed to Phase 5 +- **REVISE** → take feedback, return to Phase 2 or Phase 1 +- Specific change requests → incorporate and re-run from Phase 2 + +--- + +## Phase 5 — Implementation Changes + +**Goal**: Propagate specification changes to implementation and +verification artifacts. + +Apply the **change-propagation protocol**: + +1. **Impact analysis** — identify affected implementation and + verification artifacts. +2. **Implementation changes** — derive minimal changes to realize + the updated specifications. +3. **Verification changes** — update or add tests/simulations/ + inspections for each validation change. +4. **Invariant check** — verify existing contracts are preserved. +5. **Completeness and conflict checks**. + +Apply the **operational-constraints protocol** — focus on the +behavioral surface first, trace inward for verification. + +### Output + +A structured implementation patch with full traceability to the +specification patch. + +--- + +## Phase 6 — Implementation Audit + +**Goal**: Adversarially verify that implementation correctly +realizes the specification changes. + +Apply the **code-compliance-audit**, **test-compliance-audit**, +and **adversarial-falsification** protocols: + +1. **Forward traceability** — every spec change implemented. + Flag D8 (unimplemented). +2. **Backward traceability** — no undocumented behavior. + Flag D9. +3. **Constraint verification** — no violations. Flag D10. +4. **Test coverage** — all validation changes have verification. + Flag D11, D12, D13. +5. **Adversarial falsification** — disprove findings, challenge + clean areas. + +### Verdict + +- **PASS** → proceed to Phase 7 (user review) +- **REVISE-IMPLEMENTATION** → fix implementation, return to Phase 5 +- **REVISE-SPEC** → specification issues found, return to Phase 2 +- **RESTART** → return to Phase 1 + +Present the audit report to the user with the verdict. + +--- + +## Phase 7 — User Review of Implementation + +**Goal**: Get user approval of implementation changes. + +Present to the user: +1. The implementation patch (from Phase 5) +2. The audit report (from Phase 6) +3. A summary of all artifacts changed across the full workflow + +Ask the user to respond with one of: +- **APPROVED** → proceed to Phase 8 +- **REVISE** → take feedback, return to Phase 5, 2, or 1 +- Specific change requests → incorporate and re-run + +--- + +## Phase 8 — Create Deliverable + +**Goal**: Package all changes into a deliverable. + +Based on the user's workflow preference: + +### Option A: Git-Based Workflow +1. Stage all changed files +2. Generate a commit message summarizing the full change chain +3. Create a pull request with: + - Description tracing requirements → specs → implementation + - Links to audit reports + - Traceability summary + +### Option B: Patch Set +1. Produce a consolidated patch set containing: + - Requirements patch + - Specification patch + - Implementation patch + - Audit reports +2. Include application instructions + +### Option C: Design Package +1. Produce a design review package containing: + - Updated specifications + - Change summary + - Audit reports + - BOM/schematic updates (for hardware domains) + +Ask the user which deliverable format they prefer if not obvious +from context. + +--- + +## Non-Goals + +- Do NOT skip phases — each phase exists for a reason. +- Do NOT auto-approve — every audit verdict and user review is a + real gate. +- Do NOT mix phases — complete one phase before starting the next + (except when looping back). +- Do NOT introduce changes unrelated to the user's original request. diff --git a/templates/generate-implementation-changes.md b/templates/generate-implementation-changes.md new file mode 100644 index 0000000..bce4ce4 --- /dev/null +++ b/templates/generate-implementation-changes.md @@ -0,0 +1,146 @@ + + + +--- +name: generate-implementation-changes +description: > + Generate implementation and verification changes from a specification + patch. Propagates each design and validation change to the appropriate + implementation artifacts (code, schematics, configurations) and + verification artifacts (tests, simulations, inspections). + Domain-agnostic. +persona: "{{persona}}" +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - guardrails/operational-constraints + - reasoning/change-propagation +format: structured-patch +params: + persona: "Persona to use — select from library or describe a custom one" + project_name: "Name of the project, product, or system" + spec_patch: "The structured specification patch (output of generate-spec-changes or equivalent)" + implementation_artifacts: "Existing implementation — code, schematics, configurations, or other artifacts" + verification_artifacts: "Existing tests, simulations, inspection procedures, or other verification artifacts" + context: "Additional context — build system, toolchain, domain conventions, coding standards" +input_contract: + type: structured-patch + description: > + A structured specification patch with design and validation changes, + each tracing to a requirement change. +output_contract: + type: structured-patch + description: > + A structured patch covering implementation and verification changes, + with every change tracing to a specification change from the input + patch. +--- + +# Task: Generate Implementation Changes + +You are tasked with propagating specification changes into implementation +and verification changes. Every downstream change MUST trace to an +upstream specification change. + +## Inputs + +**Project**: {{project_name}} + +**Specification Patch**: +{{spec_patch}} + +**Existing Implementation**: +{{implementation_artifacts}} + +**Existing Verification Artifacts**: +{{verification_artifacts}} + +**Additional Context**: +{{context}} + +## Instructions + +Apply the **change-propagation protocol** in order: + +### Step 1 — Impact Analysis + +For each specification change in the input patch: + +1. Identify which implementation artifacts are **directly affected** + (files, modules, components, schematic sheets that implement the + changed design section). +2. Identify which verification artifacts are **directly affected** + (test files, simulation configs, inspection checklists linked to + the changed validation entries). +3. Identify **indirect impacts** — artifacts that depend on interfaces, + data structures, or behaviors affected by the specification change. +4. Apply the **operational-constraints protocol** — focus on the + behavioral surface first (APIs, entry points, interfaces), then + trace inward only as needed for verification. + +### Step 2 — Implementation Changes + +For each impacted implementation artifact: + +1. Derive the **minimal necessary change** to implement the updated + specification. +2. Draft a change entry with Before/After content showing exact + modifications with sufficient surrounding context. +3. Preserve existing style, conventions, and patterns of the + implementation. +4. Record the upstream specification change (CHG-ID from the input + patch) as the upstream ref. + +### Step 3 — Verification Changes + +For each impacted verification artifact: + +1. If an existing test/verification covers the changed specification + entry, **modify** it to match the updated acceptance criteria. +2. If no verification exists for a new specification entry, **add** + new verification artifacts following existing patterns and naming. +3. If a specification entry is retired, **remove** linked verification + (or update if shared with other entries). +4. Ensure verification changes exercise ALL acceptance criteria — + including negative cases, boundary conditions, and ordering + constraints. + +### Step 4 — Assemble Patch + +Produce a single structured-patch document containing: + +1. **Change Context** — reference the input specification patch as + the upstream artifact. +2. **Change Manifest** — all implementation and verification changes. +3. **Detailed Changes** — full Before/After for every change, with + upstream refs pointing to the specification patch CHG-IDs. +4. **Traceability Matrix** — every specification change mapped to its + downstream implementation and verification changes. +5. **Invariant Impact** — assess which existing invariants, constraints, + or runtime assumptions are affected. +6. **Application Notes** — how to apply (git diff, manual edit, + schematic update, etc.), build/compile verification steps, and + rollback instructions. + +## Non-Goals + +- Do NOT refactor or improve unrelated implementation. +- Do NOT introduce changes beyond what the specification patch requires. +- Do NOT change build systems, tooling, or infrastructure unless the + specification change explicitly requires it. +- Note improvement opportunities separately as recommendations. + +## Quality Checklist + +Before presenting the patch, verify: + +- [ ] Every implementation change traces to a specification change +- [ ] Every verification change traces to a specification change +- [ ] Every specification change has at least one downstream change + (or explicit "no impact" justification) +- [ ] Implementation follows existing style and conventions +- [ ] Verification covers all acceptance criteria (positive, negative, + boundary) +- [ ] No invariants broken without explicit acknowledgment +- [ ] Before/After content is unambiguous and directly applicable +- [ ] Application notes include build/compile verification steps diff --git a/templates/generate-spec-changes.md b/templates/generate-spec-changes.md new file mode 100644 index 0000000..832b85a --- /dev/null +++ b/templates/generate-spec-changes.md @@ -0,0 +1,132 @@ + + + +--- +name: generate-spec-changes +description: > + Generate design and validation specification changes from a + requirements patch. Propagates each requirement change to the + appropriate design sections and validation test cases, maintaining + full traceability. Domain-agnostic. +persona: "{{persona}}" +protocols: + - guardrails/anti-hallucination + - guardrails/self-verification + - reasoning/change-propagation +format: structured-patch +params: + persona: "Persona to use — select from library or describe a custom one" + project_name: "Name of the project, product, or system" + requirements_patch: "The structured requirements patch (output of collaborate-requirements-change or equivalent)" + design_doc: "Existing design document or specification" + validation_plan: "Existing validation plan or test specification" + context: "Additional context — architecture, constraints, domain conventions" +input_contract: + type: structured-patch + description: > + A structured requirements patch with CHG-IDs, Before/After content, + and traceability to user intent. +output_contract: + type: structured-patch + description: > + A structured patch covering design and validation changes, with + every change tracing to a requirement change from the input patch. +--- + +# Task: Generate Specification Changes + +You are tasked with propagating requirements changes into design and +validation specification changes. Every downstream change MUST trace +to an upstream requirement change. + +## Inputs + +**Project**: {{project_name}} + +**Requirements Patch**: +{{requirements_patch}} + +**Existing Design Document**: +{{design_doc}} + +**Existing Validation Plan**: +{{validation_plan}} + +**Additional Context**: +{{context}} + +## Instructions + +Apply the **change-propagation protocol** in order: + +### Step 1 — Impact Analysis + +For each requirement change in the input patch: + +1. Identify which design document sections are **directly affected** + (sections that reference or implement the changed requirement). +2. Identify which validation plan entries are **directly affected** + (test cases linked to the changed requirement). +3. Identify **indirect impacts** — sections that depend on assumptions + or constraints affected by the requirement change. +4. For sections verified as unaffected, state WHY. + +### Step 2 — Design Changes + +For each impacted design section: + +1. Derive the **minimal necessary change** to restore alignment with + the updated requirement. +2. Draft a change entry with Before/After content. +3. Record the upstream requirement change (CHG-ID from the input patch) + as the upstream ref. + +### Step 3 — Validation Changes + +For each impacted validation entry: + +1. If an existing test case covers the changed requirement, **modify** + the test case to reflect the new acceptance criteria. +2. If no test case exists for a new requirement, **add** a new test + case with a TC-ID following the existing numbering scheme. +3. If a requirement is retired, **remove** the linked test case + (or mark it for retirement if it covers other requirements too). +4. Verify every requirement in the patch has at least one linked + test case after changes are applied. + +### Step 4 — Assemble Patch + +Produce a single structured-patch document containing: + +1. **Change Context** — reference the input requirements patch as + the upstream artifact. +2. **Change Manifest** — all design and validation changes in one table. +3. **Detailed Changes** — full Before/After for every change, with + upstream refs pointing to the requirement patch CHG-IDs. +4. **Traceability Matrix** — every requirement change mapped to its + downstream design and validation changes. +5. **Invariant Impact** — assess which existing invariants, constraints, + or assumptions are affected. +6. **Application Notes** — how to apply these changes to the existing + design document and validation plan. + +## Non-Goals + +- Do NOT introduce changes beyond what the requirements patch requires. +- Do NOT redesign unaffected sections. +- Do NOT add speculative features or improvements. +- If you identify issues in the existing design unrelated to this change, + note them separately as recommendations. + +## Quality Checklist + +Before presenting the patch, verify: + +- [ ] Every design change traces to a requirement change +- [ ] Every validation change traces to a requirement change +- [ ] Every requirement change has at least one downstream change + (or an explicit "no impact" justification) +- [ ] No invariants are broken without explicit acknowledgment +- [ ] No internal conflicts between design and validation changes +- [ ] Before/After content is unambiguous and sufficient to apply +- [ ] Traceability matrix is complete — no upstream changes dropped From 2d20bb12b422659043dd1e4064cd5844ddb520bf Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Sun, 29 Mar 2026 20:13:34 -0700 Subject: [PATCH 2/5] Rename dev-workflow to engineering-workflow The workflow is domain-agnostic and applies to all engineering disciplines, not just software development. Rename to reflect this. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- manifest.yaml | 12 ++++++------ protocols/reasoning/change-propagation.md | 2 +- .../{dev-workflow.md => engineering-workflow.md} | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) rename templates/{dev-workflow.md => engineering-workflow.md} (99%) diff --git a/manifest.yaml b/manifest.yaml index 193b61d..dc77caa 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -1307,11 +1307,11 @@ templates: protocols: [anti-hallucination, self-verification, protocol-validation-design] format: protocol-validation-spec - dev-workflow: - - name: dev-workflow - path: templates/dev-workflow.md + engineering-workflow: + - name: engineering-workflow + path: templates/engineering-workflow.md description: > - Full incremental development workflow with human-in-the-loop + Full incremental engineering workflow with human-in-the-loop review. Guides an agent through requirements discovery, specification changes, implementation changes, adversarial audits, and deliverable creation. Domain-agnostic. @@ -1428,9 +1428,9 @@ pipelines: consumes: requirements-document produces: investigation-report - dev-workflow: + engineering-workflow: description: > - Domain-agnostic incremental development workflow with + Domain-agnostic incremental engineering workflow with human-in-the-loop review. Propagates changes through requirements, specifications, and implementation with adversarial audits at each transition. Phases can loop diff --git a/protocols/reasoning/change-propagation.md b/protocols/reasoning/change-propagation.md index 7cd9101..1855fd8 100644 --- a/protocols/reasoning/change-propagation.md +++ b/protocols/reasoning/change-propagation.md @@ -13,7 +13,7 @@ description: > applicable_to: - generate-spec-changes - generate-implementation-changes - - dev-workflow + - engineering-workflow --- # Protocol: Change Propagation diff --git a/templates/dev-workflow.md b/templates/engineering-workflow.md similarity index 99% rename from templates/dev-workflow.md rename to templates/engineering-workflow.md index 65d0838..088f1d4 100644 --- a/templates/dev-workflow.md +++ b/templates/engineering-workflow.md @@ -2,7 +2,7 @@ --- -name: dev-workflow +name: engineering-workflow mode: interactive description: > Full incremental development workflow with human-in-the-loop review. From b5ac8bc93fd49e51bc132addefd2b4c3c5bea79f Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Sun, 29 Mar 2026 20:16:56 -0700 Subject: [PATCH 3/5] Address review: format compliance and protocol alignment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add mandatory section rule to structured-patch format (all 6 sections required even if empty, state 'None identified') - Add No-Impact status to traceability matrix (aligns with change-propagation protocol's completeness check) - Fix [ASSUMED] → [ASSUMPTION] to match anti-hallucination protocol - Fix [UNKNOWN] → [UNKNOWN: ] for specificity - Move Pre-Patch Analysis inside Change Context section to comply with structured-patch format's fixed section ordering Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- formats/structured-patch.md | 6 ++++++ templates/collaborate-requirements-change.md | 6 +++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/formats/structured-patch.md b/formats/structured-patch.md index a5328f8..92e78e0 100644 --- a/formats/structured-patch.md +++ b/formats/structured-patch.md @@ -33,6 +33,10 @@ request) so reviewers can verify alignment at each transition. ## 6. Application Notes ``` +All six top-level sections (1–6) are **mandatory**. If a section has no +content for this patch, still include the heading and state "None identified" +or "Not applicable" rather than omitting the section. + ## 1. Change Context Provide the context for this patch set: @@ -113,6 +117,8 @@ Map every upstream change to its downstream changes: **Status values**: - **Complete** — all necessary downstream changes are included - **Partial** — some downstream changes are deferred (explain in notes) +- **No-Impact** — upstream change verified to have no downstream effect + (MUST include rationale) - **Blocked** — downstream changes cannot be made yet (explain why) ## 5. Invariant Impact diff --git a/templates/collaborate-requirements-change.md b/templates/collaborate-requirements-change.md index 9aab2bb..bb784fa 100644 --- a/templates/collaborate-requirements-change.md +++ b/templates/collaborate-requirements-change.md @@ -86,13 +86,13 @@ Once the user declares Phase 1 complete: 1. **Apply the requirements-elicitation protocol** to decompose changes into atomic, testable requirement modifications. 2. **Apply the anti-hallucination protocol** — ground every change - in what was discussed. Flag assumptions with `[ASSUMED]`. + in what was discussed. Flag assumptions with `[ASSUMPTION]`. 3. **Format the output** according to the structured-patch format: - Change manifest summarizing all requirement changes - Detailed change entries with Before/After content - Each change traces to `USER-REQUEST: ` - Invariant impact assessment -4. **Include a Pre-Patch Analysis** section before the patch: +4. **Include a Pre-Patch Analysis** inside the Change Context section: - Ambiguities resolved during Phase 1 (and how) - Ambiguities that remain unresolved - Existing requirements affected @@ -136,5 +136,5 @@ Before presenting the patch in Phase 2, verify: - [ ] Every new/modified requirement uses RFC 2119 keywords - [ ] No existing requirement IDs are renumbered - [ ] Invariant impact section is present and complete -- [ ] No fabricated requirements — all unknowns marked with [UNKNOWN] +- [ ] No fabricated requirements — all unknowns marked with [UNKNOWN: ] - [ ] Traceability matrix accounts for every discussed change From 18a87e3aa0f987d98e1c6e6d7f2ea59082da1897 Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Sun, 29 Mar 2026 20:26:41 -0700 Subject: [PATCH 4/5] Address review: format compliance, pipeline ordering, PR naming - Clarify engineering-workflow output_contract to describe multiple artifacts across phases (patches + audit reports) - Remove consumes from post-audit pipeline stages that don't consume the immediately previous stage's output type - Audit templates now explicitly follow investigation-report format's required 9-section structure with verdict in Open Questions section - (PR description updated separately to reflect engineering-workflow name) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- manifest.yaml | 1 - templates/audit-implementation-alignment.md | 16 ++++++++++------ templates/audit-spec-alignment.md | 15 +++++++++------ templates/engineering-workflow.md | 7 ++++--- 4 files changed, 23 insertions(+), 16 deletions(-) diff --git a/manifest.yaml b/manifest.yaml index dc77caa..b07b416 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -1445,7 +1445,6 @@ pipelines: consumes: structured-patch produces: investigation-report - template: generate-implementation-changes - consumes: structured-patch produces: structured-patch - template: audit-implementation-alignment consumes: structured-patch diff --git a/templates/audit-implementation-alignment.md b/templates/audit-implementation-alignment.md index d7c0ce9..b1f7353 100644 --- a/templates/audit-implementation-alignment.md +++ b/templates/audit-implementation-alignment.md @@ -111,15 +111,19 @@ Apply the **adversarial-falsification protocol**: ### Step 5 — Report -Produce an investigation report with: +Produce an investigation report following the **investigation-report +format's required 9-section structure** exactly. Do not add, remove, +or reorder top-level sections. Map this template's content as follows: -1. **Executive Summary** — overall implementation alignment - assessment with key findings. -2. **Findings** — each classified with D8–D13 label, severity, +- **Executive Summary** — overall implementation alignment assessment + with key D8–D13 findings. +- **Findings** — each classified with D8–D13 label, severity, evidence (specific locations in both spec and implementation patches), and remediation. -3. **Recommendations** — prioritized fixes. -4. **Verdict** — one of: +- **Remediation Plan** — prioritized fixes. +- **Open Questions** — include the **Verdict** as a clearly labeled + line: `Verdict: PASS | REVISE-IMPLEMENTATION | REVISE-SPEC | RESTART`, + where: - **PASS** — implementation faithfully realizes the specification changes, proceed to user review - **REVISE-IMPLEMENTATION** — implementation issues found, loop diff --git a/templates/audit-spec-alignment.md b/templates/audit-spec-alignment.md index a990b15..0799013 100644 --- a/templates/audit-spec-alignment.md +++ b/templates/audit-spec-alignment.md @@ -120,15 +120,18 @@ Apply the **adversarial-falsification protocol**: ### Step 5 — Report -Produce an investigation report with: +Produce an investigation report following the **investigation-report +format's required 9-section structure** exactly. Do not add, remove, +or reorder top-level sections. Map this template's content as follows: -1. **Executive Summary** — overall alignment assessment (Aligned / - Partially Aligned / Misaligned) with key findings. -2. **Findings** — each classified with a D1–D7 label, severity, +- **Executive Summary** — overall alignment assessment (Aligned / + Partially Aligned / Misaligned) with key D1–D7 findings. +- **Findings** — each classified with a D1–D7 label, severity, evidence, and specific remediation. -3. **Recommendations** — prioritized list of changes needed to +- **Remediation Plan** — prioritized list of changes needed to restore alignment. -4. **Verdict** — one of: +- **Open Questions** — include the **Verdict** as a clearly labeled + line: `Verdict: PASS | REVISE | RESTART`, where: - **PASS** — patches faithfully represent user intent, proceed to user review - **REVISE** — specific issues found, loop back to fix patches diff --git a/templates/engineering-workflow.md b/templates/engineering-workflow.md index 088f1d4..b8d3290 100644 --- a/templates/engineering-workflow.md +++ b/templates/engineering-workflow.md @@ -35,9 +35,10 @@ input_contract: null output_contract: type: structured-patch description: > - A set of structured patches covering requirements, specifications, - and implementation changes, each fully traceable. Accompanied by - adversarial audit reports at each transition. + Multiple structured-patch documents produced across phases + (requirements patch, specification patch, implementation patch), + each fully traceable. Audit phases produce investigation-report + artifacts with PASS/REVISE/RESTART verdicts that gate progression. --- # Task: Incremental Development Workflow From 4a4c46a5ee058622f000bb7d6052579e2de5313f Mon Sep 17 00:00:00 2001 From: Alan Jowett Date: Sun, 29 Mar 2026 20:37:57 -0700 Subject: [PATCH 5/5] Address review: distinct artifact types and multi-artifact format - Introduce distinct artifact types (requirements-patch, spec-patch, implementation-patch) in pipeline stages and template contracts for unambiguous artifact handoff - Switch engineering-workflow format to multi-artifact since it produces multiple artifact types across phases (patches + audit reports) - Update output_contract to artifact-set type - Fix protocol ordering in manifest for generate-implementation-changes to match frontmatter (operational-constraints before change-propagation) - Update input_contracts on audit templates to declare multi-type inputs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- manifest.yaml | 17 +++++++++-------- templates/audit-implementation-alignment.md | 2 +- templates/audit-spec-alignment.md | 2 +- templates/collaborate-requirements-change.md | 2 +- templates/engineering-workflow.md | 12 ++++++------ templates/generate-implementation-changes.md | 4 ++-- templates/generate-spec-changes.md | 4 ++-- 7 files changed, 22 insertions(+), 21 deletions(-) diff --git a/manifest.yaml b/manifest.yaml index b07b416..c759c1f 100644 --- a/manifest.yaml +++ b/manifest.yaml @@ -1318,7 +1318,7 @@ templates: persona: configurable protocols: [anti-hallucination, self-verification, adversarial-falsification, operational-constraints, requirements-elicitation, iterative-refinement, change-propagation, traceability-audit, code-compliance-audit, test-compliance-audit] taxonomies: [specification-drift] - format: structured-patch + format: multi-artifact - name: collaborate-requirements-change path: templates/collaborate-requirements-change.md @@ -1347,7 +1347,7 @@ templates: specification patch. Propagates design and validation changes to implementation artifacts. Domain-agnostic. persona: configurable - protocols: [anti-hallucination, self-verification, change-propagation, operational-constraints] + protocols: [anti-hallucination, self-verification, operational-constraints, change-propagation] format: structured-patch - name: audit-spec-alignment @@ -1437,15 +1437,16 @@ pipelines: back based on audit verdicts or user feedback. stages: - template: collaborate-requirements-change - produces: structured-patch + produces: requirements-patch - template: generate-spec-changes - consumes: structured-patch - produces: structured-patch + consumes: requirements-patch + produces: spec-patch - template: audit-spec-alignment - consumes: structured-patch + consumes: [requirements-patch, spec-patch] produces: investigation-report - template: generate-implementation-changes - produces: structured-patch + consumes: spec-patch + produces: implementation-patch - template: audit-implementation-alignment - consumes: structured-patch + consumes: [spec-patch, implementation-patch] produces: investigation-report diff --git a/templates/audit-implementation-alignment.md b/templates/audit-implementation-alignment.md index b1f7353..cf2c775 100644 --- a/templates/audit-implementation-alignment.md +++ b/templates/audit-implementation-alignment.md @@ -25,7 +25,7 @@ params: implementation_patch: "The structured implementation patch (code/artifact + verification changes)" existing_artifacts: "Existing implementation and verification artifacts for context" input_contract: - type: structured-patch + type: [spec-patch, implementation-patch] description: > Structured patches for specifications and implementation, to be audited for alignment. diff --git a/templates/audit-spec-alignment.md b/templates/audit-spec-alignment.md index 0799013..2f834c9 100644 --- a/templates/audit-spec-alignment.md +++ b/templates/audit-spec-alignment.md @@ -24,7 +24,7 @@ params: spec_patch: "The structured specification patch (design + validation changes)" existing_artifacts: "Existing requirements, design, and validation documents for context" input_contract: - type: structured-patch + type: [requirements-patch, spec-patch] description: > Structured patches for requirements and specifications, plus the user's original intent description. diff --git a/templates/collaborate-requirements-change.md b/templates/collaborate-requirements-change.md index bb784fa..6cff908 100644 --- a/templates/collaborate-requirements-change.md +++ b/templates/collaborate-requirements-change.md @@ -25,7 +25,7 @@ params: context: "Additional context — system architecture, constraints, domain conventions" input_contract: null output_contract: - type: structured-patch + type: requirements-patch description: > A structured requirements patch with traceable change entries, each linked to the user's stated intent. Ready for downstream diff --git a/templates/engineering-workflow.md b/templates/engineering-workflow.md index b8d3290..a4868f5 100644 --- a/templates/engineering-workflow.md +++ b/templates/engineering-workflow.md @@ -24,7 +24,7 @@ protocols: - reasoning/test-compliance-audit taxonomies: - specification-drift -format: structured-patch +format: multi-artifact params: persona: "Persona to use — select from library (e.g., software-architect, electrical-engineer, mechanical-engineer)" project_name: "Name of the project, product, or system being changed" @@ -33,12 +33,12 @@ params: context: "Additional context — architecture, constraints, domain conventions, toolchain" input_contract: null output_contract: - type: structured-patch + type: artifact-set description: > - Multiple structured-patch documents produced across phases - (requirements patch, specification patch, implementation patch), - each fully traceable. Audit phases produce investigation-report - artifacts with PASS/REVISE/RESTART verdicts that gate progression. + Multiple artifacts produced across phases: requirements-patch, + spec-patch, and implementation-patch (each using structured-patch + format), plus investigation-report artifacts from adversarial + audits with PASS/REVISE/RESTART verdicts that gate progression. --- # Task: Incremental Development Workflow diff --git a/templates/generate-implementation-changes.md b/templates/generate-implementation-changes.md index bce4ce4..ce70bf5 100644 --- a/templates/generate-implementation-changes.md +++ b/templates/generate-implementation-changes.md @@ -24,12 +24,12 @@ params: verification_artifacts: "Existing tests, simulations, inspection procedures, or other verification artifacts" context: "Additional context — build system, toolchain, domain conventions, coding standards" input_contract: - type: structured-patch + type: spec-patch description: > A structured specification patch with design and validation changes, each tracing to a requirement change. output_contract: - type: structured-patch + type: implementation-patch description: > A structured patch covering implementation and verification changes, with every change tracing to a specification change from the input diff --git a/templates/generate-spec-changes.md b/templates/generate-spec-changes.md index 832b85a..7d89fc3 100644 --- a/templates/generate-spec-changes.md +++ b/templates/generate-spec-changes.md @@ -22,12 +22,12 @@ params: validation_plan: "Existing validation plan or test specification" context: "Additional context — architecture, constraints, domain conventions" input_contract: - type: structured-patch + type: requirements-patch description: > A structured requirements patch with CHG-IDs, Before/After content, and traceability to user intent. output_contract: - type: structured-patch + type: spec-patch description: > A structured patch covering design and validation changes, with every change tracing to a requirement change from the input patch.