@codyswann/lisa 2.176.9 → 2.176.10

package/plugins/src/base/agents/github-agent.md

@@ -51,22 +51,24 @@ Use the `github-verify` skill to check the issue against organizational standard
 
 Resolve build labels from `.lisa.config.json` `github.labels.build.*` (defaults: `status:ready` / `status:in-progress` / env-keyed `status:on-*`); resolve the `blocked` label from the same section (`github.labels.build.blocked`, default `status:blocked`) and the `human_needed` marker label from the same section (`github.labels.build.human_needed`, default `human-needed`).
 
-If `github-verify` returns `FAIL` on any of the above, do NOT continue:
+If `github-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the author:
 
-1. Relabel: remove the `claimed` label, add the `blocked` label **and** the `human_needed` marker label. A pre-flight gate failure bounces the issue back to its author precisely because it needs something **no agent and no automated retry can supply** — credentials, access, a product/scoping decision, or required issue quality only the human can add — so the marker tells a human scanning the board which blocked issues are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
+1. **Best-effort autofill (before blocking).** Run the **draft-then-block procedure** in the `pre-flight-autofill` rule: draft every *authorable* missing section — Technical Approach, Out of Scope, Gherkin acceptance criteria, expected-vs-actual, Repository, Relationship Search (run the git + `gh`/tracker search, don't fabricate it), a Validation Journey **draft** via `github-add-journey`, and a recommended Target Backend Environment — from the issue's own content (title, body, screenshots, design links, repro steps) plus the codebase. Write it into the body via `github-write-issue` as clearly-labeled assumptions/recommendations (never overwrite the author's prose), then re-run `github-verify`. Whatever the agent could author is now structured spec; only genuinely human-only inputs remain.
+2. Relabel: remove the `claimed` label, add the `blocked` label **and** the `human_needed` marker label. Even after the agent drafted what it could, a pre-flight gate failure bounces the issue back to its author because it still needs a human to **confirm the drafted assumptions** or supply something no agent can invent — real missing credentials, access, or an irreducible product/scoping decision — so the marker tells a human scanning the board which blocked issues are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
    ```bash
-   CLAIMED=$(jq -r '.github.labels.build.claimed // "status:in-progress"' .lisa.config.json)
-   BLOCKED=$(jq -r '.github.labels.build.blocked // "status:blocked"' .lisa.config.json)
-   HUMAN_NEEDED=$(jq -r '.github.labels.build.human_needed // "human-needed"' .lisa.config.json)
+   _read_cfg() { local lv gv; lv=$(jq -r "$1 // empty" .lisa.config.local.json 2>/dev/null); gv=$(jq -r "$1 // empty" .lisa.config.json 2>/dev/null); echo "${lv:-${gv}}"; }
+   CLAIMED=$(_read_cfg '.github.labels.build.claimed'); CLAIMED="${CLAIMED:-status:in-progress}"
+   BLOCKED=$(_read_cfg '.github.labels.build.blocked'); BLOCKED="${BLOCKED:-status:blocked}"
+   HUMAN_NEEDED=$(_read_cfg '.github.labels.build.human_needed'); HUMAN_NEEDED="${HUMAN_NEEDED:-human-needed}"
    gh label create "$HUMAN_NEEDED" --color D93F0B --description "Blocked on human-only input (credentials / access / decision)" --repo <org>/<repo> 2>/dev/null || true
    gh issue edit <num> --repo <org>/<repo> --remove-label "$CLAIMED" --add-label "$BLOCKED" --add-label "$HUMAN_NEEDED"
    ```
-2. Reassign the issue back to its **author** (the original reporter — `author.login` from `gh issue view --json author`). Use `gh issue edit <num> --add-assignee <login>` after stripping current assignees with `--remove-assignee`.
-3. Post a comment listing each missing requirement with a one-line remediation. Prefix with `[<repo>]`:
+3. Reassign the issue back to its **author** (the original reporter — `author.login` from `gh issue view --json author`). Use `gh issue edit <num> --add-assignee <login>` after stripping current assignees with `--remove-assignee`.
+4. Post the **confirmation comment** from the `pre-flight-autofill` rule, **not** a bare remediation checklist: disclose it is a Claude draft, give one line per drafted section naming the key assumption made, list any remaining human-only item as a specific question with a recommended default, and close with *"review the drafted sections, correct anything wrong, then flip back to Ready and it builds — or reply with corrections."* Prefix with `[<repo>]`:
    ```bash
    gh issue comment <num> --repo <org>/<repo> --body-file /tmp/blocked-comment.md
    ```
-4. Stop. Do not run triage, do not delegate to a flow, do not start work.
+5. Stop. Do not run triage, do not delegate to a flow, do not start work.
 
 **Exception — single-repo scope is split, not blocked.** A single-repo-scope FAIL is the one gate failure the agent fixes rather than bounces to the author: a cross-repo work unit is a decomposition error the agent owns (S10 is `product_relevant: false`), not a product question. Instead of blocking, run the **work-time split procedure** in the `repo-scope-split` rule — narrow this issue to one repo, create a sibling issue per additional repo cloning its metadata, encode the producer→consumer dependency (`Blocked by #<n>` / `Blocks #<n>`), comment on the original, then re-run `github-verify` on the original and every new sibling. Block (per the path above) only if the split is ambiguous (see "When to block instead of split"). If single-repo scope was the only FAIL and the split succeeded, proceed to Step 3 once every resulting issue passes.
 
