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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.4.1
+Version: 0.4.2
 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.

{methodology_framework-0.4.1 → methodology_framework-0.4.2}/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.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.4.1"
+version = "0.4.2"
 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.2}/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(
@@ -291,9 +300,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 +318,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.2}/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.2}/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 → methodology_framework-0.4.2}/src/methodology_framework/playbooks/scrum-router.body.md

@@ -1,7 +1,8 @@
 ---
-playbook_id: scrum-router
-version: 1.4.0
+playbook_id: {{PLAYBOOK_ID}}
+version: 1.5.0
 changelog:
+  - "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 +32,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 +65,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 +102,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 +145,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.2}/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
 

{methodology_framework-0.4.1 → methodology_framework-0.4.2}/src/methodology_framework/register_playbook_with_devin.py

@@ -12,6 +12,16 @@ body's YAML frontmatter.  It is used as the lookup slug against Devin's API.
 
 Environment:
     DEVIN_API_TOKEN   Devin API key (cog_ prefix). Required.
+    DEVIN_ORG_ID      Devin organization ID (v3 API path is org-scoped). Required.
+
+Devin API v3 (org-scoped, service-user auth):
+  GET    /v3/organizations/{org_id}/playbooks         — list
+  GET    /v3/organizations/{org_id}/playbooks/{id}    — read
+  POST   /v3/organizations/{org_id}/playbooks         — create
+  PUT    /v3/organizations/{org_id}/playbooks/{id}    — update
+
+Migrated from v1 in task #107 — same pattern as the populator's v3 migration
+(#74). v1 was rejecting cog_* service-user tokens with 403 Unauthorized.
 
 Exit codes:
     0  Registration succeeded and smoke-verify passed.
@@ -22,45 +32,60 @@ from __future__ import annotations
 
 import argparse
 import hashlib
-import json
 import os
 import re
 import sys
-import urllib.error
-import urllib.request
 from typing import Any
 
+import requests
+
 MACRO_PATTERN = re.compile(r"^![A-Za-z0-9_]+$")
 
-DEVIN_API_BASE = "https://api.devin.ai/v1"
+DEVIN_API_BASE = "https://api.devin.ai/v3"
 
 
 def _request(
     method: str,
     path: str,
     token: str,
+    org_id: str,
     data: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """Make an authenticated request to the Devin API."""
-    url = f"{DEVIN_API_BASE}{path}"
-    body = json.dumps(data).encode("utf-8") if data else None
-    req = urllib.request.Request(
-        url,
-        data=body,
-        headers={
-            "Authorization": f"Bearer {token}",
-            "Content-Type": "application/json",
-        },
-        method=method,
-    )
+    """Make an authenticated request to the Devin API v3 org-scoped endpoint.
+
+    `path` is the trailing path component (e.g., '/playbooks' or
+    '/playbooks/{id}'); this function prepends the v3 org-scoped prefix
+    `/organizations/{org_id}` automatically.
+
+    Uses `requests` (not urllib) — Devin's v3 API rejects urllib's default
+    User-Agent ('Python-urllib/3.12') with 403 Unauthorized while accepting
+    requests' default ('python-requests/X.Y.Z'). Switched 2026-06-07 after
+    #108 diagnostic isolated the failure mode: curl + requests both return
+    200; urllib returns 403 against identical token/org. Aligns this script
+    with the populator (populate_acus.py) which has always used requests
+    successfully against v3.
+    """
+    url = f"{DEVIN_API_BASE}/organizations/{org_id}{path}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    }
     try:
-        with urllib.request.urlopen(req) as resp:
-            result: dict[str, Any] = json.loads(resp.read().decode("utf-8"))
-            return result
-    except urllib.error.HTTPError as e:
-        error_body = e.read().decode("utf-8", errors="replace")
+        resp = requests.request(method, url, headers=headers, json=data, timeout=30)
+        resp.raise_for_status()
+        result: dict[str, Any] = resp.json()
+        return result
+    except requests.HTTPError as e:
+        error_body = e.response.text if e.response is not None else "<no response body>"
+        status = e.response.status_code if e.response is not None else "???"
+        print(
+            f"ERROR: Devin API {method} {path} returned {status}: {error_body}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except (requests.ConnectionError, requests.Timeout) as e:
         print(
-            f"ERROR: Devin API {method} {path} returned {e.code}: {error_body}",
+            f"ERROR: Devin API connection error for {method} {path}: {e}",
             file=sys.stderr,
         )
         sys.exit(1)
@@ -70,13 +95,17 @@ def sha256hex(text: str) -> str:
     return hashlib.sha256(text.encode("utf-8")).hexdigest()
 
 
-def list_playbooks(token: str) -> list[dict[str, Any]]:
+def list_playbooks(token: str, org_id: str) -> list[dict[str, Any]]:
     """List all playbooks accessible to the token's org."""
-    resp: Any = _request("GET", "/playbooks", token)
-    # v1 returns {"playbooks": [...]} or a bare list
+    resp: Any = _request("GET", "/playbooks", token, org_id)
+    # v3 confirmed 2026-06-07 via #108 diagnostic: returns {"items": [...]}.
+    # Tolerate the legacy "playbooks" / "data" wrappers + bare list for
+    # forward-compat across API shape changes.
     if isinstance(resp, list):
         return resp
-    items: list[dict[str, Any]] = resp.get("playbooks", resp.get("data", []))
+    items: list[dict[str, Any]] = resp.get(
+        "items", resp.get("playbooks", resp.get("data", []))
+    )
     return items
 
 
@@ -102,25 +131,35 @@ def _build_payload(title: str, content: str, macro: str | None = None) -> dict[s
 
 
 def update_playbook(
-    token: str, playbook_id: str, title: str, content: str, macro: str | None = None
+    token: str,
+    org_id: str,
+    playbook_id: str,
+    title: str,
+    content: str,
+    macro: str | None = None,
 ) -> dict[str, Any]:
     """Update a playbook's title and content (full replace)."""
     payload = _build_payload(title, content, macro)
-    return _request("PUT", f"/playbooks/{playbook_id}", token, payload)
+    return _request("PUT", f"/playbooks/{playbook_id}", token, org_id, payload)
 
 
-def get_playbook(token: str, playbook_id: str) -> dict[str, Any]:
+def get_playbook(token: str, org_id: str, playbook_id: str) -> dict[str, Any]:
     """Read back a playbook by ID."""
-    return _request("GET", f"/playbooks/{playbook_id}", token)
+    return _request("GET", f"/playbooks/{playbook_id}", token, org_id)
 
 
 def create_playbook(
-    token: str, slug: str, title: str, content: str, macro: str | None = None
+    token: str,
+    org_id: str,
+    slug: str,
+    title: str,
+    content: str,
+    macro: str | None = None,
 ) -> dict[str, Any]:
     """Create a new playbook with the given slug, title, and content."""
     payload = _build_payload(title, content, macro)
     payload["playbook_id"] = slug
-    return _request("POST", "/playbooks", token, payload)
+    return _request("POST", "/playbooks", token, org_id, payload)
 
 
 def main() -> int:
@@ -168,6 +207,16 @@ def main() -> int:
         print("ERROR: DEVIN_API_TOKEN environment variable is not set.", file=sys.stderr)
         return 1
 
+    org_id = os.environ.get("DEVIN_ORG_ID", "")
+    if not org_id:
+        print(
+            "ERROR: DEVIN_ORG_ID environment variable is required "
+            "(the Devin organization ID; obtain from your service user setup "
+            "or the Devin webapp settings).",
+            file=sys.stderr,
+        )
+        return 1
+
     rendered_path = args.rendered_body
     try:
         rendered_content = open(rendered_path, encoding="utf-8").read()
@@ -184,7 +233,7 @@ def main() -> int:
 
     # Step 1: List playbooks and find the target by name
     print("Listing playbooks...", file=sys.stderr)
-    playbooks = list_playbooks(token)
+    playbooks = list_playbooks(token, org_id)
     names = [p.get("name") or p.get("title") or "?" for p in playbooks]
     print(f"Found {len(playbooks)} playbook(s); available names: {names}", file=sys.stderr)
 
@@ -209,13 +258,13 @@ def main() -> int:
         if args.dry_run:
             print("DRY RUN — would create new playbook.", file=sys.stderr)
             return 0
-        created = create_playbook(token, slug, name, rendered_content, args.macro)
+        created = create_playbook(token, org_id, slug, name, rendered_content, args.macro)
         created_id: str = created.get("playbook_id") or created.get("id") or ""
         print(f"Created playbook: id={created_id}, title={name}", file=sys.stderr)
 
         # Smoke-verify the creation
         print("Smoke-verifying creation...", file=sys.stderr)
-        readback = get_playbook(token, created_id)
+        readback = get_playbook(token, org_id, created_id)
         readback_content = readback.get("content") or readback.get("body") or ""
         readback_sha = sha256hex(readback_content)
         if readback_sha != rendered_sha:
@@ -265,12 +314,12 @@ def main() -> int:
     print(f"Update needed: {'; '.join(reasons)}. Updating...", file=sys.stderr)
 
     # Step 3: Update the playbook
-    update_playbook(token, playbook_id, playbook_title, rendered_content, args.macro)
+    update_playbook(token, org_id, playbook_id, playbook_title, rendered_content, args.macro)
     print("Playbook updated successfully.", file=sys.stderr)
 
     # Step 4: Smoke-verify — read back and compare SHA256
     print("Smoke-verifying registration...", file=sys.stderr)
-    readback = get_playbook(token, playbook_id)
+    readback = get_playbook(token, org_id, playbook_id)
     readback_content = readback.get("content") or readback.get("body") or ""
     readback_sha = sha256hex(readback_content)
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.4.1
+Version: 0.4.2
 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.