methodology-framework 0.4.1__tar.gz → 0.4.3__tar.gz

{methodology_framework-0.4.1/src/methodology_framework.egg-info → methodology_framework-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.4.1
+Version: 0.4.3
 Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
 Author: whiteout59
 License-Expression: Apache-2.0
@@ -22,6 +22,7 @@ Requires-Dist: types-colorama<1,>=0.4; extra == "dev"
 Requires-Dist: vcrpy<9,>=7.0; extra == "dev"
 Dynamic: license-file
 
+[![PyPI version](https://img.shields.io/pypi/v/methodology-framework)](https://pypi.org/project/methodology-framework/)
 # methodology-framework
 
 Portable process tooling for agent-driven delivery -- scripts, playbooks, templates, and specs.
@@ -315,7 +316,7 @@ jobs:
   build-and-register:
     uses: whiteout59/methodology-framework/.github/workflows/build-and-register.yml@v0.1.0
     with:
-      playbook_body_path: "methodology/playbooks/scrum-router.body.md"
+      playbook_body_path: "methodology/playbooks/router-base.body.md"
       bindings_path: "docs/jira-pickup-config.md"
     secrets:
       DEVIN_API_TOKEN: ${{ secrets.DEVIN_API_TOKEN }}

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/README.md

@@ -1,3 +1,4 @@
+[![PyPI version](https://img.shields.io/pypi/v/methodology-framework)](https://pypi.org/project/methodology-framework/)
 # methodology-framework
 
 Portable process tooling for agent-driven delivery -- scripts, playbooks, templates, and specs.
@@ -291,7 +292,7 @@ jobs:
   build-and-register:
     uses: whiteout59/methodology-framework/.github/workflows/build-and-register.yml@v0.1.0
     with:
-      playbook_body_path: "methodology/playbooks/scrum-router.body.md"
+      playbook_body_path: "methodology/playbooks/router-base.body.md"
       bindings_path: "docs/jira-pickup-config.md"
     secrets:
       DEVIN_API_TOKEN: ${{ secrets.DEVIN_API_TOKEN }}

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.4.1"
+version = "0.4.3"
 description = "Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs."
 readme = "README.md"
 license = "Apache-2.0"

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/src/methodology_framework/build_playbook.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Build a concrete, project-bound playbook from the parameterized body + bindings.
 
-Reads the parameterized playbook body from methodology/playbooks/scrum-router.body.md
+Reads the parameterized playbook body from methodology/playbooks/router-base.body.md
 and substitutes {{PLACEHOLDER}} tokens with the project-specific bindings defined in
 docs/jira-pickup-config.md § 5.1 (the playbook_bindings YAML block).
 
@@ -23,7 +23,7 @@ Options:
                     Does not write output.
 
 When --body and --bindings are omitted, the script falls back to the legacy
-hardcoded paths (methodology/playbooks/scrum-router.body.md and
+hardcoded paths (methodology/playbooks/router-base.body.md and
 docs/jira-pickup-config.md relative to the repo root).
 """
 
@@ -35,7 +35,7 @@ import sys
 from pathlib import Path
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-BODY_PATH = REPO_ROOT / "methodology" / "playbooks" / "scrum-router.body.md"
+BODY_PATH = REPO_ROOT / "methodology" / "playbooks" / "router-base.body.md"
 CONFIG_PATH = REPO_ROOT / "docs" / "jira-pickup-config.md"
 
 PLACEHOLDER_RE = re.compile(r"\{\{(\w+)\}\}")

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/src/methodology_framework/jira_discovery.py

@@ -78,7 +78,16 @@ LINK_TYPE_NAME_BLOCKS = "Blocks"
 
 # Canonical issue type names
 ISSUE_TYPE_NAME_STORY = "Story"
-ISSUE_TYPE_NAME_SUBTASK = "Sub-task"
+ISSUE_TYPE_NAME_SUBTASK = "Sub-task"  # canonical (classic Atlassian spelling)
+
+# Modern Atlassian UI defaults to "Subtask" (no hyphen) for newly-provisioned
+# projects. Discovery tolerates either spelling; the matched alias gets
+# canonicalized to ISSUE_TYPE_NAME_SUBTASK in the returned name→ID map so
+# downstream code uses one stable key regardless of which spelling the
+# adopter's Jira tenant uses. Per methodology §3.9 (No Hardcoded Identity
+# Strings) and §3.7 (Portability by Construction) — tenant-spelling
+# variants must not break the framework's portability claim.
+ISSUE_TYPE_NAME_SUBTASK_ALIASES = ("Subtask",)
 
 # Protected/terminal status names
 PROTECTED_STATUS_NAMES = frozenset(
@@ -220,24 +229,14 @@ def discover_statuses(
     return result
 
 
-def discover_transitions(
-    session: Any,
-    base_url: str,
-    project_key: str,
-) -> dict[str, str]:
-    """Discover transition name→ID map.
-
-    Uses GET /rest/api/3/project/{key}/statuses to find a sample issue
-    type, then queries the workflow scheme. Falls back to scanning
-    transitions from each status via the workflow spec.
-
-    For transitions, the approach is: use the statuses endpoint to get
-    status names, then use GET /rest/api/3/status to get transitions.
-    But Jira Cloud doesn't expose transitions without an issue context.
+def _spec_transition_map() -> dict[str, str]:
+    """Return canonical transition name→ID map sourced from workflow.yaml.
 
-    Instead, we create a name→ID map from the workflow spec (which has
-    transition_id values) and verify they're consistent with what's live.
-    The verifier already checked these exist; we trust the spec IDs.
+    Used only for dry-run sync invocations where no Jira credentials are
+    available. Returns the SCRUM-accidental IDs encoded in the spec —
+    these are stable for the SCRUM project but will NOT match a freshly-
+    provisioned team-managed project. Real sync uses :func:`discover_transitions`
+    which queries Jira directly.
     """
     shape = _load_shape(_WORKFLOW_YAML)
     result: dict[str, str] = {}
@@ -247,11 +246,86 @@ def discover_transitions(
             tid = str(t["transition_id"])
             if name not in result:
                 result[name] = tid
+    return result
 
-    if not result:
-        raise _fail("transition", "(any)", project_key)
 
-    return result
+def discover_transitions(
+    session: Any,
+    base_url: str,
+    project_key: str,
+) -> dict[str, str]:
+    """Discover transition name→ID map by querying Jira directly.
+
+    Strategy: find any existing issue in the project via JQL search, then
+    call ``GET /rest/api/3/issue/{key}/transitions`` to read the live
+    transition map for the workflow. The framework's canonical workflow
+    uses global transitions (``isGlobal: true``), so any single issue
+    exposes the complete name→ID map.
+
+    Raises :class:`DiscoveryError` if:
+
+    - The project has no issues yet (operator must create at least one
+      issue before first sync — sync can't probe an empty project's
+      workflow because Jira Cloud only exposes transitions in an issue
+      context).
+    - Any canonical transition name is missing from the live workflow
+      (operator must fix the workflow per ``bootstrap-jira --verify``).
+
+    For SCRUM the discovered IDs match :func:`_spec_transition_map` by
+    historical accident. For freshly-provisioned projects they will not —
+    that's the point of querying instead of trusting the spec.
+    """
+    # Find any existing issue in the project via JQL.
+    resp = session.get(
+        f"{base_url}/rest/api/3/search/jql",
+        params={
+            "jql": f"project={project_key}",
+            "fields": "key",
+            "maxResults": 1,
+        },
+    )
+    resp.raise_for_status()
+    search_data: dict[str, Any] = resp.json()
+    issues = search_data.get("issues") or []
+
+    if not issues:
+        raise DiscoveryError(
+            f"Project {project_key} has no issues yet, so workflow transitions "
+            f"cannot be probed. Jira Cloud only exposes transition IDs in an "
+            f"issue context. Create at least one placeholder issue in "
+            f"{project_key} (any issue type, any state) and re-run sync. "
+            f"That issue is enough — discovery uses it as a probe to read the "
+            f"global transition map for the project's workflow."
+        )
+
+    probe_key: str = issues[0]["key"]
+    logger.info(
+        "Probing transitions on %s (any existing issue exposes the global "
+        "transition map for the project's workflow).",
+        probe_key,
+    )
+
+    resp = session.get(f"{base_url}/rest/api/3/issue/{probe_key}/transitions")
+    resp.raise_for_status()
+    transitions_data: dict[str, Any] = resp.json()
+
+    name_to_id: dict[str, str] = {}
+    for t in transitions_data.get("transitions", []):
+        name_to_id[t["name"]] = str(t["id"])
+
+    # Verify every canonical transition name resolved.
+    canonical = _canonical_transition_names()
+    missing = canonical - set(name_to_id.keys())
+    if missing:
+        raise DiscoveryError(
+            f"Project {project_key}'s workflow is missing required transition(s): "
+            f"{', '.join(sorted(missing))}. "
+            f"Run 'methodology-framework bootstrap-jira --verify "
+            f"--project-key={project_key}' to identify the gaps, then add the "
+            f"missing states/transitions in the Jira workflow editor."
+        )
+
+    return name_to_id
 
 
 def discover_link_types(
@@ -291,9 +365,14 @@ def discover_issue_types(
     is unsafe (it returns types across all projects and dict-overwrite
     picks the wrong project's ID when names collide).
 
-    Returns mapping from issue type name to ID string.
-    Raises DiscoveryError if "Story" or "Sub-task" is missing from the
-    project's issue type list.
+    Returns mapping from issue type name to ID string. The Subtask issue
+    type is tolerated under either the classic spelling ``"Sub-task"`` or
+    the modern Atlassian default ``"Subtask"`` — whichever the project
+    actually has gets canonicalized to ``ISSUE_TYPE_NAME_SUBTASK`` in the
+    returned map so downstream code uses one stable key.
+
+    Raises DiscoveryError if ``"Story"`` is missing OR if neither of the
+    Subtask spellings is present in the project's issue type list.
     """
     resp = session.get(f"{base_url}/rest/api/3/project/{project_key}")
     resp.raise_for_status()
@@ -304,9 +383,27 @@ def discover_issue_types(
     for it in project_issue_types:
         name_to_id[it["name"]] = it["id"]
 
-    for required_name in (ISSUE_TYPE_NAME_STORY, ISSUE_TYPE_NAME_SUBTASK):
-        if required_name not in name_to_id:
-            raise _fail("issue type", required_name, project_key)
+    if ISSUE_TYPE_NAME_STORY not in name_to_id:
+        raise _fail("issue type", ISSUE_TYPE_NAME_STORY, project_key)
+
+    # Subtask tolerance: accept canonical spelling OR any registered alias.
+    # If matched via an alias, add a synthetic entry under the canonical
+    # name so downstream lookups have a stable key.
+    if ISSUE_TYPE_NAME_SUBTASK not in name_to_id:
+        matched_alias = next(
+            (a for a in ISSUE_TYPE_NAME_SUBTASK_ALIASES if a in name_to_id),
+            None,
+        )
+        if matched_alias is None:
+            accepted_aliases = ", ".join(ISSUE_TYPE_NAME_SUBTASK_ALIASES)
+            error_name = f"{ISSUE_TYPE_NAME_SUBTASK} (also accepted: {accepted_aliases})"
+            raise _fail("issue type", error_name, project_key)
+        name_to_id[ISSUE_TYPE_NAME_SUBTASK] = name_to_id[matched_alias]
+        logger.info(
+            "Discovered Subtask issue type under alias '%s'; canonicalized as '%s'",
+            matched_alias,
+            ISSUE_TYPE_NAME_SUBTASK,
+        )
 
     return name_to_id
 

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/src/methodology_framework/playbooks/bindings/meth.yaml

@@ -8,3 +8,4 @@ playbook_bindings:
   REQ_DOC_PATH: "docs/requirements.md"
   CONFIG_DOC_PATH: "docs/jira-pickup-config.md"
   STORY_PATH_PATTERN: "docs/stories/**/*.md"
+  PLAYBOOK_ID: "meth-router"

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/src/methodology_framework/playbooks/bindings/scrum.yaml

@@ -9,3 +9,4 @@ playbook_bindings:
   REQ_DOC_PATH: "docs/use-cases.md"
   CONFIG_DOC_PATH: "docs/jira-pickup-config.md"
   STORY_PATH_PATTERN: "docs/stories/{phase1,phase2}/**/*.md"
+  PLAYBOOK_ID: "scrum-router"

methodology_framework-0.4.1/src/methodology_framework/playbooks/scrum-router.body.md → methodology_framework-0.4.3/src/methodology_framework/playbooks/router-base.body.md

@@ -1,7 +1,9 @@
 ---
-playbook_id: scrum-router
-version: 1.4.0
+playbook_id: {{PLAYBOOK_ID}}
+version: 1.6.0
 changelog:
+  - "1.6.0 (2026-06-07): Renamed body file from `scrum-router.body.md` to `router-base.body.md`. Canonical-template naming should be project-neutral; the SCRUM prefix was a legacy artifact from when the playbook had a single SCRUM binding. The rendered outputs continue to be named per-binding via `{{PLAYBOOK_ID}}` (scrum-router, meth-router, etc.). Code + workflow references updated to the new path. Closes #113. MINOR bump per SemVer (additive: file rename + reference updates, no body content change)."
+  - "1.5.0 (2026-06-07): Parameterize all self-references via new {{PLAYBOOK_ID}} substitution token (previously hardcoded as `scrum-router` in 4 places — frontmatter, the audit-banner step, the comment template, and the webapp settings-path reference). Bindings (scrum.yaml, meth.yaml) now declare PLAYBOOK_ID. Rendered METH playbook now correctly emits `meth-router` in the audit banner instead of `scrum-router` (surfaced by the post-extraction smoke #71 / METH-5). MINOR bump per SemVer (new substitution token added; no breaking change since all bindings updated simultaneously). Closes #92."
   - "1.4.0 (2026-06-02): Added METH as a second bound project alongside SCRUM. Surface expansion only; no body changes. MINOR bump per SemVer (binding surface expands without breaking existing callers)."
   - "1.3.0 (2026-05-29): New convention — cross-repo writeback discipline (story file in repo A, implementation in repo B → two-PR pattern with writeback PR in repo A). New convention — agent populates agent_session_url field in post-execution notes block. New convention — agent_acus field added to post-exec block (default \"pending\"; populated asynchronously by post-merge automation since agents cannot self-report ACU consumption mid-session). MINOR bump per SemVer (three additive new conventions, no breaking changes for single-repo work)."
   - "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)."
@@ -31,6 +33,7 @@ Consuming projects must provide bindings for the following placeholders. The bui
 | `{{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}/` |
+| `{{PLAYBOOK_ID}}` | Slug under which the rendered playbook is registered in Devin's webapp; bound per project so multi-binding deployments don't overwrite each other. Echoed in the audit banner and the comment template. | `scrum-router` (SCRUM) / `meth-router` (METH) |
 | `{{VERSION}}` | Playbook version from frontmatter; injected automatically by the build script. | `1.3.0` |
 
 # {{PROJECT_KEY}} ticket pickup (router)
@@ -63,7 +66,7 @@ The matched story file ideally contains an `Execution recipe` section (now speci
 
 ## 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.
+1. Clone the repo and check out `main`. First line of your substantive output (scoping comment OR implementation log) MUST be: `Playbook: {{PLAYBOOK_ID}}@{{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":
@@ -100,7 +103,7 @@ The matched story file ideally contains an `Execution recipe` section (now speci
     Comment template (rendered into ADF):
 
     ```
-    Playbook: scrum-router@{{VERSION}} (binding: {{PROJECT_KEY}})
+    Playbook: {{PLAYBOOK_ID}}@{{VERSION}} (binding: {{PROJECT_KEY}})
 
     ### Scoping for <TICKET-KEY> — <story title>
 
@@ -143,7 +146,7 @@ The matched story file ideally contains an `Execution recipe` section (now speci
 
     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.
+    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 > {{PLAYBOOK_ID}} > 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 12 (implementation).
 

{methodology_framework-0.4.1 → methodology_framework-0.4.3}/src/methodology_framework/populate_acus.py

@@ -15,10 +15,40 @@ logger = logging.getLogger(__name__)
 _SESSION_URL_RE = re.compile(
     r"agent_session_url:\s*[\"']?https://app\.devin\.ai/sessions/([a-zA-Z0-9_-]+)[\"']?"
 )
-_ACUS_PENDING_RE = re.compile(r"^(\s*)agent_acus:\s*[\"']?pending[\"']?\s*$", re.MULTILINE)
+# The optional `(#.*)?` group absorbs trailing YAML inline comments (e.g.
+# `agent_acus: pending  # filled by populator`). Without this, operator-added
+# annotations on the pending line silently defeat the regex and the populator
+# skips the file — same fail-silent class as the v2/v3 URL bug (task #74).
+# The comment is dropped on replacement; once the value is numeric, the
+# "pending" annotation is no longer truthful.
+_ACUS_PENDING_RE = re.compile(
+    r"^(\s*)agent_acus:\s*[\"']?pending[\"']?\s*(#.*)?$",
+    re.MULTILINE,
+)
 _ACUS_NUMERIC_RE = re.compile(r"^\s*agent_acus:\s*[0-9]", re.MULTILINE)
 _ACUS_PRESENT_RE = re.compile(r"^(\s*)agent_acus:\s*\S", re.MULTILINE)
 _SESSION_URL_LINE_RE = re.compile(r"^(\s*)agent_session_url:\s*\S", re.MULTILINE)
+_ACUS_LINE_RE = re.compile(r"^(\s*)agent_acus:\s*\S.*$", re.MULTILINE)
+
+# agent_session_status: Devin's session lifecycle state at population time
+# (e.g. "exit", "finished", "running"). Vendor-neutral name mirroring the
+# agent_acus / agent_session_url pattern. The field is populator-only: agents
+# don't emit "pending" at PR-open time because they can't predict their own
+# session's terminal status. The populator captures whatever the v3 response's
+# `status` field holds at populate time and writes it alongside agent_acus.
+_STATUS_LINE_RE = re.compile(r"^(\s*)agent_session_status:\s*\S.*$", re.MULTILINE)
+
+
+@dataclass
+class SessionData:
+    """Subset of Devin v3 session response that the populator persists.
+
+    acus is required (the populator's primary purpose); status is informational
+    audit metadata and may be absent from legacy / mid-lifecycle responses.
+    """
+
+    acus: float
+    status: str | None
 
 
 @dataclass
@@ -29,6 +59,8 @@ class PopulateResult:
     session_id: str
     acus: float
     action: str  # "replaced" | "inserted"
+    status: str | None = None  # Devin session status if captured (task #87)
+    status_action: str = ""  # "replaced" | "inserted" | "" (no-op or absent)
 
 
 def extract_session_id(content: str) -> str | None:
@@ -77,19 +109,72 @@ def rewrite_acus(content: str, acus_value: float) -> tuple[str, str]:
     return content, ""
 
 
-def fetch_acus_from_devin(session_id: str, api_token: str, org_id: str) -> float | None:
-    """Fetch ACU consumption from Devin API for a given session ID.
+def rewrite_status(content: str, status_value: str) -> tuple[str, str]:
+    """Insert or replace agent_session_status in the content.
 
-    Returns the ACU value or None on error.
+    Returns (new_content, action) where action is:
+      - "replaced" if an existing agent_session_status line was overwritten
+      - "inserted" if a new line was added after agent_acus / agent_session_url
+      - "" if neither anchor was found (the caller has nowhere to anchor the
+        insert — should not happen in practice because needs_population requires
+        agent_session_url to exist)
+
+    The field is inserted AFTER agent_acus when present (since acus is the
+    primary populator field and status is supplementary metadata); falls back
+    to inserting after agent_session_url for files that have a session URL but
+    no acus line yet.
+    """
+    # Replace path
+    m = _STATUS_LINE_RE.search(content)
+    if m:
+        indent = m.group(1)
+        new_content = _STATUS_LINE_RE.sub(
+            f"{indent}agent_session_status: {status_value}",
+            content,
+            count=1,
+        )
+        return new_content, "replaced"
+
+    # Insert path — anchor preferentially on agent_acus, fall back to session URL
+    anchor = _ACUS_LINE_RE.search(content) or _SESSION_URL_LINE_RE.search(content)
+    if anchor is None:
+        return content, ""
+
+    indent = anchor.group(1)
+    line_end = content.find("\n", anchor.start())
+    insert_line = f"{indent}agent_session_status: {status_value}"
+    if line_end == -1:
+        new_content = content + f"\n{insert_line}"
+    else:
+        insert_pos = line_end + 1
+        new_content = content[:insert_pos] + f"{insert_line}\n" + content[insert_pos:]
+    return new_content, "inserted"
+
+
+def fetch_session_data_from_devin(
+    session_id: str, api_token: str, org_id: str
+) -> SessionData | None:
+    """Fetch ACU consumption and session status from Devin API for a session.
+
+    Returns a SessionData (acus + optional status) or None on error / when no
+    ACU field is present in the response.
 
     Devin API v3 (org-scoped, service-user auth):
       GET /v3/organizations/{org_id}/sessions/{devin_id}
-    Returns JSON with ``acus_consumed`` (float) at the top level.
+    Returns JSON with ``acus_consumed`` (float) and ``status`` (string) at
+    the top level among other fields. The populator persists both: ACU into
+    ``agent_acus`` (the primary audit value) and status into
+    ``agent_session_status`` (informational lifecycle metadata, task #87).
 
     The session ID extracted from story file URLs (e.g.
     ``https://app.devin.ai/sessions/abc123``) is the raw ID without prefix.
     The v3 path parameter expects the ``devin-`` prefix, so this function
     prepends it when constructing the URL.
+
+    Status is best-effort: if the response omits it (legacy sessions, partial
+    payloads), the SessionData carries None and the rewriter skips inserting
+    agent_session_status. acus is required — None response means populator
+    skips the file entirely (preserves existing fail-loud behavior).
     """
     devin_id = f"devin-{session_id}" if not session_id.startswith("devin-") else session_id
     url = f"https://api.devin.ai/v3/organizations/{org_id}/sessions/{devin_id}"
@@ -98,17 +183,6 @@ def fetch_acus_from_devin(session_id: str, api_token: str, org_id: str) -> float
         resp = requests.get(url, headers=headers, timeout=30)
         resp.raise_for_status()
         data = resp.json()
-        # v3 field name is "acus_consumed"; keep legacy fallbacks for robustness.
-        for field in ("acus_consumed", "total_acus", "acus"):
-            acus = data.get(field)
-            if acus is not None:
-                return float(acus)
-        logger.warning(
-            "Session %s: no ACU field found in response keys: %s",
-            session_id,
-            list(data.keys()),
-        )
-        return None
     except requests.HTTPError as exc:
         logger.warning("Devin API error for session %s: %s", session_id, exc)
         return None
@@ -116,6 +190,36 @@ def fetch_acus_from_devin(session_id: str, api_token: str, org_id: str) -> float
         logger.warning("Devin API connection error for session %s: %s", session_id, exc)
         return None
 
+    # v3 field name is "acus_consumed"; keep legacy fallbacks for robustness.
+    acus: float | None = None
+    for field in ("acus_consumed", "total_acus", "acus"):
+        v = data.get(field)
+        if v is not None:
+            acus = float(v)
+            break
+    if acus is None:
+        logger.warning(
+            "Session %s: no ACU field found in response keys: %s",
+            session_id,
+            list(data.keys()),
+        )
+        return None
+
+    status_raw = data.get("status")
+    status = str(status_raw) if status_raw is not None else None
+    return SessionData(acus=acus, status=status)
+
+
+def fetch_acus_from_devin(session_id: str, api_token: str, org_id: str) -> float | None:
+    """Backward-compatible shim returning only the ACU value.
+
+    Preserved so existing callers and contract-level integration tests keep
+    working unchanged. New code SHOULD call ``fetch_session_data_from_devin``
+    directly to also capture the session status (task #87).
+    """
+    data = fetch_session_data_from_devin(session_id, api_token, org_id)
+    return data.acus if data is not None else None
+
 
 def scan_and_populate(
     story_path_pattern: str,
@@ -144,8 +248,8 @@ def scan_and_populate(
             logger.info("Skipping %s: no agent_session_url found", filepath)
             continue
 
-        acus = fetch_acus_from_devin(session_id, api_token, org_id)
-        if acus is None:
+        session_data = fetch_session_data_from_devin(session_id, api_token, org_id)
+        if session_data is None:
             logger.warning(
                 "Skipping %s: could not fetch ACUs for session %s",
                 filepath,
@@ -153,10 +257,17 @@ def scan_and_populate(
             )
             continue
 
-        new_content, action = rewrite_acus(content, acus)
+        new_content, action = rewrite_acus(content, session_data.acus)
         if not action:
             continue
 
+        # Best-effort status capture (task #87). Status is informational; if the
+        # API response omits it (legacy sessions, partial payloads) we still
+        # write the ACU value and skip the status field rather than failing.
+        status_action = ""
+        if session_data.status is not None:
+            new_content, status_action = rewrite_status(new_content, session_data.status)
+
         if not dry_run:
             with open(filepath, "w", encoding="utf-8") as f:
                 f.write(new_content)
@@ -165,11 +276,28 @@ def scan_and_populate(
             PopulateResult(
                 path=filepath,
                 session_id=session_id,
-                acus=acus,
+                acus=session_data.acus,
                 action=action,
+                status=session_data.status,
+                status_action=status_action,
             )
         )
-        logger.info("Updated %s: agent_acus=%s (%s)", filepath, acus, action)
+        if session_data.status is not None:
+            logger.info(
+                "Updated %s: agent_acus=%s (%s), agent_session_status=%s (%s)",
+                filepath,
+                session_data.acus,
+                action,
+                session_data.status,
+                status_action or "no-op",
+            )
+        else:
+            logger.info(
+                "Updated %s: agent_acus=%s (%s); no status field in v3 response",
+                filepath,
+                session_data.acus,
+                action,
+            )
 
     return results
 
@@ -218,7 +346,10 @@ def main() -> int:
 
     print(f"\nPopulated agent_acus for {len(results)} story file(s):")
     for r in results:
-        print(f"  {r.path}: {r.acus} ({r.action})")
+        if r.status is not None:
+            print(f"  {r.path}: acus={r.acus} ({r.action}), status={r.status} ({r.status_action})")
+        else:
+            print(f"  {r.path}: acus={r.acus} ({r.action}), status=<absent>")
 
     return 0