fix(instructions): repair #357, #355, #354, #356 - contract defects across all plugin targets (ai-generated, includes-ai-code)

instructions/r3/core/skills/research/README.md

@@ -17,15 +17,15 @@ Single flat SKILL.md, no `assets/` or `references/`. Flow: `<role>` (senior rese
 - "MUST NOT update CONTEXT.md, ARCHITECTURE.md, IMPLEMENTATION.md, and create any other documents EXCEPT those mentioned explicitly" — research output is deliberately walled off from the project's core docs.
 - "Follow tree-of-thoughts pattern and analyze at least 3 options" — a single correct-looking option still fails the skill's contract.
 - "Fall back to anecdotal references, but call this out EXPLICITLY!" — anecdote is permitted only with a loud disclaimer, never silently blended with reputable sources.
-- "MUST use DeepWiki and Context7" — a named-tool mandate written into the generated research prompt, not a suggestion.
+- "MUST use DeepWiki and Context7 when available" — a named-tool mandate written into the generated research prompt, conditional on the tools being installed.
 - "MUST think about and align consequences and consequences of consequences to prevent oversight" — second-order-effects analysis is required of the crafted prompt, not optional depth.
 
 ## Invariants — do not change
 - Frontmatter `name: research` equals the folder name and the registry entry at `docs/definitions/skills.md:4` — renaming either breaks registration.
 - `description` is one dense sentence under the ~25-token budget ("To run systematic deep research via meta-prompting — grounded references, incremental tracking, self-validation.").
 - XML section names `<research>`, `<role>`, `<when_to_use_skill>`, `<core_concepts>`, `<process>` are structural anchors that other tooling may parse.
 - Two distinct, similarly-named state files: `research-state.md` (this skill, `agents/researcher.md`) is the skill-level tracker; `research-flow-state.md` (`workflows/research-flow.md`) is the workflow-level tracker — do not rename either without checking both call sites, and do not assume they are the same file.
-- Inbound couplings: `agents/researcher.md:33,40` ("Apply `research` skill." / "USE SKILL research") — the subagent contractually required to run this skill; `workflows/research-flow.md:51` ("Required skills: `research`", phase 3 `execute_research`) — the sanctioned entry point; `skills/orchestration/assets/o-team-manager.md:9` ("USE SKILL `research` for external knowledge if needed") — an ad hoc invocation path outside `research-flow`; `workflows/self-help-flow.md:53` — documents direct `/research` invocation as bypassing the structured workflow.
+- Inbound couplings: `agents/researcher.md:33,40` ("Apply `research` skill." / "USE SKILL research") — the subagent contractually required to run this skill; `workflows/research-flow.md:50` ("Required skills: `research`", phase 3 `execute_research`) — the sanctioned entry point; `skills/orchestration/assets/o-team-manager.md:9` ("USE SKILL `research` for external knowledge if needed") — an ad hoc invocation path outside `research-flow`; `workflows/self-help-flow.md:53` — documents direct `/research` invocation as bypassing the structured workflow.
 
 ## Editing guide
 Safe to edit: wording inside the "Research rules" / "Enforcement rules for the generated research prompt" bullet lists, as long as the meta-prompting split survives (this skill governs how research is carried out; the crafted prompt separately carries its own 5 enforcement rules). Handle with care: frontmatter (`name`, `description`), the two state-file names, and the `docs/<feature>-research.md` / `research-prompt.md` output paths, since `research-flow.md` and `researcher.md` branch on these exact strings. Referenced by: `agents/researcher.md`, `workflows/research-flow.md`, `skills/orchestration/assets/o-team-manager.md`, and `workflows/self-help-flow.md` (as a cautionary example).

instructions/r3/core/skills/research/SKILL.md

@@ -50,7 +50,7 @@ Research rules:
 Enforcement rules for the generated research prompt:
 
 1. MUST use todo tasks
-2. MUST use DeepWiki and Context7
+2. MUST use DeepWiki and Context7 when available
 3. MUST create and update state md file after each task
 4. MUST output result file section by section as soon as each section becomes available
 5. MUST think about and align consequences and consequences of consequences to prevent oversight (example: doing X leads to Y, which affects Z, thus it should be done ABC way)

instructions/r3/core/workflows/coding-agents-prompting-flow.md

@@ -26,7 +26,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 5. Orchestrator and subagents MUST USE SKILL `coding-agents-prompt-authoring`.
 6. No rush, take your time, MUST FOLLOW WORKFLOW ENTIRELY, no skipping.
 7. This workflow MUST be used with Fable, Opus, GPT-6.1-Sol+ class models => IF NOT - DEMAND USER TO SWITCH MODEL.
-8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state` file.
+8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state.md` file.
 
 </prerequisites>
 
@@ -88,7 +88,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 <validate step="7" subagent="prompt-engineer" role="Quality validator" subagent_required_model="claude-opus-5-5, gpt-6.1-sol-high, gemini-4-argon-high, gemini-3.8-flash-high">
 
 1. Validate final artifacts against intent, contracts, failure modes, and traceability.
-2. Input: `Prompt Brief` + `Blueprint` + `Candidate Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
+2. Input: `Prompt Brief` + `Blueprint` + `Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
 3. Update `coding-agents-prompting-flow-state.md` and mark complete.
 4. HITL final approval required before persistence; small tasks may stay in-memory and be returned in message.
 

instructions/r3/core/workflows/modernization-flow-analysis.md

@@ -12,7 +12,7 @@ baseSchema: docs/schemas/phase.md
 ## Phase Flow
 
 **Phase 2: Old Code Analysis**
-1. Complete Phase 1 first
+1. Complete Phase 1 first, unless on the reduced route recorded in the state file
 2. Process each project separately
 3. Analyze code and tests
 4. Create original-code-specs files
@@ -26,7 +26,7 @@ baseSchema: docs/schemas/phase.md
 
 ## Context
 
-**PREREQUISITES:** Complete Phase 1 (all reference code specs created)
+**PREREQUISITES:** Complete Phase 1 (all reference code specs created), unless on the reduced route recorded in the state file
 
 **OBJECTIVES:**
 - Create complete, factual specification of existing code

instructions/r3/core/workflows/modernization-flow-implement.md

@@ -12,7 +12,7 @@ baseSchema: docs/schemas/phase.md
 ## Context
 
 **PREREQUISITES:** 
-- Complete Phase 7 (final cross-project review)
+- Complete Phase 7 (final cross-project review), unless on the reduced route recorded in the state file
 - **EXPLICIT HUMAN APPROVAL** of all target specs
 
 ## Requirements

instructions/r3/core/workflows/modernization-flow-mapping.md

@@ -12,7 +12,7 @@ baseSchema: docs/schemas/phase.md
 ## Phase Flow
 
 **Phase 6: Implementation Mapping**
-1. Complete Phase 5 first
+1. Complete Phase 5 first, unless on the reduced route recorded in the state file
 2. Define technical approaches
 3. Compare multiple alternatives
 4. Map source to target
@@ -24,7 +24,7 @@ baseSchema: docs/schemas/phase.md
 
 ## Context
 
-**PREREQUISITES:** Complete Phase 5 (cross-project analysis)
+**PREREQUISITES:** Complete Phase 5 (cross-project analysis), unless on the reduced route recorded in the state file
 
 **OBJECTIVES:**
 - Define technical approaches for modernization
@@ -53,7 +53,7 @@ baseSchema: docs/schemas/phase.md
 ## Requirements
 
 - **MUST** process each project separately
-- **MUST** re-read `docs/cross-project-analysis.md`
+- **MUST** re-read `docs/cross-project-analysis.md` if it exists
 - **MUST** re-read matching `docs/original-code-specs-<lib/project>.md`
 - **MUST** re-read both incoming/outgoing dependency if those exist `docs/target-code-specs-<lib/project>.md`
 - **MUST** create `docs/target-code-specs-<lib/project>.md` for each project

instructions/r3/core/workflows/modernization-flow.md

@@ -30,7 +30,7 @@ This modernization process is designed to systematically analyze, specify, and i
 
 - If user did not specify any preferences perform all steps except optional.
 - User CAN customize and ask only for specific steps OR steps could have been done already OR towards specific goal OR for specific case, in this case LISTEN and ADOPT to the user.
-- Modernization scope could be small or could be done in place (example: upgrade Java 8 to 17 or 17 to 21), in this case only use `Phase 2` and `Phase 6`, unless you discover dependencies and project becomes bigger.
+- Modernization scope could be small or could be done in place (example: upgrade Java 8 to 17 or 17 to 21), in this case only use `Phase 2` and `Phase 6`, skip the other phases and their prerequisites, record this in the state file, unless you discover dependencies and project becomes bigger.
 - If there is no need to rewrite code (example: upgrade .NET 6 to .NET 8), then take original and target code specs LIGHTLY, only document WHAT IS NECESSARY TO CHANGE (example: new way to use app builder).
 
 ## Modernization Flow - Phase Overview

plugins/core-antigravity-light/skills/coding-agents-prompting-flow/SKILL.md

@@ -24,7 +24,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 5. Orchestrator and subagents MUST USE SKILL `coding-agents-prompt-authoring`.
 6. No rush, take your time, MUST FOLLOW WORKFLOW ENTIRELY, no skipping.
 7. This workflow MUST be used with Fable, Opus, GPT-6.1-Sol+ class models => IF NOT - DEMAND USER TO SWITCH MODEL.
-8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state` file.
+8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state.md` file.
 
 </prerequisites>
 
@@ -86,7 +86,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 <validate step="7" subagent="prompt-engineer" role="Quality validator" subagent_required_model="inherit">
 
 1. Validate final artifacts against intent, contracts, failure modes, and traceability.
-2. Input: `Prompt Brief` + `Blueprint` + `Candidate Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
+2. Input: `Prompt Brief` + `Blueprint` + `Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
 3. Update `coding-agents-prompting-flow-state.md` and mark complete.
 4. HITL final approval required before persistence; small tasks may stay in-memory and be returned in message.
 

plugins/core-antigravity-light/skills/modernization-flow/SKILL.md

@@ -28,7 +28,7 @@ This modernization process is designed to systematically analyze, specify, and i
 
 - If user did not specify any preferences perform all steps except optional.
 - User CAN customize and ask only for specific steps OR steps could have been done already OR towards specific goal OR for specific case, in this case LISTEN and ADOPT to the user.
-- Modernization scope could be small or could be done in place (example: upgrade Java 8 to 17 or 17 to 21), in this case only use `Phase 2` and `Phase 6`, unless you discover dependencies and project becomes bigger.
+- Modernization scope could be small or could be done in place (example: upgrade Java 8 to 17 or 17 to 21), in this case only use `Phase 2` and `Phase 6`, skip the other phases and their prerequisites, record this in the state file, unless you discover dependencies and project becomes bigger.
 - If there is no need to rewrite code (example: upgrade .NET 6 to .NET 8), then take original and target code specs LIGHTLY, only document WHAT IS NECESSARY TO CHANGE (example: new way to use app builder).
 
 ## Modernization Flow - Phase Overview

plugins/core-antigravity-light/skills/modernization-flow/phases/modernization-flow-analysis.md

@@ -3,7 +3,7 @@
 ## Phase Flow
 
 **Phase 2: Old Code Analysis**
-1. Complete Phase 1 first
+1. Complete Phase 1 first, unless on the reduced route recorded in the state file
 2. Process each project separately
 3. Analyze code and tests
 4. Create original-code-specs files
@@ -17,7 +17,7 @@
 
 ## Context
 
-**PREREQUISITES:** Complete Phase 1 (all reference code specs created)
+**PREREQUISITES:** Complete Phase 1 (all reference code specs created), unless on the reduced route recorded in the state file
 
 **OBJECTIVES:**
 - Create complete, factual specification of existing code

plugins/core-antigravity-light/skills/modernization-flow/phases/modernization-flow-implement.md

@@ -3,7 +3,7 @@
 ## Context
 
 **PREREQUISITES:** 
-- Complete Phase 7 (final cross-project review)
+- Complete Phase 7 (final cross-project review), unless on the reduced route recorded in the state file
 - **EXPLICIT HUMAN APPROVAL** of all target specs
 
 ## Requirements

plugins/core-antigravity-light/skills/modernization-flow/phases/modernization-flow-mapping.md

@@ -3,7 +3,7 @@
 ## Phase Flow
 
 **Phase 6: Implementation Mapping**
-1. Complete Phase 5 first
+1. Complete Phase 5 first, unless on the reduced route recorded in the state file
 2. Define technical approaches
 3. Compare multiple alternatives
 4. Map source to target
@@ -15,7 +15,7 @@
 
 ## Context
 
-**PREREQUISITES:** Complete Phase 5 (cross-project analysis)
+**PREREQUISITES:** Complete Phase 5 (cross-project analysis), unless on the reduced route recorded in the state file
 
 **OBJECTIVES:**
 - Define technical approaches for modernization
@@ -44,7 +44,7 @@
 ## Requirements
 
 - **MUST** process each project separately
-- **MUST** re-read `docs/cross-project-analysis.md`
+- **MUST** re-read `docs/cross-project-analysis.md` if it exists
 - **MUST** re-read matching `docs/original-code-specs-<lib/project>.md`
 - **MUST** re-read both incoming/outgoing dependency if those exist `docs/target-code-specs-<lib/project>.md`
 - **MUST** create `docs/target-code-specs-<lib/project>.md` for each project

plugins/core-antigravity-light/skills/research/README.md

@@ -17,15 +17,15 @@ Single flat SKILL.md, no `assets/` or `references/`. Flow: `<role>` (senior rese
 - "MUST NOT update CONTEXT.md, ARCHITECTURE.md, IMPLEMENTATION.md, and create any other documents EXCEPT those mentioned explicitly" — research output is deliberately walled off from the project's core docs.
 - "Follow tree-of-thoughts pattern and analyze at least 3 options" — a single correct-looking option still fails the skill's contract.
 - "Fall back to anecdotal references, but call this out EXPLICITLY!" — anecdote is permitted only with a loud disclaimer, never silently blended with reputable sources.
-- "MUST use DeepWiki and Context7" — a named-tool mandate written into the generated research prompt, not a suggestion.
+- "MUST use DeepWiki and Context7 when available" — a named-tool mandate written into the generated research prompt, conditional on the tools being installed.
 - "MUST think about and align consequences and consequences of consequences to prevent oversight" — second-order-effects analysis is required of the crafted prompt, not optional depth.
 
 ## Invariants — do not change
 - Frontmatter `name: research` equals the folder name and the registry entry at `docs/definitions/skills.md:4` — renaming either breaks registration.
 - `description` is one dense sentence under the ~25-token budget ("To run systematic deep research via meta-prompting — grounded references, incremental tracking, self-validation.").
 - XML section names `<research>`, `<role>`, `<when_to_use_skill>`, `<core_concepts>`, `<process>` are structural anchors that other tooling may parse.
 - Two distinct, similarly-named state files: `research-state.md` (this skill, `agents/researcher.md`) is the skill-level tracker; `research-flow-state.md` (`skills/research-flow/SKILL.md`) is the workflow-level tracker — do not rename either without checking both call sites, and do not assume they are the same file.
-- Inbound couplings: `agents/researcher.md:33,40` ("Apply `research` skill." / "USE SKILL research") — the subagent contractually required to run this skill; `skills/research-flow/SKILL.md:51` ("Required skills: `research`", phase 3 `execute_research`) — the sanctioned entry point; `skills/orchestration/assets/o-team-manager.md:9` ("USE SKILL `research` for external knowledge if needed") — an ad hoc invocation path outside `research-flow`; `skills/self-help-flow/SKILL.md:53` — documents direct `/research` invocation as bypassing the structured workflow.
+- Inbound couplings: `agents/researcher.md:33,40` ("Apply `research` skill." / "USE SKILL research") — the subagent contractually required to run this skill; `skills/research-flow/SKILL.md:50` ("Required skills: `research`", phase 3 `execute_research`) — the sanctioned entry point; `skills/orchestration/assets/o-team-manager.md:9` ("USE SKILL `research` for external knowledge if needed") — an ad hoc invocation path outside `research-flow`; `skills/self-help-flow/SKILL.md:53` — documents direct `/research` invocation as bypassing the structured workflow.
 
 ## Editing guide
 Safe to edit: wording inside the "Research rules" / "Enforcement rules for the generated research prompt" bullet lists, as long as the meta-prompting split survives (this skill governs how research is carried out; the crafted prompt separately carries its own 5 enforcement rules). Handle with care: frontmatter (`name`, `description`), the two state-file names, and the `docs/<feature>-research.md` / `research-prompt.md` output paths, since `research-flow.md` and `researcher.md` branch on these exact strings. Referenced by: `agents/researcher.md`, `skills/research-flow/SKILL.md`, `skills/orchestration/assets/o-team-manager.md`, and `skills/self-help-flow/SKILL.md` (as a cautionary example).

plugins/core-antigravity-light/skills/research/SKILL.md

@@ -47,7 +47,7 @@ Research rules:
 Enforcement rules for the generated research prompt:
 
 1. MUST use todo tasks
-2. MUST use DeepWiki and Context7
+2. MUST use DeepWiki and Context7 when available
 3. MUST create and update state md file after each task
 4. MUST output result file section by section as soon as each section becomes available
 5. MUST think about and align consequences and consequences of consequences to prevent oversight (example: doing X leads to Y, which affects Z, thus it should be done ABC way)

plugins/core-antigravity/skills/coding-agents-prompting-flow/SKILL.md

@@ -24,7 +24,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 5. Orchestrator and subagents MUST USE SKILL `coding-agents-prompt-authoring`.
 6. No rush, take your time, MUST FOLLOW WORKFLOW ENTIRELY, no skipping.
 7. This workflow MUST be used with Fable, Opus, GPT-6.1-Sol+ class models => IF NOT - DEMAND USER TO SWITCH MODEL.
-8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state` file.
+8. Workflow state MUST be saved to `agents/TEMP/<FEATURE>/coding-agents-prompting-flow-state.md` file.
 
 </prerequisites>
 
@@ -86,7 +86,7 @@ Orchestrates prompt authoring/adaptation via `discover -> extract+intake -> blue
 <validate step="7" subagent="prompt-engineer" role="Quality validator" subagent_required_model="inherit">
 
 1. Validate final artifacts against intent, contracts, failure modes, and traceability.
-2. Input: `Prompt Brief` + `Blueprint` + `Candidate Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
+2. Input: `Prompt Brief` + `Blueprint` + `Prompt Set` + `Simulation Notes`. Output: `Final Prompt Set` + `Validation Pack` (`Checklist Results`, `Tests`, `Failure Modes`, `Traceability`; persistent report optional in FEATURE PLAN folder as validation-report.md).
 3. Update `coding-agents-prompting-flow-state.md` and mark complete.
 4. HITL final approval required before persistence; small tasks may stay in-memory and be returned in message.