Add posting guardrails to mach6-issue skill

[m-aebrer]

Closes #438

Hardens mach6-issue CREATE mode so issue content and the explicit target repository require approval before posting.

Implementation plan posted as a comment below.

[m-aebrer]

Implementation Plan

Problem analysis

CREATE mode currently puts a soft “present the draft” sentence immediately before the posting command. It does not force a separate user decision, does not define which response authorizes posting, and lets gh issue create rely on ambient repository context. This allows an imperative opening request to be mistaken for posting approval and creates a fork/default-repository hazard.

The existing ask_user tool already supplies the required interaction: a Markdown-formatted question, three selectable options, free text, and a pause for a distinct user response. The fix is therefore confined to the built-in skill instructions; no runtime code, generated artifact, or broader product documentation needs to change.

Deliverables

1. Harden CREATE mode in packages/coding-agent/skills/mach6-issue/SKILL.md so an initial request to “create,” “post,” or “open” an issue authorizes drafting only and can never authorize posting in the same turn.
2. Require the parent model to resolve and display the exact owner/repo, full Markdown title, and full Markdown draft body in an ask_user approval wizard before running any posting command.
3. Define the wizard with the required choices:
   • Approve — the only response that authorizes posting.
   • Deny/Discuss — do not post; discuss or revise the draft.
   • Detailed Explanation with minimal jargon of each acceptance criteria — do not post; explain each criterion, then return to the approval gate.
4. State that any revision to the approved title, body, or destination invalidates approval and requires the complete approval gate again.
5. Update the creation command example to pass the confirmed destination explicitly with --repo <owner/repo>, while preserving the existing unique temp-file and --body-file safeguards.

Acceptance criteria

• CREATE mode explicitly forbids posting during the initial imperative request and requires a distinct ask_user response after the draft is shown.
• The approval question visibly contains the exact target owner/repo, complete title, and complete Markdown body.
• Only the explicit Approve selection permits gh issue create; discussion, explanation, free text, cancellation, or an unanswered/skipped prompt never posts.
• The explanation path uses minimal jargon for every acceptance criterion and then requires approval again.
• Draft or destination changes require fresh approval.
• The posting example uses the same confirmed target via --repo <owner/repo> and retains the existing safe gh invocation pattern.

Files to modify

• packages/coding-agent/skills/mach6-issue/SKILL.md — clarify CREATE-mode semantics, add the hard ask_user approval gate and outcome handling, and make repository targeting explicit.

No README or dedicated docs change is needed: the public mach6 documentation only states that CREATE mode drafts structured issues and does not duplicate the posting workflow or contradict the new guardrail.

Testing and verification

Per the requested small documentation-only scope, add no regression test. Verify the change by:

• reviewing the rendered skill Markdown to confirm the full gate, exact three options, non-approval paths, and re-approval rule are unambiguous;
• confirming the sample ask_user shape stays within the existing 2–4 option schema and permits discussion through free text;
• running the existing built-in skill test file to ensure the edited skill remains discoverable and satisfies current skill-content contracts;
• checking the final diff to ensure only packages/coding-agent/skills/mach6-issue/SKILL.md changed after the empty planning commit.

The skill is loaded directly from Markdown at runtime, so no generated files or compile step are required for this change.

Risks and open questions

• The wording must contain a hard stop, not merely stronger advisory prose, or the original same-turn failure mode remains possible.
• The destination displayed for approval and the value passed to --repo must be identical; repository inference alone is insufficient.
• Explanation, discussion, free-text, skipped, or cancelled outcomes must not fall through to posting.
• The approval prompt may be long because it must show the complete body, but truncating it would violate the requirement.
• There are no unresolved product decisions; the issue and maintainer comment define the required interaction.

---

Plan created by mach6

[github-actions]

Vitest coverage

Metric	Covered	Total	Coverage
Statements	39006	55214	70.64%
Branches	20800	34437	60.4%
Functions	8247	11539	71.47%
Lines	28181	39691	71%

View full coverage run

[m-aebrer]

Progress Update

Implemented the mach6-issue CREATE-mode posting guardrails:

• imperative opening requests now authorize drafting only, never same-turn posting;
• ask_user must show the exact target repository, complete title, and complete Markdown body;
• only the explicit Approve option permits posting, while discussion and explanation paths return to the approval gate;
• edits invalidate prior approval; and
• gh issue create now uses the confirmed target through explicit --repo.