@@ -143,7 +145,7 @@ Note: `done` may be a string or an env-keyed map (`{ dev, staging, production }`
 
 ## Rules
 
-- Never auto-relabel build labels, with one explicit exception: when `github-verify` returns FAIL for the pre-flight gate (Step 2), relabel to the configured `blocked` label, add the configured `human_needed` marker label (`github.labels.build.human_needed`, default `human-needed`), and reassign to the original author. The build-intake owner transitions a successful issue from `claimed` directly to the configured `done` label after PR evidence is posted.
+- Never auto-relabel build labels, with one explicit exception: when `github-verify` returns FAIL for the pre-flight gate (Step 2), first run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the issue body as labeled assumptions), then relabel to the configured `blocked` label, add the configured `human_needed` marker label (`github.labels.build.human_needed`, default `human-needed`), and reassign to the original author with a confirmation comment. The build-intake owner transitions a successful issue from `claimed` directly to the configured `done` label after PR evidence is posted.
 - Always read the full issue graph via `github-read-issue` before determining intent — don't rely on the `type:` label alone.
 - Never create or materially edit an issue by calling `gh issue create` / `gh issue edit` directly — always delegate to `github-write-issue` (or, from a vendor-neutral caller, `tracker-write`) so relationships, Gherkin criteria, and metadata gates are enforced.
 - If sign-in credentials are in the issue body, extract and pass them to the flow. If the issue touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.

package/plugins/src/base/agents/jira-agent.md

@@ -47,12 +47,13 @@ Use the `jira-verify` skill to check the ticket against organizational standards
 
 **Gating behavior — this is the one place auto-transitioning is allowed:**
 
