Fix: Operation Manager bugs

[YevheniiaLementova]

… command explanation in help

[github-actions]

Rosetta Triage Review

Summary: Fixes misleading help documentation for the plan upsert CLI command — --kind and --phase_id were incorrectly documented as JSON patch body fields rather than CLI flags, causing them to be silently dropped by the RFC 7396 upsert merge mechanism. Updates TypeScript help content, three r3 bootstrap instruction files, and requirements spec (FR-CLI-0006) consistently.

Findings:

• help-content.ts: Fix is correct and comprehensive — usage string, arg keys (kind→--kind, phase_id→--phase_id), conditional_requirements text, and examples all updated consistently. Old example embedded "kind":"phase" inside the JSON string, which the merge mechanism silently strips.
• instructions/r3/core/rules (3 files): bootstrap.md, local-files-mode.md, and plugin-files-mode.md updated identically with correct plan upsert ... --kind [phase|step] syntax. Consistent and well-placed.
• docs/requirements/rosettify/CLI.md: FR-CLI-0006 is well-structured — includes title, statement, rationale, source, ticketId (CTORNDGAIN-1333), priority, status, verification method, and acceptance criteria.
• PR body is minimal (… command explanation in help) — a brief root-cause explanation would help reviewers understand the silent-drop failure mode.

Suggestions:

• Expand the PR body to describe the root cause: kind/phase_id embedded in the JSON patch body are silently ignored by the RFC 7396 merge, so AI agents using the old help would produce a no-op upsert with no error signal.
• Verify that existing vitest coverage includes assertions on the upsert command's help content (args keys, examples) to catch future regressions in help accuracy.

Automated triage by Rosetta agent

[github-actions]

📋 Prompt Quality Validation Report

✅ Validation Passed

Summary by File

File	🔴 Critical	🟠 Very High	🟡 High	🔵 Medium	⚪ Low	Status
instructions/r3/core/rules/bootstrap.md	0	0	0	0	0	✅ Pass
instructions/r3/core/rules/local-files-mode.md	0	0	0	0	0	✅ Pass
instructions/r3/core/rules/plugin-files-mode.md	0	0	0	0	0	✅ Pass

---

📄 instructions/r3/core/rules/bootstrap.md

✅ No Issues Found

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	4	⬆️ Slightly better
Precision & Explicitness	5	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better
Example Grounding	5	⬆️ Slightly better

---

📄 instructions/r3/core/rules/local-files-mode.md

✅ No Issues Found

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	4	⬆️ Slightly better
Precision & Explicitness	5	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better
Example Grounding	5	⬆️ Slightly better

---

📄 instructions/r3/core/rules/plugin-files-mode.md

✅ No Issues Found

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	4	⬆️ Slightly better
Precision & Explicitness	5	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better
Example Grounding	5	⬆️ Slightly better

---

[github-actions]

📋 Prompt Quality Validation Report

✅ Validation Passed

Summary by File

File	🔴 Critical	🟠 Very High	🟡 High	🔵 Medium	⚪ Low	Status
instructions/r3/core/rules/bootstrap.md	0	0	0	1	0	⚠️ Warning
instructions/r3/core/rules/local-files-mode.md	0	0	0	1	0	⚠️ Warning
instructions/r3/core/rules/plugin-files-mode.md	0	0	0	1	0	⚠️ Warning

---

📄 instructions/r3/core/rules/bootstrap.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Precision & Explicitness	Problem: The added line tells the orchestrator to use plan upsert 'for adding or patching any phase/step with custom content'. The phrase 'adding ... any phase' overlaps with the very next line, where upsert-with-template is the command that injects the standard subagent prep steps when a phase is delegated. The plan help source of truth (rosettify/src/commands/plan/help-content.ts) states plain upsert should never be used to add a new phase. Reason: If an orchestrator adds a delegated phase via plain upsert, the standard subagent prep steps are not injected, so the subagent can start without its bootstrap and become less reliable. Solution: Narrow the upsert wording so plain upsert covers patching existing phases/steps and adding individual steps, and reserve adding new (delegated) phases for upsert-with-template. For example: 'for patching existing phases/steps or adding custom steps'.

📊 Gates Comparison

Gate	Score	Comparison
Workflow Completeness	4	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better

---