Verification passed: the focused built-in skill suite (43 tests), git diff --check, and the commit hook's full test run (5,543 passed, 711 skipped).

Commit: 80d4164

---

Progress tracked by mach6

[m-aebrer]

Code Review

Critical

None.

Important

1. [Manual user QA — must resolve] Preserve the original request as an exact quote. CREATE mode does not require the issue body to retain the user's original input verbatim. Add an exact quotation of the original request so the issue preserves the source requirement rather than only the agent's interpretation.

2. [Manual user QA — must resolve] Confirm scope before adding unrequested acceptance criteria. CREATE mode currently lets the agent expand acceptance criteria beyond what the user explicitly requested. Before adding such criteria, require confirmation that they are valid scope; otherwise keep the issue small and focused on the request.

3. Missing regression contract for the posting gate. packages/coding-agent/test/skills.test.ts loads built-in skill Markdown and protects other instruction contracts, but this PR adds no assertion for its safety-critical CREATE-mode state machine. Add focused checks for draft-only initial requests, the exact approval options and displayed fields, non-approval outcomes, approval invalidation, and explicit --repo usage. Confidence: 98.

Suggestions

4. Labels can be posted without appearing in the approval gate. Step 2 drafts suggested labels and Step 3 may pass --label, but the approval wizard requires only repository, title, and body. Include proposed labels in approval or omit them unless separately confirmed. Confidence: 85.

5. Repository discovery is underspecified. The skill requires an exact owner/repo and forbids relying on ambient context when posting, but gives no positive discovery method. Consider specifying a non-interactive source such as gh repo view --json nameWithOwner, followed by user confirmation. Confidence: 82.

Strengths

• The initial imperative is explicitly draft-only and cannot authorize same-turn posting.
• Only Approve permits posting; every non-approval path is prevented from falling through.
• Complete title, body, and destination are shown, edits invalidate approval, and --repo binds execution to the approved target.
• The implementation satisfies the previously approved plan and preserves safe temp-file and --body-file usage.
• The safety-critical repetition is clear and intentional rather than needless duplication.

Agents run: code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier; plus manual user QA feedback

---

Reviewed by mach6

[m-aebrer]

Review Assessment

Review comment

Classifications

Finding	Classification	Reasoning
1. Preserve the original request as an exact quote	genuine	Factual: CREATE mode uses the request as a starting point but never requires retaining the original input verbatim. Scope: The subsequent human scope update explicitly requires an exact quotation and marks it must-resolve.
2. Confirm scope before adding unrequested acceptance criteria	genuine	Factual: The skill unconditionally generates acceptance criteria without distinguishing requested criteria from agent-added scope or requiring prior confirmation. Whole-draft posting approval does not satisfy this earlier scope check. Scope: The human explicitly added this behavior and marked it must-resolve.
3. Missing regression contract for the posting gate	genuine	Factual: Existing skill tests protect availability and Explore-agent wording but do not assert the new approval state machine. Scope: This PR introduces testable, safety-critical write guardrails whose regression could permit unauthorized or misdirected posting.
4. Labels can be posted without appearing in the approval gate	deferred	Factual: The skill suggests labels and may pass --label, while approval requires only repository, title, and body. Scope: Current approved requirements do not require label confirmation; track separately rather than expanding this PR.
5. Repository discovery is underspecified	false-positive	Factual: No discovery command is mandated, but the skill requires an exact destination, human confirmation, and binding through --repo; lack of one prescribed lookup method is not itself a defect. Scope: Requirements govern confirmation and execution, not candidate discovery, and the intended target may differ from the current checkout.

Action Plan

1. Require the issue body to contain a clearly identified, exact quotation of the original user request/input.
2. Separate explicitly requested acceptance criteria from proposed additions and obtain user confirmation before inserting any unrequested criterion.
3. Add focused skill-contract tests for both new scope rules and the posting gate's draft-only behavior, approval fields/options, non-approval handling, invalidation, and explicit --repo binding.

Deferred follow-up: Decide separately whether labels must appear in the approval gate or be omitted unless independently confirmed.

---

Assessment by mach6

[m-aebrer]

Review Assessment — Scope Update

Supersedes the classification and action plan in the prior assessment.