-If `jira-verify` returns `FAIL` on any of the above, do NOT continue:
-1. Transition the ticket status to the configured `blocked` status (typically `Blocked` — read from `.lisa.config.json` `jira.workflow.blocked` if present, otherwise the project's standard blocked status). Use `mcp__atlassian__transitionJiraIssue` or equivalent.
-2. **Add the `human_needed` marker label.** A pre-flight gate failure bounces the ticket back to its reporter precisely because it needs something **no agent and no automated retry can supply** — credentials, access, a product/scoping decision, or required ticket quality only the human can add. Add the configured label (`jira.labels.human_needed`, default `Human Needed`) to the ticket's `labels` field via `mcp__atlassian__editJiraIssue` — a lightweight metadata update permitted under this same gate exception. This is additive to (not a replacement for) the `blocked` status, so a human scanning the board sees at a glance which blocked tickets are waiting on them. If the label does not exist in the project, record that and proceed — the marker is best-effort. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
-3. Reassign the ticket to the **Reporter** (the human who filed it — not the Creator field, which may be a bot/integration).
-4. Post a comment using `mcp__atlassian__addCommentToJiraIssue` listing each missing requirement with a one-line remediation. Prefix with `[{repo}]`.
-5. Stop. Do not run triage, do not delegate to a flow, do not start work.
+If `jira-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the reporter:
+1. **Best-effort autofill (before blocking).** Run the **draft-then-block procedure** in the `pre-flight-autofill` rule: draft every *authorable* missing section — Technical Approach, Out of Scope, Gherkin acceptance criteria, expected-vs-actual, Repository, Relationship Search (run the git + JQL search, don't fabricate it), a Validation Journey **draft** via `jira-add-journey`, and a recommended Target Backend Environment — from the ticket's own content (title, description, screenshots, design links, repro steps) plus the codebase. Write it into the description via `jira-write-ticket` as clearly-labeled assumptions/recommendations (never overwrite the reporter's prose), then re-run `jira-verify`. Whatever the agent could author is now structured spec; only genuinely human-only inputs remain.
+2. Transition the ticket status to the configured `blocked` status (typically `Blocked` — read from `.lisa.config.json` `jira.workflow.blocked` if present, otherwise the project's standard blocked status). Use `mcp__atlassian__transitionJiraIssue` or equivalent.
+3. **Add the `human_needed` marker label.** Even after the agent drafted what it could, a pre-flight gate failure bounces the ticket back to its reporter because the ticket still needs a human to **confirm the drafted assumptions** or supply something no agent can invent — real missing credentials, access, or an irreducible product/scoping decision. Add the configured label (`jira.labels.human_needed`, default `Human Needed`) to the ticket's `labels` field via `mcp__atlassian__editJiraIssue` — a lightweight metadata update permitted under this same gate exception. This is additive to (not a replacement for) the `blocked` status, so a human scanning the board sees at a glance which blocked tickets are waiting on them. If the label does not exist in the project, record that and proceed — the marker is best-effort. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
+4. Reassign the ticket to the **Reporter** (the human who filed it — not the Creator field, which may be a bot/integration).
+5. Post a comment using `mcp__atlassian__addCommentToJiraIssue` — the **confirmation comment** from the `pre-flight-autofill` rule, **not** a bare remediation checklist: disclose it is a Claude draft, give one line per drafted section naming the key assumption made, list any remaining human-only item as a specific question with a recommended default, and close with *"review the drafted sections, correct anything wrong, then flip back to Ready and it builds — or reply with corrections."* Prefix with `[{repo}]`.
+6. Stop. Do not run triage, do not delegate to a flow, do not start work.
 
 **Exception — single-repo scope is split, not blocked.** A single-repo-scope FAIL is the one gate failure the agent fixes rather than bounces to the reporter: a cross-repo work unit is a decomposition error the agent owns (S10 is `product_relevant: false`), not a product question. Instead of blocking, run the **work-time split procedure** in the `repo-scope-split` rule — narrow this ticket to one repo, create a sibling per additional repo cloning its metadata, link the producer→consumer dependency (`Blocks` / `is blocked by`), comment on the original, then re-run `jira-verify` on the original and every new sibling. Block (per the path above) only if the split is ambiguous (see "When to block instead of split"). If single-repo scope was the only FAIL and the split succeeded, proceed to Step 3 once every resulting ticket passes.
 
@@ -123,7 +124,7 @@ Note: `done` may be a string or an env-keyed map (`{ dev, staging, production }`
 
 ## Rules
 
-- Never auto-transition ticket status, with one explicit exception: when `jira-verify` returns `FAIL` for the pre-flight gate (Step 2), transition to the configured `blocked` status, add the configured `human_needed` marker label (`jira.labels.human_needed`, default `Human Needed`), and reassign to the Reporter. Every other status change remains a suggestion the human confirms.
+- Never auto-transition ticket status, with one explicit exception: when `jira-verify` returns `FAIL` for the pre-flight gate (Step 2), first run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the ticket as labeled assumptions), then transition to the configured `blocked` status, add the configured `human_needed` marker label (`jira.labels.human_needed`, default `Human Needed`), and reassign to the Reporter with a confirmation comment. Every other status change remains a suggestion the human confirms.
 - Any transition is config-bound: never invent transitions; a transition may target only a status named in `config.jira.workflow`. Don't guess from the live workflow. The evidence-time review hop (Step 7) follows this rule too — it is config-bound, optional, and skipped when `jira.workflow.review` is absent (the ticket stays in `claimed`).
 - Always read the full ticket graph via `jira-read-ticket` before determining intent — don't rely on ticket type alone
 - Never create or materially edit a ticket by calling MCP write tools directly — always delegate to `jira-write-ticket` so relationships, Gherkin criteria, and metadata gates are enforced

package/plugins/src/base/agents/linear-agent.md

@@ -49,11 +49,12 @@ Use the `linear-verify` skill to check the item against organizational standards
 
 Resolve build labels from `.lisa.config.json` `linear.labels.build.*` (defaults: `status:ready` / `status:in-progress` / `status:code-review`); resolve the `blocked` label from the same section (`linear.labels.build.blocked`, default `status:blocked`) and the `human_needed` marker label from the same section (`linear.labels.build.human_needed`, default `human-needed`).
 
-If `linear-verify` returns `FAIL` on any of the above, do NOT continue:
-1. Update labels via `mcp__linear-server__save_issue`: remove the current build label, add the configured `blocked` label **and** the configured `human_needed` marker label. (Create either label via `create_issue_label` if needed.) A pre-flight gate failure bounces the item back to its creator precisely because it needs something **no agent and no automated retry can supply** — credentials, access, a product/scoping decision, or required item quality only the human can add — so the marker tells a human scanning the board which blocked items are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
-2. Reassign the item to the **Issue creator** (the human who filed it — Linear's `creator` field).
-3. Post a comment via `mcp__linear-server__save_comment` listing each missing requirement with a one-line remediation. Prefix with `[{repo}]`.
-4. Stop. Do not run triage, do not delegate to a flow, do not start work.
+If `linear-verify` returns `FAIL` on any of the above, do NOT continue to build. **Draft the missing spec content first, then block for confirmation** — never bounce a raw "go write all this" checklist back to the creator:
+1. **Best-effort autofill (before blocking).** Run the **draft-then-block procedure** in the `pre-flight-autofill` rule: draft every *authorable* missing section — Technical Approach, Out of Scope, Gherkin acceptance criteria, expected-vs-actual, Repository, Relationship Search (run the git + Linear search, don't fabricate it), a Validation Journey **draft** via `linear-add-journey`, and a recommended Target Backend Environment — from the item's own content (title, description, screenshots, design links, repro steps) plus the codebase. Write it into the description via `linear-write-issue` as clearly-labeled assumptions/recommendations (never overwrite the creator's prose), then re-run `linear-verify`. Whatever the agent could author is now structured spec; only genuinely human-only inputs remain.
+2. Update labels via `mcp__linear-server__save_issue`: remove the current build label, add the configured `blocked` label **and** the configured `human_needed` marker label. (Create either label via `create_issue_label` if needed.) Even after the agent drafted what it could, a pre-flight gate failure bounces the item back to its creator because it still needs a human to **confirm the drafted assumptions** or supply something no agent can invent — real missing credentials, access, or an irreducible product/scoping decision — so the marker tells a human scanning the board which blocked items are waiting on them. The marker is additive to `blocked`, not a replacement. (See the `config-resolution` rule's "Build markers" for when the marker applies and when it must NOT.)
+3. Reassign the item to the **Issue creator** (the human who filed it — Linear's `creator` field).
+4. Post the **confirmation comment** from the `pre-flight-autofill` rule via `mcp__linear-server__save_comment`, **not** a bare remediation checklist: disclose it is a Claude draft, give one line per drafted section naming the key assumption made, list any remaining human-only item as a specific question with a recommended default, and close with *"review the drafted sections, correct anything wrong, then flip back to Ready and it builds — or reply with corrections."* Prefix with `[{repo}]`.
+5. Stop. Do not run triage, do not delegate to a flow, do not start work.
 
 **Exception — single-repo scope is split, not blocked.** A single-repo-scope FAIL is the one gate failure the agent fixes rather than bounces to the creator: a cross-repo work unit is a decomposition error the agent owns (S10 is `product_relevant: false`), not a product question. Instead of blocking, run the **work-time split procedure** in the `repo-scope-split` rule — narrow this item to one repo, create a sibling Issue per additional repo cloning its metadata (same `projectId`), add the producer→consumer blocking relation, comment on the original, then re-run `linear-verify` on the original and every new sibling. Block (per the path above) only if the split is ambiguous (see "When to block instead of split"). If single-repo scope was the only FAIL and the split succeeded, proceed to Step 3 once every resulting item passes.
 
@@ -127,7 +128,7 @@ The label transitions ARE the canonical signal. The native `state` field stays a
 
 ## Rules
 
-- Never auto-transition the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), update labels to the configured `blocked` label, add the configured `human_needed` marker label (`linear.labels.build.human_needed`, default `human-needed`), and reassign to the creator. Every other status change remains a label-driven suggestion.
+- Never auto-transition the native Linear `state`, with one explicit exception: when `linear-verify` returns `FAIL` for the pre-flight gate (Step 2), first run the `pre-flight-autofill` draft-then-block procedure (draft the authorable missing sections into the description as labeled assumptions), then update labels to the configured `blocked` label, add the configured `human_needed` marker label (`linear.labels.build.human_needed`, default `human-needed`), and reassign to the creator with a confirmation comment. Every other status change remains a label-driven suggestion.
 - Always read the full item graph via `linear-read-issue` before determining intent — don't rely on type labels alone.
 - Never create or materially edit an item by calling MCP write tools directly — always delegate to `linear-write-issue` so relationships, Gherkin criteria, and metadata gates are enforced. Two explicit exceptions are permitted: (1) the Step 2 pre-flight failure path (when `linear-verify` returns `FAIL`) may call `mcp__linear-server__save_issue` and `mcp__linear-server__save_comment` directly to set `status:blocked`, add the configured `human_needed` marker label, and reassign to the creator — this narrow exception is already granted by the rule above; (2) the Step 3 triage path may call `mcp__linear-server__save_comment` to post triage findings and `mcp__linear-server__save_issue` to add the `claude-triaged-{repo}` label — these are lightweight metadata updates that do not create or materially edit ticket content and therefore do not need to route through `linear-write-issue`.
 - If sign-in credentials are in the item, extract and pass them to the flow. If the item touches an authenticated surface and credentials are missing, that is a Step 2 failure — block and reassign rather than guessing.

package/plugins/src/base/rules/eager/pre-flight-autofill.md

@@ -0,0 +1,65 @@
+# Pre-Flight Spec Autofill — Draft-Then-Block (load-bearing)
+
+When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
+gaps, do **not** bounce a raw checklist back to the reporter. Most "missing
+required spec content" gaps are **authorable** from material already on the work
+item (title, description, screenshots, design links, repro steps) plus the
+codebase. **Draft** a best-effort version of every authorable gap, write it into
+the item as clearly-labeled **assumptions/recommendations**, and only **then**
+block — turning the human ask from *"author all this"* into *"confirm or correct
+my draft, then flip back to Ready."* Same shape as `repo-scope-split`: the agent
+does the work it can; the human decides only what only a human can.
+
+This does **not** widen the gate — every required section must still exist
+before build. It replaces an empty demand with a defensible first draft, and it
+breaks the `Ready ↔ Blocked` ping-pong loop that a raw checklist causes (the
+information was already on the ticket; only the structure was missing).
+
+## Two tiers
+
+- **Tier A — authorable (always draft):** Technical Approach, Out of Scope,
+  Gherkin Acceptance Criteria (one scenario per fix), expected-vs-actual +
+  environment, Repository, Relationship Search (actually run the git+tracker
+  search — don't fabricate "none found"), Validation Journey **draft** (via the
+  vendor `*-add-journey` skill), Target Backend Environment (recommend a default
+  from `deploy.branches`/config).
+- **Tier B — irreducibly human:** real credentials/access that exist nowhere on
+  the item or in repo test-user docs; a genuine product/scoping decision with no
+  defensible default. Still propose a recommended default where one exists; ask
+  a specific question only where none does.
+
+## Procedure
+
+1. Enumerate FAIL categories from `*-verify`. If S10 failed, run
+   `repo-scope-split` first (split, not autofill).
+2. Draft each Tier-A gap grounded in item material + codebase; tag every
+   inference as an assumption. **Never overwrite human prose** — add/augment
+   sections only.
+3. Write the draft via the vendor write skill (`jira-write-ticket` /
+   `github-write-issue` / `linear-write-issue`); draft the Validation Journey
+   via `*-add-journey`.
+4. Re-run `*-verify`. Structural gates should now PASS; anything still failing
+   is Tier B — name it in the comment.
+5. Block as usual (`blocked` status + `human_needed` marker + reassign to
+   Reporter) but post the **confirmation comment**, not a checklist: disclose
+   it's a Claude draft, one line per drafted section + its key assumption,
+   Tier-B items as specific questions with defaults, and close with *"correct
+   anything wrong, then flip back to Ready and it builds — or reply with
+   corrections."*
+6. **Loop-safety:** if the item already carries the agent's draft, refine only
+   the still-failing gaps; don't redraft. Re-readying after review is the
+   human's approval — the next claim's `*-verify` PASSes and build proceeds.
+
+## When you genuinely cannot autofill
+
+If drafting would be fabrication (no fix/expected behavior described, no usable
+design ref, uninformative title, no codebase anchor), block as before — but
+phrase each gap as a specific question with a default where defensible. Never a
+bare checklist when a defensible draft is possible.
+
+The agent writes **spec/criteria, never code**, at this gate — authoring AC and
+a validation journey is explicitly permitted here (this supersedes the older
+"the build agent does not author the missing spec content" stance).
+
+Full procedure, tier detail, confirmation-comment template, and vendor mechanics:
+[reference/pre-flight-autofill.md](../reference/pre-flight-autofill.md).

package/plugins/src/base/rules/reference/base-rules.md

@@ -78,7 +78,7 @@ JIRA Discipline:
   - **Gherkin acceptance criteria** (Given/When/Then) so the implementer can verify behavior without guessing.
   - **Relationship discovery evidence** — either an issue link to a related ticket, or a documented search showing none was found (see Relationship Discovery in jira-verify).
 - Ticket metadata MUST include an **epic parent** for non-bug, non-epic tickets so every Story/Task/Sub-task is traceable to a strategic goal.
-- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, transition the ticket to Blocked, reassign to the **Reporter**, and post a comment listing exactly what is missing. Do not start work. This is the one place where auto-transitioning status is allowed.
+- Pre-flight gate before starting work on any ticket: if the description is missing target backend environment (when applicable), sign-in credentials (when applicable), Gherkin acceptance criteria, epic parent (non-bug/non-epic), or relationship discovery evidence, first **draft** the authorable missing sections into the ticket as clearly-labeled assumptions (the `pre-flight-autofill` draft-then-block procedure — the agent writes spec, never code, here), then transition the ticket to Blocked, reassign to the **Reporter**, and post a **confirmation** comment asking them to confirm the drafted assumptions (not a bare "go write all this" checklist). Do not start work. This is the one place where auto-transitioning status is allowed.
 - When checking for associated pull requests on a JIRA issue, check the **Development panel** — not just comments or description text. The Development panel shows PRs, commits, branches, and builds linked via the GitHub-Jira integration. Query it via the dev-status API:
   ```bash
   ISSUE_ID=$(curl -s -u "${JIRA_LOGIN}:${JIRA_API_TOKEN}" \

package/plugins/src/base/rules/reference/config-resolution.md

@@ -330,7 +330,7 @@ A **marker** is an additive label applied *alongside* a lifecycle role, not a st
 
 | Marker | What it means | JIRA default | GitHub/Linear default |
 |---|---|---|---|
-| `human_needed` | Applied with `blocked` when the block genuinely requires something **no agent and no automated retry can supply** — credentials, access/permissions, a product or scoping decision, or required ticket quality only the human reporter can add. | `Human Needed` (label) | `human-needed` (label) |
+| `human_needed` | Applied with `blocked` when — **after the agent has drafted every authorable missing section via the `pre-flight-autofill` procedure** — the block still requires a human to confirm the drafted assumptions or supply something no agent can invent: real missing credentials, access/permissions, or an irreducible product/scoping decision. | `Human Needed` (label) | `human-needed` (label) |
 
 Resolution keys:
 
@@ -338,7 +338,7 @@ Resolution keys:
 - GitHub: `github.labels.build.human_needed` (default `human-needed`). Added next to the `blocked` label.
 - Linear: `linear.labels.build.human_needed` (default `human-needed`). Added next to the `blocked` label.
 
-**When to apply it.** Apply `human_needed` only when a human must act before the item can move — the pre-flight gate failures that bounce a ticket back to its reporter (missing credentials, missing acceptance criteria / validation journey, missing parent/epic, an ambiguous product or scoping decision) are exactly this case.
+**When to apply it.** Apply `human_needed` only when a human must act before the item can move — the pre-flight gate failures that bounce a ticket back to its reporter are exactly this case, but **only after** the agent has run the `pre-flight-autofill` draft-then-block procedure (drafting the authorable gaps — acceptance criteria, validation journey, repository, relationship search, etc. — into the ticket as labeled assumptions). What then remains for the human is to **confirm those assumptions** or supply a genuinely human-only input (real missing credentials, an irreducible product/scoping decision). The marker means "a human must confirm or decide," not "a human must author from scratch."
 
 **When NOT to apply it.** Do **not** apply `human_needed` to a block that an automated cycle can clear on its own: a block whose `is blocked by` dependency is another tracked ticket that will build and close (for example a `repair-intake`-filed build-ready fix ticket for an unmergeable PR or a failed deploy), or any block waiting only on a retry. Those self-heal; flagging them for a human is noise. If such an item already carries a stale `human_needed` marker, clear it when the block becomes auto-recoverable.
 

package/plugins/src/base/rules/reference/pre-flight-autofill.md

@@ -0,0 +1,142 @@
+# Pre-Flight Spec Autofill (Draft-Then-Block)
+
+When the pre-flight gate (`*-agent` Step 2) returns `FAIL` on **ticket-quality**
+gaps, the agent does **not** bounce a raw "here is everything you must write"
+checklist back to the reporter. Most "missing required spec content" gaps are
+**authorable** from material already on the work item (title, description,
+screenshots, design links, reproduction steps) plus the codebase. The agent
+drafts a best-effort version of every authorable gap, writes it into the work
+item as clearly-labeled **assumptions and recommendations**, and only **then**
+blocks — turning the human ask from *"author all of this from scratch"* into
+*"confirm or correct my draft, then flip it back to Ready."*
+
+This is the same shape as the `repo-scope-split` exception: the agent does the
+work it can and reserves the human for what only a human can decide. It does
+**not** widen the gate — every required section must still exist before build;
+autofill just supplies a defensible first draft instead of an empty demand.
+
+## Why this exists
+
+The build + screenshot-diff verification pipeline needs **structured,
+machine-readable** sections — Gherkin acceptance criteria, a Validation Journey
+with `[SCREENSHOT:]`/`[EVIDENCE:]` markers, Sign-in Required, Target Backend
+Environment, Repository. A bug report routinely contains all of that
+*information* in prose, screenshots, or a Figma link, but not the *structure*.
+Dumping the checklist straight back produces a ping-pong loop: the item bounces
+`Ready → Blocked → Ready` on every intake cycle because nobody re-types the
+existing information into headings, and the reporter reasonably objects that the
+information is already there. Drafting the structure breaks the loop and
+respects the reporter's time — the human reviews a draft instead of authoring a
+spec.
+
+## Two tiers of gap
+
+**Tier A — authorable (always attempt a draft):**
+
+- **Technical Approach** — locate the affected component/files in the repo (the
+  title and description usually name the surface, e.g. "Player modal"); state
+  which files likely change and the expected layout. Flag inferences as
+  assumptions.
+- **Out of Scope** — a one-line boundary derived from the fix list.
+- **Acceptance Criteria (Gherkin)** — convert each described fix / expected
+  behavior into `Given/When/Then`. One scenario per discrete fix.
+- **Expected-vs-actual + environment** — restate the bug as explicit expected
+  vs actual, naming the environment the screenshots/description came from.
+- **Repository** — resolve per `config-resolution` repo scoping and state it.
+- **Relationship Search** — actually **run** the git + tracker search; record
+  the queries and results and link anything found. Do not fabricate a
+  "none found" note.
+- **Validation Journey (draft)** — run the vendor `*-add-journey` skill to draft
+  the click-path, markers, and viewports from the reproduction steps. This is a
+  draft for human approval, not the final ratified contract.
+- **Target Backend Environment** — recommend a default from `deploy.branches` /
+  config (the backend the FE points at for verification) and state it as a
+  recommendation.
+
+**Tier B — irreducibly human (cannot invent — but still propose a default):**
+
+- **Real credentials / access** that exist nowhere on the item or in the repo's
+  known test-user docs. (If credentials are present in prose, that is Tier A —
+  lift them into a Sign-in Required section.)
+- **A genuine product / scoping decision** with no defensible default — the
+  exact expected behavior when the ticket is internally contradictory or the
+  design reference is missing.
+
+For Tier B, still propose a **recommended default** wherever one is defensible,
+and ask a **specific question** only where none is. Never reduce a Tier B item
+to a bare demand.
+
+## Procedure
+
+1. **Enumerate the FAIL categories** from `*-verify`.
+2. **Run `repo-scope-split` first** if S10 (single-repo scope) failed — that is
+   a split, not an autofill. Autofill handles the remaining quality gaps.
+3. **Draft each Tier-A gap** grounded in the work-item material + codebase.
+   Every inferred value is explicitly tagged as an assumption/recommendation
+   (lead the drafted block with a note: *"Drafted by Claude — assumptions
+   flagged inline; please confirm or correct."*). **Never overwrite
+   human-authored prose** — add the missing structured sections; if a section
+   exists but is thin, augment it without discarding the human's words.
+4. **Write the draft into the work item** via the vendor write skill
+   (`jira-write-ticket` / `github-write-issue` / `linear-write-issue`) so
+   relationship and metadata gates stay enforced. Draft the Validation Journey
+   via the vendor `*-add-journey` skill.
+5. **Re-run `*-verify`.** The structural gates should now PASS (the content
+   exists, even if assumed). Any gate that still FAILs is Tier B — leave it and
+   name it precisely in the comment.
+6. **Block as usual** — transition/relabel to the configured `blocked` status,
+   add the `human_needed` marker, reassign to the **Reporter** — but post the
+   **confirmation comment** (below), not a remediation checklist.
+7. **Idempotency / loop-safety.** If the item already carries the agent's draft
+   from a prior cycle, do **not** redraft from scratch — refine only the gaps
+   still failing and refresh the confirmation comment. When the reporter flips
+   the item back to Ready, the next claim re-runs `*-verify`; if it now PASSes,
+   build proceeds on the draft the reporter approved by re-readying it. That is
+   what breaks the `Ready ↔ Blocked` loop.
+
+## The confirmation comment (replaces the remediation checklist)
+
+- **Disclose**: posted by Claude (AI build agent); identify the content as a
+  draft.
+- **Frame it**: the item had the right information but lacked the structured
+  sections the pipeline needs, so the agent drafted them — the report's validity
+  was never in question.
+- **One line per drafted section**, naming the section and the key assumption
+  (e.g. *"Acceptance Criteria — drafted 4 Gherkin scenarios from the fix list;
+  assumed 'Search result' restores the prior query terms."*).
+- **Tier-B items still required**, each as a specific question with a
+  recommended default where one exists.
+- **Close with the action**: *"Review the drafted sections in the description.
+  Correct anything wrong, then flip back to Ready and it builds immediately — or
+  reply with corrections and I'll revise."* Keep the `human_needed` marker until
+  then.
+
+## When you genuinely cannot autofill (fall back to the plain block)
+
+If the item is so underspecified that drafting would be fabrication — no fix or
+expected behavior described, no usable design reference, an uninformative title,
+and the codebase gives no anchor — block as before. Even then, phrase **each gap
+as a specific question** and propose a default wherever one is defensible (the
+"Human-Needed is a last resort" principle). Never bounce a bare checklist when a
+defensible draft is possible.
+
+## Disclosure & safety
+
+- Agent-drafted content is **always attributed to Claude and marked as
+  assumptions**, so a human never mistakes a guess for their own ratified spec.
+- The agent writes **spec/criteria, never code**, at this gate. Drafting
+  acceptance criteria and a validation journey is authoring, not implementation
+  — explicitly permitted here. This **supersedes** the older "the build agent
+  does not author the missing spec content" stance, which produced the
+  bounce-loop.
+
+## Vendor mechanics
+
+- **JIRA** — draft sections via `jira-write-ticket`; Validation Journey via
+  `jira-add-journey`; block + label + reassign + comment via the `jira-agent`
+  Step 2 exception (`transitionJiraIssue`, `editJiraIssue` for the label and
+  assignee, `addCommentToJiraIssue`).
+- **GitHub** — `github-write-issue`; `github-add-journey`; relabel + reassign +
+  comment via `gh`.
+- **Linear** — `linear-write-issue`; `linear-add-journey`; `save_issue` +
+  `save_comment`.