📄 instructions/r3/core/rules/local-files-mode.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Precision & Explicitness	Problem: Same as bootstrap.md: the added plan upsert line directs the orchestrator to use it 'for adding or patching any phase/step with custom content', which overlaps with the adjacent upsert-with-template line that injects subagent prep steps for delegated phases. The plan help source of truth says plain upsert should never add a new phase. Reason: Adding a delegated phase via plain upsert skips the standard subagent prep-step injection and can reduce subagent reliability. Solution: Narrow the upsert wording to patching existing phases/steps and adding individual steps; keep adding new delegated phases under upsert-with-template.

📊 Gates Comparison

Gate	Score	Comparison
Workflow Completeness	4	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better

---

📄 instructions/r3/core/rules/plugin-files-mode.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Precision & Explicitness	Problem: Same as bootstrap.md: the added plan upsert line directs the orchestrator to use it 'for adding or patching any phase/step with custom content', which overlaps with the adjacent upsert-with-template line that injects subagent prep steps for delegated phases. The plan help source of truth says plain upsert should never add a new phase. Reason: Adding a delegated phase via plain upsert skips the standard subagent prep-step injection and can reduce subagent reliability. Solution: Narrow the upsert wording to patching existing phases/steps and adding individual steps; keep adding new delegated phases under upsert-with-template.

📊 Gates Comparison

Gate	Score	Comparison
Workflow Completeness	4	⬆️ Slightly better
Reference Integrity	5	⬆️ Slightly better

---

[github-actions]

📋 Prompt Quality Validation Report

✅ Validation Passed

Summary by File

File	🔴 Critical	🟠 Very High	🟡 High	🔵 Medium	⚪ Low	Status
instructions/r3/core/rules/bootstrap.md	0	0	0	3	0	⚠️ Warning
instructions/r3/core/rules/local-files-mode.md	0	0	0	3	0	⚠️ Warning
instructions/r3/core/rules/plugin-files-mode.md	0	0	0	3	0	⚠️ Warning

---