The user explicitly confirmed that proposed labels must also be presented in the approval gate. Finding 4 is therefore genuine and must-resolve, not deferred.

Updated Classifications

Finding	Classification	Reasoning
1. Preserve the original request as an exact quote	genuine	Factual: The original input is not retained verbatim. Scope: Explicitly required by the human scope update.
2. Confirm scope before adding unrequested acceptance criteria	genuine	Factual: Agent-added criteria need no prior scope confirmation. Scope: Explicitly required by the human scope update.
3. Missing regression contract for the posting gate	genuine	Factual: Existing tests do not protect the new state machine. Scope: The new safety-critical write guardrails require regression protection.
4. Labels can be posted without appearing in the approval gate	genuine	Factual: Labels may be passed to gh issue create but are absent from the required approval display. Scope: The user explicitly requires proposed labels to be presented for approval in this PR.
5. Repository discovery is underspecified	false-positive	Factual: Exact destination confirmation and --repo binding are already required; no single discovery command is universally correct. Scope: Candidate discovery method is not required.

Updated Action Plan

1. Require a clearly identified exact quotation of the original user request/input in the issue body.
2. Require confirmation before adding acceptance criteria not explicitly requested by the user.
3. Present all proposed labels in the approval gate and invalidate approval if labels change.
4. Add focused skill-contract tests covering these rules and the complete posting gate.

---

Assessment by mach6

[m-aebrer]

Progress Update

Resolved review findings 1–4:

• CREATE-mode issue bodies now preserve the original user request verbatim in a clearly identified block quote;
• acceptance criteria not explicitly requested require separate user scope confirmation before inclusion;
• proposed labels are displayed in the approval gate, and label changes invalidate approval;
• focused built-in skill contract tests protect the full posting and scope guardrails; and
• updated two stale Google live-test model references exposed by the current generated model registry during the commit checks.

Verification passed: focused skill tests (44 passed), Biome, full build, workspace-link verification, git diff --check, and the commit hook's full suite (5,544 passed, 711 skipped).

Commit: bafcb87

---

Progress tracked by mach6

[m-aebrer]

Code Review

Critical

None.

Important

1. Approval state-machine test does not enforce the required ask_user gate. The new test checks selected phrases independently, but does not assert that the final approval question is made through ask_user, that execution stops for a distinct response, or that Approve is the only state allowed to reach gh issue create. A regression to a generic question could retain all asserted phrases while removing the issue's central safety mechanism. Confidence: 99.

Suggestions

2. The “exactly three options” requirement is not protected. The test asserts that all three required option strings occur, but does not verify that the approval question offers exactly those three choices. A future additional authorization-like option could pass the test while violating the approved interaction contract. Confidence: 96.

Strengths

• The skill fully implements the linked issue, plan, and subsequent human-approved scope updates: draft-only initial requests, verbatim source preservation, separate confirmation of added criteria, complete approval display, label confirmation, invalidation after edits, and explicit --repo binding.
• Error paths are explicit: skipped, unanswered, cancelled, free-text, discussion, and explanation outcomes cannot fall through to posting.
• The existing contract test covers most newly required guardrail wording, and the Gemini live-test updates preserve prior behavior with current model identifiers.
• No simplification opportunities or runtime error-handling defects were identified.

Agents run: code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier

---

Reviewed by mach6

[m-aebrer]

Review Assessment

Review comment

The user's subsequent explicit clarification is authoritative and supersedes contrary inferences from the plan or prior automated review: the approval wizard must include at least the three named options but may include more, and additional regression assertions are not required for this text-only skill document.

Classifications

Finding	Classification	Reasoning
1. Approval state-machine test does not enforce the complete ask_user gate	deferred	Factual: The current string assertions do not independently pin every sentence of the approval state machine, so the narrow test-coverage observation is accurate. Scope: The user explicitly clarified that further regression tests for this text-only document are unnecessary and overkill. The implemented skill text itself contains the required gate, so no change is required for this PR. No follow-up issue is requested.
2. The test does not enforce exactly three options	false-positive	Factual: The finding assumes an “exactly three” requirement that the user explicitly rejected. The intended behavior is to require at least the three named choices while permitting additional choices. Scope: Enforcing exactly three would contradict the authoritative human clarification rather than complete the requested scope.

Action Plan

No genuine issues. This PR requires no review-driven changes.

---

Assessment by mach6