methodology-framework 0.1.0__py3-none-any.whl

methodology_framework/jira_shapes/automation_rules.yaml

@@ -0,0 +1,85 @@
+# Canonical Jira automation rule definitions for methodology-framework projects.
+#
+# These rules are provisioned by the bootstrap CLI on project adoption.
+# All references to a specific project key use {{PROJECT_KEY}} for substitution.
+#
+# JSON-schema: each rule has name, description, trigger, conditions[], and
+# actions[].
+
+schema_version: "1.0"
+
+automation_rules:
+  - name: "PR merged → transition to Done"
+    key: "pr_merged_to_done"
+    description: >-
+      When a pull request is merged and its title contains the issue key,
+      transition the linked issue to Done. Gated by a path filter: only fires
+      if the PR changes files outside docs/stories/** (docs-only PRs like
+      story-file post-exec-notes updates do not auto-close the ticket).
+    trigger:
+      type: "pull_request_merged"
+      repository: "{{PROJECT_KEY}}"
+    conditions:
+      - type: "pr_title_contains_issue_key"
+        description: >-
+          pullRequest.title contains issue.key — ensures only the primary
+          ticket auto-transitions. PR titles must contain exactly one Jira key.
+      - type: "changed_files_outside_path"
+        path_filter: "docs/stories/**"
+        description: >-
+          At least one file changed by the PR is outside docs/stories/**.
+          Prevents docs-only PRs (e.g. post-execution notes updates) from
+          prematurely closing the ticket.
+    actions:
+      - type: "transition_issue"
+        target_status: "Done"
+        transition_id: 41
+
+  - name: "Dependency resolution → Waiting to Ready for Agent"
+    key: "dependency_resolution"
+    description: >-
+      When all blocking issues of a Waiting ticket reach Done status,
+      automatically transition the ticket from Waiting to Ready for Agent.
+      This is the sync-driven dependency resolution mechanism.
+    trigger:
+      type: "issue_transitioned"
+      target_status: "Done"
+    conditions:
+      - type: "all_linked_blocking_issues_done"
+        link_type: "is blocked by"
+        description: >-
+          Every issue linked via 'is blocked by' relationship is in Done status.
+      - type: "issue_in_status"
+        status: "Waiting"
+        description: >-
+          The dependent issue is currently in Waiting status.
+    actions:
+      - type: "transition_issue"
+        target_status: "Ready for AI agent"
+        transition_id: 2
+
+  - name: "BLOCKED protection"
+    key: "blocked_protection"
+    description: >-
+      Prevents automated workflows from transitioning a ticket OUT of Blocked
+      status. Only human operators may unblock a ticket. This enforces the
+      methodology's distinction: Blocked = human intervention required;
+      Waiting = auto-resolves when deps merge.
+    trigger:
+      type: "issue_transitioned"
+      source_status: "Blocked"
+    conditions:
+      - type: "actor_is_automation"
+        description: >-
+          The transition was triggered by an automation rule or sync workflow,
+          not a human operator.
+    actions:
+      - type: "revert_transition"
+        description: >-
+          Transition the issue back to Blocked. Log a warning comment noting
+          the attempted automated un-block was prevented.
+      - type: "add_comment"
+        body: >-
+          Automated transition out of Blocked was prevented by the BLOCKED
+          protection rule. Only human operators may transition tickets out
+          of Blocked status.

methodology_framework/jira_shapes/custom_fields.yaml

@@ -0,0 +1,44 @@
+# Canonical Jira custom field definitions for methodology-framework projects.
+#
+# Mirrors the three required custom fields from the SCRUM project.
+# These fields are provisioned by the bootstrap CLI on project adoption.
+#
+# JSON-schema: each field has name, key, type, description, required_at_create,
+# and optional constraints.
+
+schema_version: "1.0"
+
+custom_fields:
+  - name: "Story File"
+    key: "story_file"
+    type: "url"
+    description: >-
+      URL to the canonical story file in the repo. Set by the outbound sync
+      workflow on story creation. Format:
+      https://github.com/<owner>/<repo>/blob/main/docs/stories/<phase>/<slug>.md
+    required_at_create: false
+    constraints:
+      pattern: "^https://.+"
+
+  - name: "Requirement IDs"
+    key: "requirement_ids"
+    type: "labels"
+    description: >-
+      Multi-value field containing the REQ-id(s) this story implements.
+      Values come from the project's use-case registry (e.g. REQ-VIZ-12,
+      REQ-MET-PORT). Set by the outbound sync workflow from story frontmatter.
+    required_at_create: false
+    constraints:
+      allow_custom_values: true
+
+  - name: "Agent Estimate"
+    key: "agent_estimate"
+    type: "number"
+    description: >-
+      Estimated agent-hours for the story. Populated from the story frontmatter
+      estimate field (converted to numeric hours). Used for capacity planning
+      and estimate_overrun drift-trigger thresholds.
+    required_at_create: false
+    constraints:
+      min: 0
+      precision: 1

methodology_framework/jira_shapes/workflow.yaml

@@ -0,0 +1,135 @@
+# Canonical Jira workflow shape definition for methodology-framework projects.
+#
+# Mirrors the SCRUM project workflow as the reference shape.
+# All references to a specific project key use {{PROJECT_KEY}} for substitution.
+#
+# JSON-schema: each status has name, description, status_id, and transitions[].
+# Each transition has name, transition_id, target, and allowed_actors[].
+
+schema_version: "1.0"
+
+statuses:
+  - name: "To Do"
+    description: >-
+      Backlog state. Stories with manual-gate label sit here.
+      Initial state for stories that are not yet ready for agent pickup.
+    status_id: 10000
+    transitions:
+      - name: "Ready for AI agent"
+        transition_id: 2
+        target: "Ready for AI agent"
+        allowed_actors: ["sync-workflow", "operator"]
+      - name: "Won't do"
+        transition_id: 4
+        target: "Won't do"
+        allowed_actors: ["sync-workflow", "operator"]
+
+  - name: "Ready for AI agent"
+    description: >-
+      Trigger-firing state. Devin picks up tickets from this status via the
+      automation trigger. Stories land here when all depends_on are resolved.
+    status_id: 10070
+    transitions:
+      - name: "In Progress"
+        transition_id: 21
+        target: "In Progress"
+        allowed_actors: ["agent", "operator"]
+      - name: "Blocked"
+        transition_id: 3
+        target: "Blocked"
+        allowed_actors: ["agent", "operator"]
+      - name: "To Do"
+        transition_id: 11
+        target: "To Do"
+        allowed_actors: ["operator"]
+
+  - name: "In Progress"
+    description: >-
+      Agent is actively implementing. Read-only for humans during this state.
+      Agent transitions here on session start.
+    status_id: 10001
+    transitions:
+      - name: "In Review"
+        transition_id: 31
+        target: "In Review"
+        allowed_actors: ["agent", "operator"]
+      - name: "Blocked"
+        transition_id: 3
+        target: "Blocked"
+        allowed_actors: ["agent", "operator"]
+      - name: "Waiting"
+        transition_id: 5
+        target: "Waiting"
+        allowed_actors: ["sync-workflow", "operator"]
+
+  - name: "In Review"
+    description: >-
+      PR is open and awaiting human review. Agent transitions here on PR open.
+      PR link is posted as a remote link by the GitHub-Jira integration.
+    status_id: 10002
+    transitions:
+      - name: "Done"
+        transition_id: 41
+        target: "Done"
+        allowed_actors: ["jira-automation", "operator"]
+      - name: "In Progress"
+        transition_id: 21
+        target: "In Progress"
+        allowed_actors: ["operator"]
+      - name: "Blocked"
+        transition_id: 3
+        target: "Blocked"
+        allowed_actors: ["operator"]
+
+  - name: "Waiting"
+    description: >-
+      Dependency not yet resolved. Auto-resolves when blocking issues reach Done.
+      Sync-driven; distinct from Blocked (which requires human intervention).
+    status_id: 10137
+    transitions:
+      - name: "Ready for AI agent"
+        transition_id: 2
+        target: "Ready for AI agent"
+        allowed_actors: ["sync-workflow", "operator"]
+      - name: "Blocked"
+        transition_id: 3
+        target: "Blocked"
+        allowed_actors: ["operator"]
+      - name: "To Do"
+        transition_id: 11
+        target: "To Do"
+        allowed_actors: ["operator"]
+
+  - name: "Blocked"
+    description: >-
+      Human attention required. Reserved for drift-trigger escalations:
+      ambiguity_escalation, ac_verification_fail, ci_repeat_fail,
+      estimate_overrun (3x), file_overlap_with_open_story.
+    status_id: 10103
+    transitions:
+      - name: "Ready for AI agent"
+        transition_id: 2
+        target: "Ready for AI agent"
+        allowed_actors: ["operator"]
+      - name: "To Do"
+        transition_id: 11
+        target: "To Do"
+        allowed_actors: ["operator"]
+      - name: "Won't do"
+        transition_id: 4
+        target: "Won't do"
+        allowed_actors: ["operator"]
+
+  - name: "Done"
+    description: >-
+      Terminal success state. Reached via Jira automation rule on PR merge
+      (gated by pullRequest.title contains issue.key).
+    status_id: 10003
+    transitions: []
+
+  - name: "Won't do"
+    description: >-
+      Terminal rejected state. Reached via sync workflow on story file rename
+      (prefixed with underscore) or by operator decision.
+    status_id: 10104
+    transitions: []

methodology_framework/playbooks/scrum-router.body.md

@@ -0,0 +1,217 @@
+---
+playbook_id: scrum-router
+version: 1.2.0
+changelog:
+  - "1.2.0 (2026-05-27): New convention — agent writes pre-execution scoping into the story file's new ## Scoping notes (pre-execution) section as the first commit of the implementation branch. New convention — agent populates the ## Post-execution notes block before opening PR; empty-default stubs are forbidden. MINOR bump per SemVer (additive new conventions)."
+  - "1.1.1 (2026-05-25): Bug fixes in the build + register pipeline — (1) preserve Variables-required section from substitution; (2) substitute version literal from frontmatter into the audit-echo line via {{VERSION}}; (3) look up existing Devin playbook by playbook_id slug, not rendered H1 title. No body content changes; PATCH-level bump."
+  - "1.1.0 (2026-05-24): Add PR-title-single-key convention (step 13 sub-section + Forbidden Action). The 1.0.0 changelog claimed this was included but the text was missing — uncommitted edits to the pre-relocation file at .devin/playbooks/ never landed in main before the relocation ran. This port brings the convention into the canonical body and corrects the changelog."
+  - "1.0.0 (2026-05-24): Initial extraction from project-specific to methodology-central. Encodes drift triggers, file-overlap rule, lifecycle status hygiene (Waiting vs Blocked). Parameterized via {{PROJECT_KEY}}, {{REPO}}, {{REQ_DOC_PATH}}, {{CONFIG_DOC_PATH}}, {{STORY_PATH_PATTERN}}. (Note: this entry originally also claimed the PR-title-single-key convention; that text was ported separately in 1.1.0.)"
+---
+
+## Versioning
+
+This playbook follows [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** — breaking changes to required reading or step numbering (consumers must re-read and possibly adjust their bindings or workflows).
+- **MINOR** — new conventions, new drift triggers, new steps (additive; consumers inherit new behavior on next pin bump).
+- **PATCH** — clarifications and language tightenings (no behavioral change; safe to adopt without review).
+
+When bumping the version: update the `version:` field in the frontmatter above, add a changelog entry, and update the consuming project's `playbook_version` pin in their config doc.
+
+## Variables required
+
+Consuming projects must provide bindings for the following placeholders. The build-time concatenation script (`scripts/build_playbook.py`) or equivalent registration mechanism substitutes these before the playbook is registered in Devin's webapp.
+
+| Placeholder | Description | Example (this project) |
+|---|---|---|
+| `{{PROJECT_KEY}}` | Jira project key for the consuming project. | `SCRUM` |
+| `{{REPO}}` | GitHub repository identifier (`owner/repo`). | `whiteout59/centralized-pipeline-ui` |
+| `{{REQ_DOC_PATH}}` | Path to the project's requirements / use-case registry doc. | `docs/use-cases.md` |
+| `{{CONFIG_DOC_PATH}}` | Path to the project's Jira pickup config doc. | `docs/jira-pickup-config.md` |
+| `{{STORY_PATH_PATTERN}}` | Glob-style base path to the story directories (include trailing `/`). | `docs/stories/{phase1,phase2}/` |
+| `{{VERSION}}` | Playbook version from frontmatter; injected automatically by the build script. | `1.2.0` |
+
+# {{PROJECT_KEY}} ticket pickup (router)
+
+## Overview
+
+You have been spawned by Devin's Jira pickup automation on the `{{REPO}}` repository (Jira project key `{{PROJECT_KEY}}`). Your job is to route the work from the ticket to the matching story file in this repo and execute the per-story instructions found there. You are **not** authoring per-story procedure — that's in the story file. You **are** the stable agent shell that finds, validates, scopes, and (in direct mode) executes that procedure under the project's universal rules.
+
+The Jira integration is configured in **scoping-only** mode for the POC. That means: when this playbook is triggered by a state transition, you produce *only* the scoping comment (step 9 of the Procedure) and stop. A human then clicks "Start session" to spawn the implementation run, which runs this same playbook past step 9.
+
+**Required reading before you start, in order:**
+
+1. `CLAUDE.md` — project context; locked decisions; conventions; "Where things live."
+2. `methodology/devin-jira-pickup.md` — the inbound-side methodology (what this playbook implements).
+3. `methodology/devin-story-format.md` — the 8-section story schema, the `Execution recipe` section, and frontmatter spec.
+4. `methodology/runbook-net-new-via-agents.md` — full SDLC runbook. Pay special attention to § 4.3 (drift triggers) and § 7 (synthesis pass).
+5. `{{CONFIG_DOC_PATH}}` — this project's instantiation: state names, bootstrap mechanism, smoke-test plan.
+
+## What's Needed From User
+
+The Jira ticket must give you enough information to locate the corresponding story file in the repo. Try the lookup mechanisms below in order, stopping at the first one that resolves to exactly one story file:
+
+1. **Frontmatter `jira_key:`** — story file's frontmatter has `jira_key: {{PROJECT_KEY}}-XXX` matching the ticket key. *(Canonical going forward; not yet present on existing stories — see the note in Advice and Pointers about the maturity gradient.)*
+2. **Exact title match** — the Jira ticket's summary matches the story file's frontmatter `title:` field verbatim. This is the outbound-sync convention (`methodology/devin-story-format.md`), so any story filed via that sync should match here.
+3. **Explicit path in description** — the ticket description references a specific story-file path under `{{STORY_PATH_PATTERN}}`.
+
+If none of these resolve to exactly one story file (or multiple stories match ambiguously), raise an `ambiguity_escalation` per runbook § 4.3 in the scoping comment and stop.
+
+The matched story file ideally contains an `Execution recipe` section (now specified as the 8th body section in `methodology/devin-story-format.md` § "Body structure"; mandatory for Phase-2 forward stories, optional for Phase-1 `manual-gate`-labeled backfill stories). If the recipe is **present**, follow it. If it's **absent** (Phase-1 backfill, or any pre-spec story not yet retrofitted), fall back to inferring the procedure from the story's `Acceptance criteria`, `Files`, and `Validation` sections — and cap your scoping-comment confidence at MEDIUM. If those three sections are themselves missing or vague, raise an `ambiguity_escalation`.
+
+## Procedure
+
+1. Clone the repo and check out `main`. First line of your substantive output (scoping comment OR implementation log) MUST be: `Playbook: scrum-router@{{VERSION}} (binding: {{PROJECT_KEY}})`. This makes the active playbook version unambiguous in audit logs.
+2. Read `CLAUDE.md`, then the four files listed in Overview, in order.
+3. Identify the Jira ticket key from the trigger context.
+4. Locate the story file under `{{STORY_PATH_PATTERN}}` using the lookup chain from "What's Needed From User":
+    - Try `jira_key:` frontmatter match. If exactly one match, use it.
+    - Else try exact `title:` frontmatter match against the Jira ticket summary. If exactly one match, use it.
+    - Else check the ticket description for an explicit story-file path under `{{STORY_PATH_PATTERN}}...`. Validate the file exists.
+    - If still no match, or multiple ambiguous matches → post an `ambiguity_escalation` comment naming the failure mode and stop.
+5. Read the matched story file in full. Confirm it has the canonical body sections per `methodology/devin-story-format.md` § "Body structure" — `Context`, `Goal`, `Acceptance criteria`, `Files`, `Validation`, `Out of scope`, `Dependencies` are required at scoping time on every story. `Execution recipe` is required on Phase-2 forward stories but may be absent on Phase-1 `manual-gate` backfill stories. `Post-execution notes` is appended by the agent at PR-open time, so may be a stub or absent at scoping. If any required section is missing or empty, raise an `ambiguity_escalation` and stop. Note whether the `Execution recipe` section is present — this drives step 11's behavior.
+6. Write your scoping output into the story file's `## Scoping notes (pre-execution)` section. Commit this as the first commit on the implementation branch with message `docs(stories): scope <story-slug>` (or `[skip ci]` equivalent if your project's CI shape requires). Only then proceed to implementation work. **This step executes during the implementation phase only** — in scoping-only mode, the scoping output is captured in the Jira comment (step 9) but the in-repo commit waits for the implementation session.
+7. Verify the story's acceptance criteria are concrete (per the story-format rules — each AC must be mechanically verifiable). If any AC is vague, flag in the scoping comment and lower confidence.
+8. Verify the story's `Files:` section enumerates actual file paths and the `Validation:` block has runnable commands. If anything is TBD or ambiguous, flag and lower confidence.
+9. Compose the scoping comment using the template below, then **post it to the Jira ticket via the Jira REST API**. The native Devin ↔ Jira integration only posts a stub acknowledgement comment with a session link — it does **not** post substantive content. You must post via REST using OAuth 2.0 client credentials, with secrets configured in Devin's organization settings (`JIRA_OAUTH_CLIENT_ID`, `JIRA_OAUTH_CLIENT_SECRET`).
+
+    **Authentication — OAuth 2.0 client credentials flow:**
+
+    1. **Token exchange.** `POST https://auth.atlassian.com/oauth/token` with JSON body `{"grant_type": "client_credentials", "client_id": "$JIRA_OAUTH_CLIENT_ID", "client_secret": "$JIRA_OAUTH_CLIENT_SECRET"}`. Extract the `access_token` from the response. Tokens are short-lived (~1 hour); obtain a fresh one at the start of each session.
+    2. **Discover cloud ID.** `GET https://api.atlassian.com/oauth/token/accessible-resources` with `Authorization: Bearer <token>`. Find the entry whose `url` matches `https://icpipeline.atlassian.net` and extract its `id` (the cloud ID).
+    3. **All subsequent Jira REST calls** use base URL `https://api.atlassian.com/ex/jira/<CLOUD-ID>` with header `Authorization: Bearer <token>`.
+
+    **Posting the comment:**
+
+    - **Endpoint:** `POST https://api.atlassian.com/ex/jira/<CLOUD-ID>/rest/api/3/issue/<TICKET-KEY>/comment`
+    - **Auth:** `Authorization: Bearer <token>` (from step 1 above)
+    - **Body:** Atlassian Document Format (ADF). For a multi-section comment, build a `doc` node containing `heading`, `paragraph`, and `bulletList` children. ADF spec: https://developer.atlassian.com/cloud/jira/platform/apidocs/#api-rest-api-3-issue-issueIdOrKey-comment-post
+    - **Verify:** GET the same endpoint after posting and confirm the new comment appears in the response.
+    - **If the comment is long or includes structured detail (a full report, large file list, etc.):** post a short ADF-formatted summary comment via the endpoint above, then upload the full report as an attachment via `POST https://api.atlassian.com/ex/jira/<CLOUD-ID>/rest/api/3/issue/<TICKET-KEY>/attachments` with header `X-Atlassian-Token: no-check` and multipart-form field `file=@<path>`. Reference the attachment in the summary comment.
+
+    **Fallback.** If the OAuth token exchange fails (e.g. 401 from `auth.atlassian.com`), the client credentials have been rotated or revoked — raise `ambiguity_escalation` immediately; the human owner must re-provision the OAuth app credentials in the Devin org vault.
+
+    Comment template (rendered into ADF):
+
+    ```
+    Playbook: scrum-router@{{VERSION}} (binding: {{PROJECT_KEY}})
+
+    ### Scoping for <TICKET-KEY> — <story title>
+
+    **Story file:** `{{STORY_PATH_PATTERN}}<slug>.md`
+
+    **My understanding of the goal (1–2 sentences):** …
+
+    **Implementation plan:**
+    1. …
+    2. …
+
+    **Files I expect to touch:**
+    - `path/to/file.ext` — what changes
+    - …
+
+    **Acceptance-criteria verification approach:**
+    - AC 1: <restate> — verified by <method from Validation>
+    - AC 2: <restate> — verified by <method from Validation>
+    - …
+
+    **Confidence:** HIGH | MEDIUM | LOW
+    **Reasoning:** <one line — what would lower this to MEDIUM/LOW>
+
+    **Concerns / ambiguities:** (only include if non-empty)
+    - …
+    ```
+
+    **Confidence calibration anchors.** Pick the level deterministically:
+
+    - **LOW** if *any* of the following are true (a single hard blocker is enough — do not soften LOW into MEDIUM because the rest of the scope is clear):
+        - An unmet `depends_on:` exists in `main` (the referenced story is not yet `Done` in Jira AND/OR its produced artifact is not yet on `main`).
+        - A story-referenced file (`Files:` entry, `Validation:` command, recipe `Procedure` step) does not exist on `main` and is not authored to be created by this story.
+        - An AC bullet is mechanically unverifiable — it cannot be checked by a `pytest`, `mypy`, `ruff`, shell command, or specific file/state assertion.
+        - The `Execution recipe` references a precondition (e.g., "confirm X is merged") that is not currently met.
+        - Two or more independent ambiguities that each would have been a MEDIUM on their own.
+    - **MEDIUM** if the scope is workable but a discrete assumption or judgment call could turn out to be wrong — a vague AC bullet, an architecture choice not pinned by the story, a TBD that the recipe says to resolve mid-flight. The work CAN proceed; the reviewer's job is to read the reasoning and confirm.
+    - **HIGH** if all AC are concrete and mechanically verifiable, all referenced files exist on `main`, all `depends_on:` resolve to `Done` tickets on `main`, and the recipe procedure is mechanical. Reviewer's job is light.
+
+10. **End-of-scoping gates** (evaluate in order; stop at the first that fires):
+
+    a. **If `Confidence` is `LOW`**, fire the `ambiguity_escalation` drift trigger: transition the ticket to `BLOCKED`, reassign to the ticket owner (assignee at time of pickup; fall back to reporter if no assignee), and post a comment naming the trigger and what specifically is blocking (e.g., "ambiguity_escalation: depends_on `simulator-payments-api-happy-pair-scenario` not on main"). Stop the session. *This applies in scoping-only mode too — do not wait for the implementation phase to escalate a scoping-time blocker.*
+
+    b. **If the Jira integration is in scoping-only mode**, stop the session here without further action. The scoping comment is posted; a human will click "Start session" to spawn implementation when ready. **Source of truth for the mode is the webapp's automation-trigger settings (`app.devin.ai > Settings > Integrations > Jira > Automation triggers > scrum-router > Session mode`), not any in-repo document** — check the webapp setting if the mode is ambiguous from context. The consuming project's `{{CONFIG_DOC_PATH}}` § 5 may describe the intended mode but is best-effort, not authoritative.
+
+    c. **If the Jira integration is in direct mode, or a human has started the session from a scoping comment**, proceed to step 11 (implementation).
+
+11. **Implementation phase — runs only in Direct mode, or when a human has started a session from a scoping comment.** Transition the ticket to `In Progress` (transition id `21`) before beginning implementation work. Skip this if the ticket is already in `In Progress` (e.g., from a prior in-flight session). Execute step 6 now (write scoping notes to the story file and commit as the first implementation-branch commit). Then, if the story has an `Execution recipe` section, follow its `Procedure` step-by-step. If not, follow the implementation plan you posted in step 9 (which was inferred from the story's `Acceptance criteria`, `Files`, and `Validation` sections). In both cases, treat `Acceptance criteria`, `Files`, and `Validation` as the contract for what "done" means.
+
+12. While implementing, apply the **universal drift-trigger rules** from runbook § 4.3. All Jira comments named below are posted via the same REST API mechanism documented in step 9 (`POST https://api.atlassian.com/ex/jira/<CLOUD-ID>/rest/api/3/issue/<TICKET-KEY>/comment` with OAuth Bearer auth and ADF body).
+
+    | Drift trigger | Action |
+    |---|---|
+    | `ambiguity_escalation` | Transition the ticket to `BLOCKED`, reassign to the ticket owner (assignee at time of pickup; fall back to reporter if no assignee), post a comment naming the trigger and what's ambiguous. Stop. |
+    | `ac_verification_fail` | Same as above. |
+    | `ci_repeat_fail` (3+ consecutive failures of the same job after good-faith fix attempts) | Same as above. |
+    | `file_scope_drift` (you're modifying files not in the story's `Files:` list) | Post a notify-only comment naming the trigger, list the unplanned files, request confirmation. Continue if the additions are clearly required by the AC. |
+    | `estimate_overrun` at 2× story estimate | Post a notify-only comment with current progress and confidence in remaining work. Continue. |
+    | `estimate_overrun` at 3× story estimate | Transition to `BLOCKED` + reassign + comment naming the trigger. Stop. |
+    | `file_overlap_with_open_story` | Transition the ticket to `BLOCKED`, reassign to the ticket owner, post a comment naming the overlapping story's slug and the files in common. Stop. Do NOT proceed to PR-open; do NOT attempt to merge the inline fix. |
+
+    > **Note:** `Blocked` is reserved for these human-attention cases (`ambiguity_escalation`, `ac_verification_fail`, `ci_repeat_fail`, `estimate_overrun (3×)`, `file_overlap_with_open_story`). Sync-driven dep-resolution writes to `Waiting` (status id `10137`, transition id `5`), not Blocked. The distinction: Waiting auto-resolves when the dep merges; Blocked requires human intervention.
+
+13. **Pre-PR file-overlap check.** Enumerate every file you modified outside the story's declared `Files:` list (every `file_scope_drift` event). For each such file, search `{{STORY_PATH_PATTERN}}*.md` for any story whose `Files:` block includes that file. If a match is found AND that story is not the current ticket AND its post-execution notes show `actual_hours: 0` (not yet executed), fire the `file_overlap_with_open_story` drift trigger from step 12 and stop.
+
+14. Populate the story file's `## Post-execution notes` block with concrete values. The unmodified template default (`surprises: []`, `actual_hours: 0`, all fields at default) is forbidden in a merged PR. If a field has no content, write `# none observed` inline instead of leaving the template default. See step 16 for the required field list and step 17 for the verification gate.
+
+15. Open a PR following the repo's PR template (under `.github/`). Conventional-commit title (`feat:`, `fix:`, `docs:`, etc.). The PR description must follow the project's template (typically the file at `.github/pull_request_template.md`) and link back to the Jira ticket. The Jira integration will automatically post the PR link as a remote link on the ticket; do not duplicate that as a comment. After PR creation succeeds, transition the ticket to `In Review` (transition id `31`). This is explicit and idempotent — do not rely on the Jira ↔ GitHub integration's auto-transition behavior.
+
+    **PR title convention — exactly one Jira ticket key, the primary one.** The consuming project's Jira automation rule for "PR merged → transition to Done" is gated by `{{pullRequest.title}} contains {{issue.key}}`. So **every** Jira ticket whose key appears in the PR title will auto-transition to Done on merge. To make this deterministic:
+    - The PR title MUST contain the current story's Jira ticket key — the **primary** ticket the PR is being opened for. Format: append ` ({{PROJECT_KEY}}-XXX)` to the conventional-commit title. Example: `feat(api): add pair_history to candidate detail ({{PROJECT_KEY}}-115)`.
+    - The PR title MUST NOT contain any **other** Jira ticket key. Even if the implementation work touches files or unblocks behavior tracked by a sibling/prereq ticket, do not put that ticket's key in the title. The branch-name and PR-body references via DVCS integration are sufficient to surface the linkage; the title is reserved for the auto-transition trigger.
+    - If the PR body needs to reference a related/prereq story for context, use the **slug** (e.g., `simulator-poster-previous-pair-tracking`) rather than the Jira key (e.g., `{{PROJECT_KEY}}-116`). The slug carries the same human-readable meaning without arming the auto-transition rule.
+    - Background: 2026-05-24 — a PR for one ticket included a prereq ticket's key in its title/body. The auto-transition rule fired against both tickets on merge, silently closing the prereq before its dedicated implementation PR existed. The condition `pullRequest.title contains issue.key` was added to the automation rule to enforce this convention; the playbook now codifies the author-side contract that matches it.
+
+16. **Populate** the story file's existing `## Post-execution notes` YAML block. The block is **pre-existing** in the template with placeholder values (`actual_hours: 0`, `surprises: []`, etc.); your job is to **overwrite the placeholders with real data**, not to add a new section. Required minimum:
+    - `actual_hours` — real session time
+    - `estimated_hours` — carry through from the story's `estimate:` frontmatter
+    - `estimate_delta_pct` — compute: `(actual − estimated) / estimated × 100`
+    - `drift_events` — list of drift triggers fired during the session, or `[]`
+    - `surprises` — one or more free-text bullets capturing non-obvious findings. **Single most important field for compounding lessons across stories.** If you genuinely encountered nothing surprising, write that explicitly as a bullet rather than leaving `[]`.
+    - `recommended_runbook_updates` — concrete methodology / runbook / story-format edits these findings imply, or `[]` with an explicit comment if you genuinely have none.
+
+17. **Verification gate before PR-open.** Confirm the `## Post-execution notes` block has non-placeholder values:
+    - `actual_hours != 0`
+    - `surprises` either has at least one bullet OR an explicit "nothing notable" comment
+    - `estimate_delta_pct` matches your computed value
+    If any of these still show the template placeholders, **you have not completed step 16** — go back and populate before opening the PR. This is a hard requirement of the methodology (per `methodology/devin-story-format.md` § "Feedback loop and post-execution notes"); reviewers will reject PRs that fail this gate.
+
+## Specifications
+
+- **Scoping phase end-state:** a Jira comment matching the template in step 9 is posted to the ticket. No other writes (no state transition, no PR, no in-repo changes).
+- **Ambiguity / format-violation end-state:** a single Jira comment naming the drift trigger from runbook § 4.3 is posted. No other writes.
+- **Implementation phase end-state:** a PR is open against `main`. PR title and body conform to the templates. The Jira ticket has been transitioned through `In Progress` → `In Review` → (eventually) `Done`. The pre-PR file-overlap check (step 13) has passed. The integration has posted the PR link as a remote link. The story file's `Post-execution notes` section has been populated.
+
+## Advice and Pointers
+
+- **Maturity gradient.** This router is the starting point of a model that matures over time. Two conventions in this router have a gradient:
+    - **Frontmatter `jira_key:`** — not yet in the format spec, not yet on any story. The router uses it as the preferred lookup mechanism so the convention can land later without changing the router.
+    - **In-story `Execution recipe` section** — now in the format spec as Phase-2 mandatory, Phase-1 backfill optional (`methodology/devin-story-format.md` § "Body structure"). Not yet retrofitted to existing stories. The router degrades gracefully to AC + Files + Validation inference during the transition period.
+  As stories migrate to the conventions, this router will be tightened to require them and drop the fallbacks.
+- `CLAUDE.md` is canonical for **locked decisions** (under "Decisions locked"). Anything that contradicts a locked decision is `ambiguity_escalation`, not a license to deviate.
+- Stories under `{{STORY_PATH_PATTERN}}` are already implemented on `main` — if a ticket points at a phase1 story, suspect it's a smoke-test fixture and confirm with the ticket reporter before doing destructive work.
+- Resist producing more than the scoping comment when the integration is in scoping-only mode. The implementation phase only runs when a human has explicitly started the session post-scoping or when the integration is set to direct mode.
+- Confidence calibration: pick the level (HIGH / MEDIUM / LOW) deterministically per step 8's anchors — not by gut feel. The most common miscalibration is softening a real blocker into MEDIUM because "the rest of the scope is clear." It's not — one hard blocker is enough to make confidence LOW, and LOW triggers step 9a's automatic `ambiguity_escalation` (transition to BLOCKED). Hedging into MEDIUM bypasses that gate and leaves the operator to manually catch the blocker; that's a worse outcome than the system was designed to produce.
+- **Jira identity model during the POC.** The native Devin ↔ Jira integration runs as `icpipeline` (admin OAuth). Its stub acknowledgement comment posts under whoever transitioned the ticket. Your substantive REST-API comments (step 8 / step 11) post under the Devin integration service account (`DevinInt`) because the OAuth client credentials belong to that service account. Don't be surprised if author attribution varies between the automated stub and your substantive output — this is expected.
+- **Secret rotation.** `JIRA_OAUTH_CLIENT_ID` and `JIRA_OAUTH_CLIENT_SECRET` are the org-vault secrets for Jira REST access. Unlike API tokens, OAuth client secrets do not auto-expire on a fixed cadence, but they can be rotated or revoked in the Atlassian Developer Console. If the token exchange returns a 401, raise `ambiguity_escalation` immediately rather than retrying; the human owner must re-provision the credentials at https://developer.atlassian.com/console/myapps/ and update the Devin org vault.
+
+## Forbidden Actions
+
+- Do NOT modify the repo's locked decisions (`CLAUDE.md` § "Decisions locked").
+- Do NOT merge to `main`.
+- Do NOT push directly to `main`; always open a PR via the project's branch convention.
+- Do NOT modify tests to make them pass unless the story's `Execution recipe` or `Acceptance criteria` explicitly asks for test changes.
+- Do NOT proceed past scoping if your confidence is LOW. Step 10a is the procedure for this — fire `ambiguity_escalation` (transition to BLOCKED + reassign + comment), don't just stop silently and don't soften the rating into MEDIUM to keep the ticket in `READY FOR AI AGENT`.
+- Do NOT transition the ticket out of `READY FOR AI AGENT` during the scoping phase. State transitions happen during implementation per the runbook's rules, or via the integration on PR open.
+- Do NOT use admin-level Jira APIs beyond posting comments and transitioning the ticket per the rules in step 11. No bulk operations, no workflow edits, no project-config changes.
+- Do NOT author finished business logic, React components, or route handlers without first checking `CLAUDE.md` § "How to work on this project" — Bryan writes implementation himself in VS Code for some surfaces; respect that boundary unless the story's recipe explicitly says otherwise.
+- Do NOT skip the scoping-notes commit. The Jira comment is a duplicate; the story file is the canonical record.
+- Do NOT open a PR while the post-exec block is identical to the template default. The block exists to capture findings the next agent session needs to read; an empty block is silently lying about what happened.
+- Do NOT put more than one Jira ticket key in a PR title. The consuming project's "PR merged → transition to Done" automation is gated by `pullRequest.title contains issue.key`, so any ticket whose key appears in the title auto-transitions on merge. Step 15 codifies the rule; for context on the prior failure mode that prompted it, see the 2026-05-24 episode noted there.