📄 instructions/r3/core/rules/bootstrap.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Example Grounding	Problem: The command list now requires a <phase-steps-json-string> on create-with-template and upsert-with-template and adds the new plan upsert ... '<patch-json-string>' command, but the always-in-context bootstrap gives no inline example or shape for these JSON arguments anywhere, and the Phase 0 Step 1 example uses an opaque "<PHASE_STEPS_JSON_STRING>" placeholder. The JSON shape lives only in the on-demand help plan output, yet create-with-template is the FIRST mandatory OPERATION_MANAGER call and may fire before any help plan round-trip. Reason: Without an inline cue at Phase 0 Step 1, an agent may pass the literal placeholder (invalid JSON, command rejected) or be forced into an extra help plan round-trip before its first plan-creation call. Recoverable, but it adds first-call friction at the most fragile session moment. Solution: Add a minimal inline cue at the point of first use, e.g. note the phase-steps arg is a steps array shaped like [{id,name,prompt}], that empty [] is allowed, or add an explicit 'see help plan for the JSON shape' pointer. Keep it to one short line to preserve progressive disclosure.
🔵 Medium	Precision & Explicitness	Problem: The new <phase-steps-json-string> argument is shown with inconsistent shell-quoting cues across sources. In the command list it is unquoted while its sibling args are single-quoted: ... for-orchestrator '<plan-name>' '<plan-description>' <phase-steps-json-string>. The Phase 0 Step 1 example then double-quotes it: "<PHASE_STEPS_JSON_STRING>". The canonical CLI examples single-quote it: '[{...}]'. A phase-steps JSON array contains spaces, braces, and inner double quotes, so on the npx/shell fallback path it must be single-quoted; the double-quoted example is actively misleading. Reason: On the OPERATION_MANAGER shell-fallback path (npx rosettify), copying the unquoted signature or the double-quoted example for a JSON payload that contains inner double quotes produces a broken command on the agent's first plan-creation call. The primary MCP path is unaffected, so impact is medium. Solution: Show the JSON arg consistently single-quoted in both the command list and the Phase 0 examples, e.g. ... '<plan-description>' '<phase-steps-json-string>' and "<USER_REQUEST_SUMMARY>" '<PHASE_STEPS_JSON_STRING>', matching the existing '<plan-description>' convention and the CLI's '[...]' form.
🔵 Medium	Decision Branching	Problem: The diff adds a new `plan upsert <plan_file> <target_id> '' [--kind phase

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	3	⬇️ Slightly worse
Reference Integrity	4	✅ Much better

---

📄 instructions/r3/core/rules/local-files-mode.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Example Grounding	Problem: create-with-template and upsert-with-template now require a <phase-steps-json-string> and a new plan upsert ... '<patch-json-string>' command is added, but no inline example or shape for these JSON arguments appears in this always-in-context rule; Phase 0 Step 1 uses the opaque "<PHASE_STEPS_JSON_STRING>" placeholder. The shape lives only in on-demand help plan, yet create-with-template is the first mandatory call. Reason: Without an inline cue at Phase 0 Step 1, an agent may pass the literal placeholder (invalid JSON) or need an extra help plan round-trip before its first plan-creation call. Solution: Add a minimal inline cue (phase-steps is a steps array like [{id,name,prompt}], empty [] allowed) or an explicit 'see help plan for the JSON shape' pointer; keep it to one line.
🔵 Medium	Precision & Explicitness	Problem: Inconsistent shell-quoting cue for the new <phase-steps-json-string> arg: unquoted in the command list (siblings are single-quoted), double-quoted as "<PHASE_STEPS_JSON_STRING>" in the Phase 0 Step 1 example, but single-quoted '[{...}]' in the canonical CLI. A phase-steps JSON array contains inner double quotes, so it must be single-quoted on the shell-fallback path. Reason: On the npx/shell fallback path, the unquoted signature or double-quoted example for a JSON payload with inner double quotes produces a broken first plan-creation command. The MCP path is unaffected, so impact is medium. Solution: Show the JSON arg consistently single-quoted in both the command list and the Phase 0 example, matching the existing '<plan-description>' convention and the CLI's '[...]' form.
🔵 Medium	Decision Branching	Problem: Same command-block edit as the other bootstrap files: the new `plan upsert ... '' [--kind phase

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	3	⬇️ Slightly worse
Reference Integrity	4	✅ Much better
Structural Coherence	5	⬆️ Slightly better
Bloat Control	4	⬆️ Slightly better

---

📄 instructions/r3/core/rules/plugin-files-mode.md

⚠️ Issues Found

Severity	Gate	Details
🔵 Medium	Example Grounding	Problem: create-with-template and upsert-with-template now require a <phase-steps-json-string> and a new plan upsert ... '<patch-json-string>' command is added, but no inline example or shape for these JSON arguments appears in this always-in-context rule; Phase 0 Step 1 uses the opaque "<PHASE_STEPS_JSON_STRING>" placeholder. The shape lives only in on-demand help plan, yet create-with-template is the first mandatory call. Reason: Without an inline cue at Phase 0 Step 1, an agent may pass the literal placeholder (invalid JSON) or need an extra help plan round-trip before its first plan-creation call. Solution: Add a minimal inline cue (phase-steps is a steps array like [{id,name,prompt}], empty [] allowed) or an explicit 'see help plan for the JSON shape' pointer; keep it to one line.
🔵 Medium	Precision & Explicitness	Problem: Inconsistent shell-quoting cue for the new <phase-steps-json-string> arg: unquoted in the command list (siblings are single-quoted), double-quoted as "<PHASE_STEPS_JSON_STRING>" in the Phase 0 Step 1 example, but single-quoted '[{...}]' in the canonical CLI. A phase-steps JSON array contains inner double quotes, so it must be single-quoted on the shell-fallback path. Reason: On the npx/shell fallback path, the unquoted signature or double-quoted example for a JSON payload with inner double quotes produces a broken first plan-creation command. The MCP path is unaffected, so impact is medium. Solution: Show the JSON arg consistently single-quoted in both the command list and the Phase 0 example, matching the existing '<plan-description>' convention and the CLI's '[...]' form.
🔵 Medium	Decision Branching	Problem: Same command-block edit as the other bootstrap files: the new `plan upsert ... '' [--kind phase

📊 Gates Comparison

Gate	Score	Comparison
Input Contract	4	⬆️ Slightly better
Decision Branching	3	⬇️ Slightly worse
Reference Integrity	4	✅ Much better
Structural Coherence	5	⬆️ Slightly better
Bloat Control	4	⬆️ Slightly better

---