methodology-framework 0.1.0__tar.gz → 0.1.2__tar.gz

{methodology_framework-0.1.0/src/methodology_framework.egg-info → methodology_framework-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.1.0
+Version: 0.1.2
 Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
 Author: whiteout59
 License-Expression: Apache-2.0
@@ -17,6 +17,7 @@ Requires-Dist: ruff==0.15.14; extra == "dev"
 Requires-Dist: mypy<2,>=1.10; extra == "dev"
 Requires-Dist: types-requests<3,>=2.31; extra == "dev"
 Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
+Requires-Dist: vcrpy<9,>=7.0; extra == "dev"
 Dynamic: license-file
 
 # methodology-framework
@@ -50,7 +51,8 @@ instead of manually configuring 30+ admin UI screens.
 - Python 3.12+
 - `pip install methodology-framework` (or `pip install -e .` from source)
 - For `--apply` mode: `JIRA_ADMIN_TOKEN` environment variable set to a Jira
-  admin API token or OAuth Bearer token
+  admin API token, and `JIRA_USER_EMAIL` set to the email of the Atlassian
+  account that owns that token
 
 ### Usage
 
@@ -69,6 +71,7 @@ python -m methodology_framework bootstrap-jira \
 
 # Apply — provision the Jira project via admin API
 export JIRA_ADMIN_TOKEN="<your-token>"
+export JIRA_USER_EMAIL="<your-email>"
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
@@ -97,6 +100,7 @@ python -m methodology_framework bootstrap-jira \
 | Variable | When needed | Description |
 |----------|-------------|-------------|
 | `JIRA_ADMIN_TOKEN` | `--apply` mode | Jira admin API token. **Never** accepted as a CLI flag. |
+| `JIRA_USER_EMAIL` | `--apply` mode | Email of the Atlassian account that owns the API token. Used with the token for HTTP Basic auth. **Never** accepted as a CLI flag. |
 
 ### Shape definitions
 
@@ -225,6 +229,45 @@ to the GitHub repo `whiteout59/methodology-framework`, workflow
 `pypi-release.yml`, environment `pypi` at
 [PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
 
+## Release lifecycle
+
+Version bumps in `pyproject.toml` drive the entire release cycle
+automatically. The operator's only decision surface is PR review.
+
+### Normal flow
+
+1. A PR bumps the `version` field in `pyproject.toml` (e.g. `"0.1.1"` → `"0.1.2"`).
+2. Reviewer approves and merges the PR to `main`.
+3. The `auto-tag.yml` workflow detects the `pyproject.toml` change, extracts the
+   version, validates it as stable SemVer (`^[0-9]+\.[0-9]+\.[0-9]+$`), and
+   creates an annotated tag `v0.1.2`.
+4. The `pypi-release.yml` workflow fires on the new tag and publishes the
+   package to PyPI via OIDC Trusted Publishers.
+
+**Operator surface = PR review only.** No manual `git tag` step required.
+
+### Manual fallback
+
+If `auto-tag.yml` doesn't fire (workflow disabled, branch protection
+blocking the tag push, GitHub Actions outage, etc.), the manual fallback
+still works:
+
+```bash
+git tag -a v0.1.2 -m "Release v0.1.2"
+git push origin v0.1.2
+```
+
+`pypi-release.yml` doesn't care how the tag arrived — it fires on any
+tag matching `v[0-9]+.[0-9]+.[0-9]+`.
+
+### Pre-release versions
+
+The `auto-tag.yml` workflow only tags **stable** SemVer versions. Versions
+containing `-rc`, `-beta`, `-alpha`, `.dev`, or `.pre` suffixes (or any
+string not matching `^[0-9]+\.[0-9]+\.[0-9]+$`) are logged and skipped.
+Pre-release publishing is out of scope; if needed, a separate workflow
+would handle pre-release tag patterns.
+
 ## Cost tracking via `agent_acus`
 
 The methodology's post-execution notes include an `agent_acus` field that
@@ -259,6 +302,42 @@ ruff format --check src/methodology_framework
 mypy --strict src/methodology_framework
 ```
 
+### Shape-def expansion (v0.1.2+)
+
+`workflow.yaml` now includes a `statusCategory` field on each status
+(`TODO`, `IN_PROGRESS`, or `DONE`). The `--apply` handler validates
+this field at load time and exits with a clear error if any status is
+missing it.
+
+`custom_fields.yaml` uses canonical shorthand types (`text`, `string`,
+`multi-value`, `numeric`) that are mapped to fully-qualified Jira
+identifiers at apply time. Fields may also specify a fully-qualified
+type directly (any value containing `:` is passed through unchanged).
+
+### Recording new VCR cassettes
+
+Integration tests under `tests/integration/` replay pre-recorded VCR
+cassettes in CI (no network access required). To record fresh cassettes
+against a real Jira instance:
+
+```bash
+export JIRA_USER_EMAIL="<your-email>"
+export JIRA_ADMIN_TOKEN="<your-api-token>"
+PYTEST_VCR_MODE=record pytest tests/integration/ -v
+```
+
+Cassettes are stored at `tests/fixtures/vcr/*.yaml`. The VCR config in
+`tests/integration/conftest.py` automatically strips `Authorization`
+headers from recorded interactions. **Never commit a cassette with a
+real token in any header.**
+
+After recording, verify no credentials leaked:
+
+```bash
+grep -i 'authorization' tests/fixtures/vcr/*.yaml
+# Expected: no output
+```
+
 ## License
 
 Apache-2.0

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/README.md

@@ -29,7 +29,8 @@ instead of manually configuring 30+ admin UI screens.
 - Python 3.12+
 - `pip install methodology-framework` (or `pip install -e .` from source)
 - For `--apply` mode: `JIRA_ADMIN_TOKEN` environment variable set to a Jira
-  admin API token or OAuth Bearer token
+  admin API token, and `JIRA_USER_EMAIL` set to the email of the Atlassian
+  account that owns that token
 
 ### Usage
 
@@ -48,6 +49,7 @@ python -m methodology_framework bootstrap-jira \
 
 # Apply — provision the Jira project via admin API
 export JIRA_ADMIN_TOKEN="<your-token>"
+export JIRA_USER_EMAIL="<your-email>"
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
@@ -76,6 +78,7 @@ python -m methodology_framework bootstrap-jira \
 | Variable | When needed | Description |
 |----------|-------------|-------------|
 | `JIRA_ADMIN_TOKEN` | `--apply` mode | Jira admin API token. **Never** accepted as a CLI flag. |
+| `JIRA_USER_EMAIL` | `--apply` mode | Email of the Atlassian account that owns the API token. Used with the token for HTTP Basic auth. **Never** accepted as a CLI flag. |
 
 ### Shape definitions
 
@@ -204,6 +207,45 @@ to the GitHub repo `whiteout59/methodology-framework`, workflow
 `pypi-release.yml`, environment `pypi` at
 [PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
 
+## Release lifecycle
+
+Version bumps in `pyproject.toml` drive the entire release cycle
+automatically. The operator's only decision surface is PR review.
+
+### Normal flow
+
+1. A PR bumps the `version` field in `pyproject.toml` (e.g. `"0.1.1"` → `"0.1.2"`).
+2. Reviewer approves and merges the PR to `main`.
+3. The `auto-tag.yml` workflow detects the `pyproject.toml` change, extracts the
+   version, validates it as stable SemVer (`^[0-9]+\.[0-9]+\.[0-9]+$`), and
+   creates an annotated tag `v0.1.2`.
+4. The `pypi-release.yml` workflow fires on the new tag and publishes the
+   package to PyPI via OIDC Trusted Publishers.
+
+**Operator surface = PR review only.** No manual `git tag` step required.
+
+### Manual fallback
+
+If `auto-tag.yml` doesn't fire (workflow disabled, branch protection
+blocking the tag push, GitHub Actions outage, etc.), the manual fallback
+still works:
+
+```bash
+git tag -a v0.1.2 -m "Release v0.1.2"
+git push origin v0.1.2
+```
+
+`pypi-release.yml` doesn't care how the tag arrived — it fires on any
+tag matching `v[0-9]+.[0-9]+.[0-9]+`.
+
+### Pre-release versions
+
+The `auto-tag.yml` workflow only tags **stable** SemVer versions. Versions
+containing `-rc`, `-beta`, `-alpha`, `.dev`, or `.pre` suffixes (or any
+string not matching `^[0-9]+\.[0-9]+\.[0-9]+$`) are logged and skipped.
+Pre-release publishing is out of scope; if needed, a separate workflow
+would handle pre-release tag patterns.
+
 ## Cost tracking via `agent_acus`
 
 The methodology's post-execution notes include an `agent_acus` field that
@@ -238,6 +280,42 @@ ruff format --check src/methodology_framework
 mypy --strict src/methodology_framework
 ```
 
+### Shape-def expansion (v0.1.2+)
+
+`workflow.yaml` now includes a `statusCategory` field on each status
+(`TODO`, `IN_PROGRESS`, or `DONE`). The `--apply` handler validates
+this field at load time and exits with a clear error if any status is
+missing it.
+
+`custom_fields.yaml` uses canonical shorthand types (`text`, `string`,
+`multi-value`, `numeric`) that are mapped to fully-qualified Jira
+identifiers at apply time. Fields may also specify a fully-qualified
+type directly (any value containing `:` is passed through unchanged).
+
+### Recording new VCR cassettes
+
+Integration tests under `tests/integration/` replay pre-recorded VCR
+cassettes in CI (no network access required). To record fresh cassettes
+against a real Jira instance:
+
+```bash
+export JIRA_USER_EMAIL="<your-email>"
+export JIRA_ADMIN_TOKEN="<your-api-token>"
+PYTEST_VCR_MODE=record pytest tests/integration/ -v
+```
+
+Cassettes are stored at `tests/fixtures/vcr/*.yaml`. The VCR config in
+`tests/integration/conftest.py` automatically strips `Authorization`
+headers from recorded interactions. **Never commit a cassette with a
+real token in any header.**
+
+After recording, verify no credentials leaked:
+
+```bash
+grep -i 'authorization' tests/fixtures/vcr/*.yaml
+# Expected: no output
+```
+
 ## License
 
 Apache-2.0

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.1.0"
+version = "0.1.2"
 description = "Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs."
 readme = "README.md"
 license = "Apache-2.0"
@@ -26,6 +26,7 @@ dev = [
     "mypy>=1.10,<2",
     "types-requests>=2.31,<3",
     "types-PyYAML>=6.0,<7",
+    "vcrpy>=7.0,<9",
 ]
 
 [tool.setuptools.packages.find]

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/src/methodology_framework/bootstrap_jira.py

@@ -12,17 +12,71 @@ from __future__ import annotations
 
 import argparse
 import importlib.resources
+import json
 import logging
 import os
 import re
 import sys
+from pathlib import Path
 from typing import Any
 
 import requests
 import yaml
+from requests.auth import HTTPBasicAuth
 
 logger = logging.getLogger(__name__)
 
+# ---------------------------------------------------------------------------
+# Custom-field type mapping: shorthand → Jira fully-qualified identifiers
+# ---------------------------------------------------------------------------
+
+_VALID_STATUS_CATEGORIES = frozenset({"TODO", "IN_PROGRESS", "DONE"})
+
+_FIELD_TYPE_MAP: dict[str, tuple[str, str]] = {
+    "text": (
+        "com.atlassian.jira.plugin.system.customfieldtypes:textfield",
+        "com.atlassian.jira.plugin.system.customfieldtypes:textsearcher",
+    ),
+    "string": (
+        "com.atlassian.jira.plugin.system.customfieldtypes:textfield",
+        "com.atlassian.jira.plugin.system.customfieldtypes:textsearcher",
+    ),
+    "multi-value": (
+        "com.atlassian.jira.plugin.system.customfieldtypes:labels",
+        "com.atlassian.jira.plugin.system.customfieldtypes:labelsearcher",
+    ),
+    "numeric": (
+        "com.atlassian.jira.plugin.system.customfieldtypes:float",
+        "com.atlassian.jira.plugin.system.customfieldtypes:exactnumber",
+    ),
+}
+
+
+def resolve_field_type(raw_type: str | None) -> tuple[str, str | None]:
+    """Map a shorthand type to (FQ type, FQ searcherKey).
+
+    Returns (fq_type, searcher_key).  If *raw_type* is already a FQ
+    identifier (contains ``:``) or is ``None``, it is passed through unchanged
+    with ``searcher_key=None``.
+
+    Raises ``SystemExit`` for unrecognized shorthands.
+    """
+    if raw_type is None:
+        return ("", None)
+    if ":" in raw_type:
+        return (raw_type, None)
+    if raw_type in _FIELD_TYPE_MAP:
+        return _FIELD_TYPE_MAP[raw_type]
+    supported = ", ".join(sorted(_FIELD_TYPE_MAP.keys()))
+    print(
+        f"ERROR: Unrecognized custom-field type '{raw_type}'. "
+        f"Supported shorthand types: {supported}. "
+        "Use a fully-qualified Jira type identifier (containing ':') for other types.",
+        file=sys.stderr,
+    )
+    raise SystemExit(1)
+
+
 # ---------------------------------------------------------------------------
 # Shape-def loading
 # ---------------------------------------------------------------------------
@@ -84,22 +138,56 @@ def substitute_project_key(
 class JiraAdminClient:
     """Minimal Jira Cloud admin client for bootstrap operations."""
 
-    def __init__(self, jira_host: str, token: str) -> None:
+    def __init__(self, jira_host: str, token: str, email: str) -> None:
         self._base = f"https://{jira_host}/rest/api/3"
         self._session = requests.Session()
+        # Jira Cloud user API tokens require HTTP Basic auth: base64(email:token)
+        self._session.auth = HTTPBasicAuth(email, token)
         self._session.headers.update(
             {
-                "Authorization": f"Bearer {token}",
                 "Content-Type": "application/json",
                 "Accept": "application/json",
             }
         )
+        self._project_id_cache: dict[str, str] = {}
+
+    # -- project ID resolution -----------------------------------------------
+
+    def _resolve_project_id(self, project_key: str) -> str:
+        """GET /rest/api/3/project/{key} and return the numeric project ID.
+
+        Result is cached on the instance for the duration of the session.
+        On 404, prints a clear error and exits with code 1.
+        """
+        cached = self._project_id_cache.get(project_key)
+        if cached is not None:
+            return cached
+        resp = self._session.get(f"{self._base}/project/{project_key}")
+        if resp.status_code == 404:
+            print(
+                f"ERROR: Project '{project_key}' not found at "
+                f"{self._base.split('/rest')[0]}. "
+                "Confirm project key and JIRA_USER_EMAIL has admin scope.",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+        resp.raise_for_status()
+        project_id: str = str(resp.json()["id"])
+        self._project_id_cache[project_key] = project_id
+        return project_id
 
     # -- connectivity check --------------------------------------------------
 
     def check_connectivity(self) -> None:
         """Validate reachability via GET /rest/api/3/myself."""
         resp = self._session.get(f"{self._base}/myself")
+        if resp.status_code in (401, 403):
+            raise requests.HTTPError(
+                f"{resp.status_code} {resp.reason} for url: {resp.url} "
+                "(check that JIRA_USER_EMAIL is the email that owns "
+                "JIRA_ADMIN_TOKEN and that the account has Jira admin permissions)",
+                response=resp,
+            )
         resp.raise_for_status()
         logger.info("Connected as %s", resp.json().get("displayName", "unknown"))
 
@@ -118,7 +206,13 @@ class JiraAdminClient:
         return statuses
 
     def create_status(self, spec: dict[str, Any]) -> None:
-        """Create a workflow status from *spec*."""
+        """Create workflow statuses from *spec*.
+
+        *spec* must be the full envelope shape::
+
+            {"scope": {"type": "PROJECT", "project": {"id": "<numeric>"}},
+             "statuses": [{"name": ..., "statusCategory": ..., "description": ...}]}
+        """
         resp = self._session.post(f"{self._base}/statuses", json=spec)
         resp.raise_for_status()
 
@@ -132,7 +226,11 @@ class JiraAdminClient:
         return result
 
     def create_custom_field(self, spec: dict[str, Any]) -> dict[str, Any]:
-        """Create a custom field from *spec*."""
+        """Create a custom field from *spec*.
+
+        *spec* must contain ``name``, ``description``, ``type`` (FQ Jira type
+        identifier), and optionally ``searcherKey`` (FQ searcher identifier).
+        """
         resp = self._session.post(f"{self._base}/field", json=spec)
         resp.raise_for_status()
         result: dict[str, Any] = resp.json()
@@ -154,11 +252,25 @@ class JiraAdminClient:
         return result
 
     def create_automation_rule(self, project_key: str, spec: dict[str, Any]) -> dict[str, Any]:
-        """Create an automation rule from *spec*."""
+        """Attempt to create an automation rule from *spec*.
+
+        Jira Cloud's automation API is not publicly available on Free/Standard
+        tiers and requires scopes beyond the standard OAuth grants.  If the
+        endpoint returns 401/403/404, returns an empty dict and logs a warning
+        so the caller can fall back to the graceful-degradation path.
+        """
         resp = self._session.post(
             f"{self._base}/project/{project_key}/automation/rule",
             json=spec,
         )
+        if resp.status_code in (401, 403, 404):
+            logger.warning(
+                "Automation rule API returned %d — rule '%s' cannot be created "
+                "via API. Use the graceful-degradation output instead.",
+                resp.status_code,
+                spec.get("name", "?"),
+            )
+            return {}
         resp.raise_for_status()
         result: dict[str, Any] = resp.json()
         return result
@@ -240,10 +352,11 @@ def _handle_apply(
     project_key: str,
     jira_host: str,
     token: str,
+    email: str,
     force: bool = False,
 ) -> int:
     """Apply the shape definitions to a Jira project via the admin API."""
-    client = JiraAdminClient(jira_host, token)
+    client = JiraAdminClient(jira_host, token, email)
 
     logger.info("Validating connectivity to %s ...", jira_host)
     try:
@@ -252,12 +365,38 @@ def _handle_apply(
         logger.error("Connectivity check failed: %s", exc)
         return 1
 
+    # -- resolve project ID --------------------------------------------------
+    logger.info("Resolving project ID for '%s' ...", project_key)
+    project_id = client._resolve_project_id(project_key)
+    logger.info("  Project ID: %s", project_id)
+
     # -- statuses -----------------------------------------------------------
     logger.info("Checking workflow statuses ...")
     existing_statuses = client.get_statuses(project_key)
     existing_names = {s.get("name", "").lower() for s in existing_statuses}
     desired = shapes.get("workflow", {}).get("statuses", [])
-    statuses_created = 0
+
+    # Validate statusCategory on every status in the shape def
+    for status_spec in desired:
+        cat = status_spec.get("statusCategory")
+        if cat is None:
+            print(
+                f"ERROR: Status '{status_spec['name']}' in workflow.yaml is missing "
+                f"'statusCategory'. Add one of: {', '.join(sorted(_VALID_STATUS_CATEGORIES))}. "
+                "This field is required since v0.1.2.",
+                file=sys.stderr,
+            )
+            return 1
+        if cat not in _VALID_STATUS_CATEGORIES:
+            print(
+                f"ERROR: Status '{status_spec['name']}' has statusCategory '{cat}'. "
+                f"Valid values: {', '.join(sorted(_VALID_STATUS_CATEGORIES))}.",
+                file=sys.stderr,
+            )
+            return 1
+
+    # Collect statuses that need creation
+    to_create: list[dict[str, Any]] = []
     for status_spec in desired:
         if status_spec["name"].lower() in existing_names:
             logger.info("  Status '%s' already exists — skipping.", status_spec["name"])
@@ -267,11 +406,24 @@ def _handle_apply(
                 if answer != "y":
                     logger.info("  Skipped '%s'.", status_spec["name"])
                     continue
-            logger.info("  Creating status '%s' ...", status_spec["name"])
-            client.create_status(
-                {"name": status_spec["name"], "description": status_spec.get("description", "")}
+            to_create.append(
+                {
+                    "name": status_spec["name"],
+                    "statusCategory": status_spec["statusCategory"],
+                    "description": status_spec.get("description", ""),
+                }
             )
-            statuses_created += 1
+
+    statuses_created = 0
+    if to_create:
+        # Batch all statuses into one POST per the Jira /statuses API
+        envelope: dict[str, Any] = {
+            "scope": {"type": "PROJECT", "project": {"id": project_id}},
+            "statuses": to_create,
+        }
+        logger.info("  Creating %d status(es) in one batch ...", len(to_create))
+        client.create_status(envelope)
+        statuses_created = len(to_create)
 
     # -- custom fields ------------------------------------------------------
     logger.info("Checking custom fields ...")
@@ -290,14 +442,19 @@ def _handle_apply(
                 if answer != "y":
                     logger.info("  Skipped '%s'.", field_spec["name"])
                     continue
-            logger.info("  Creating field '%s' ...", field_spec["name"])
-            client.create_custom_field(
-                {
-                    "name": field_spec["name"],
-                    "type": field_spec.get("type", "string"),
-                    "description": field_spec.get("description", ""),
-                }
-            )
+            raw_type = field_spec.get("type")
+            fq_type, searcher_key = resolve_field_type(raw_type)
+            # If the shape def already specifies a searcherKey, prefer it
+            searcher_key = field_spec.get("searcherKey", searcher_key)
+            payload: dict[str, str] = {
+                "name": field_spec["name"],
+                "type": fq_type,
+                "description": field_spec.get("description", ""),
+            }
+            if searcher_key is not None:
+                payload["searcherKey"] = searcher_key
+            logger.info("  Creating field '%s' (type: %s) ...", field_spec["name"], fq_type)
+            client.create_custom_field(payload)
             fields_created += 1
 
     # -- automation rules ---------------------------------------------------
@@ -306,6 +463,7 @@ def _handle_apply(
     existing_rule_names = {r.get("name", "").lower() for r in existing_rules}
     desired_rules = shapes.get("automation_rules", {}).get("automation_rules", [])
     rules_created = 0
+    rules_degraded: list[dict[str, Any]] = []
     for rule_spec in desired_rules:
         if rule_spec["name"].lower() in existing_rule_names:
             logger.info("  Rule '%s' already exists — skipping.", rule_spec["name"])
@@ -320,8 +478,30 @@ def _handle_apply(
                     logger.info("  Skipped '%s'.", rule_spec["name"])
                     continue
             logger.info("  Creating rule '%s' ...", rule_spec["name"])
-            client.create_automation_rule(project_key, rule_spec)
-            rules_created += 1
+            result = client.create_automation_rule(project_key, rule_spec)
+            if result:
+                rules_created += 1
+            else:
+                rules_degraded.append(rule_spec)
+
+    # Graceful degradation: emit rules that couldn't be created via API
+    if rules_degraded:
+        degradation_path = Path.cwd() / "jira-automation-rules-to-create-manually.json"
+        degradation_path.write_text(
+            json.dumps(rules_degraded, indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        logger.warning(
+            "NOTE: %d automation rule(s) could not be created via API "
+            "(Jira Cloud automation API not available at this tier). "
+            "Rule definitions written to %s for manual creation via the Jira UI.",
+            len(rules_degraded),
+            degradation_path,
+        )
+        print("\n--- Automation rules requiring manual creation ---")
+        for rule in rules_degraded:
+            print(f"  • {rule['name']}: {rule.get('description', '')[:120]}")
+        print(f"\nFull definitions: {degradation_path}\n")
 
     logger.info(
         "Apply complete: %d statuses, %d fields, %d rules created.",
@@ -329,7 +509,9 @@ def _handle_apply(
         fields_created,
         rules_created,
     )
-    if statuses_created == 0 and fields_created == 0 and rules_created == 0:
+    if rules_degraded:
+        logger.info("%d rule(s) written to file for manual creation.", len(rules_degraded))
+    if statuses_created == 0 and fields_created == 0 and rules_created == 0 and not rules_degraded:
         logger.info("Already up to date.")
     return 0
 
@@ -407,7 +589,15 @@ def main(argv: list[str] | None = None) -> int:
         if not token:
             logger.error(
                 "JIRA_ADMIN_TOKEN env var required for --apply mode. "
-                "Set it to a Jira admin API token or OAuth Bearer token."
+                "Set it to a Jira admin API token."
+            )
+            return 1
+        email = os.environ.get("JIRA_USER_EMAIL", "")
+        if not email:
+            print(
+                "ERROR: JIRA_USER_EMAIL env var is required for --apply mode. "
+                "Set it to the email of the Atlassian account that owns the API token.",
+                file=sys.stderr,
             )
             return 1
         return _handle_apply(
@@ -415,6 +605,7 @@ def main(argv: list[str] | None = None) -> int:
             project_key=args.project_key,
             jira_host=args.jira_host,
             token=token,
+            email=email,
             force=args.force,
         )
     elif args.export is not None:

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/src/methodology_framework/jira_shapes/custom_fields.yaml

@@ -11,7 +11,8 @@ schema_version: "1.0"
 custom_fields:
   - name: "Story File"
     key: "story_file"
-    type: "url"
+    type: "com.atlassian.jira.plugin.system.customfieldtypes:url"
+    searcherKey: "com.atlassian.jira.plugin.system.customfieldtypes:exacttextsearcher"
     description: >-
       URL to the canonical story file in the repo. Set by the outbound sync
       workflow on story creation. Format:
@@ -22,7 +23,7 @@ custom_fields:
 
   - name: "Requirement IDs"
     key: "requirement_ids"
-    type: "labels"
+    type: "multi-value"
     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,
@@ -33,7 +34,7 @@ custom_fields:
 
   - name: "Agent Estimate"
     key: "agent_estimate"
-    type: "number"
+    type: "numeric"
     description: >-
       Estimated agent-hours for the story. Populated from the story frontmatter
       estimate field (converted to numeric hours). Used for capacity planning

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/src/methodology_framework/jira_shapes/workflow.yaml

@@ -14,6 +14,7 @@ statuses:
       Backlog state. Stories with manual-gate label sit here.
       Initial state for stories that are not yet ready for agent pickup.
     status_id: 10000
+    statusCategory: "TODO"
     transitions:
       - name: "Ready for AI agent"
         transition_id: 2
@@ -29,6 +30,7 @@ statuses:
       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
+    statusCategory: "TODO"
     transitions:
       - name: "In Progress"
         transition_id: 21
@@ -48,6 +50,7 @@ statuses:
       Agent is actively implementing. Read-only for humans during this state.
       Agent transitions here on session start.
     status_id: 10001
+    statusCategory: "IN_PROGRESS"
     transitions:
       - name: "In Review"
         transition_id: 31
@@ -67,6 +70,7 @@ statuses:
       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
+    statusCategory: "IN_PROGRESS"
     transitions:
       - name: "Done"
         transition_id: 41
@@ -86,6 +90,7 @@ statuses:
       Dependency not yet resolved. Auto-resolves when blocking issues reach Done.
       Sync-driven; distinct from Blocked (which requires human intervention).
     status_id: 10137
+    statusCategory: "IN_PROGRESS"
     transitions:
       - name: "Ready for AI agent"
         transition_id: 2
@@ -106,6 +111,7 @@ statuses:
       ambiguity_escalation, ac_verification_fail, ci_repeat_fail,
       estimate_overrun (3x), file_overlap_with_open_story.
     status_id: 10103
+    statusCategory: "IN_PROGRESS"
     transitions:
       - name: "Ready for AI agent"
         transition_id: 2
@@ -125,6 +131,7 @@ statuses:
       Terminal success state. Reached via Jira automation rule on PR merge
       (gated by pullRequest.title contains issue.key).
     status_id: 10003
+    statusCategory: "DONE"
     transitions: []
 
   - name: "Won't do"
@@ -132,4 +139,5 @@ statuses:
       Terminal rejected state. Reached via sync workflow on story file rename
       (prefixed with underscore) or by operator decision.
     status_id: 10104
+    statusCategory: "DONE"
     transitions: []

{methodology_framework-0.1.0 → methodology_framework-0.1.2/src/methodology_framework.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.1.0
+Version: 0.1.2
 Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
 Author: whiteout59
 License-Expression: Apache-2.0
@@ -17,6 +17,7 @@ Requires-Dist: ruff==0.15.14; extra == "dev"
 Requires-Dist: mypy<2,>=1.10; extra == "dev"
 Requires-Dist: types-requests<3,>=2.31; extra == "dev"
 Requires-Dist: types-PyYAML<7,>=6.0; extra == "dev"
+Requires-Dist: vcrpy<9,>=7.0; extra == "dev"
 Dynamic: license-file
 
 # methodology-framework
@@ -50,7 +51,8 @@ instead of manually configuring 30+ admin UI screens.
 - Python 3.12+
 - `pip install methodology-framework` (or `pip install -e .` from source)
 - For `--apply` mode: `JIRA_ADMIN_TOKEN` environment variable set to a Jira
-  admin API token or OAuth Bearer token
+  admin API token, and `JIRA_USER_EMAIL` set to the email of the Atlassian
+  account that owns that token
 
 ### Usage
 
@@ -69,6 +71,7 @@ python -m methodology_framework bootstrap-jira \
 
 # Apply — provision the Jira project via admin API
 export JIRA_ADMIN_TOKEN="<your-token>"
+export JIRA_USER_EMAIL="<your-email>"
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
@@ -97,6 +100,7 @@ python -m methodology_framework bootstrap-jira \
 | Variable | When needed | Description |
 |----------|-------------|-------------|
 | `JIRA_ADMIN_TOKEN` | `--apply` mode | Jira admin API token. **Never** accepted as a CLI flag. |
+| `JIRA_USER_EMAIL` | `--apply` mode | Email of the Atlassian account that owns the API token. Used with the token for HTTP Basic auth. **Never** accepted as a CLI flag. |
 
 ### Shape definitions
 
@@ -225,6 +229,45 @@ to the GitHub repo `whiteout59/methodology-framework`, workflow
 `pypi-release.yml`, environment `pypi` at
 [PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
 
+## Release lifecycle
+
+Version bumps in `pyproject.toml` drive the entire release cycle
+automatically. The operator's only decision surface is PR review.
+
+### Normal flow
+
+1. A PR bumps the `version` field in `pyproject.toml` (e.g. `"0.1.1"` → `"0.1.2"`).
+2. Reviewer approves and merges the PR to `main`.
+3. The `auto-tag.yml` workflow detects the `pyproject.toml` change, extracts the
+   version, validates it as stable SemVer (`^[0-9]+\.[0-9]+\.[0-9]+$`), and
+   creates an annotated tag `v0.1.2`.
+4. The `pypi-release.yml` workflow fires on the new tag and publishes the
+   package to PyPI via OIDC Trusted Publishers.
+
+**Operator surface = PR review only.** No manual `git tag` step required.
+
+### Manual fallback
+
+If `auto-tag.yml` doesn't fire (workflow disabled, branch protection
+blocking the tag push, GitHub Actions outage, etc.), the manual fallback
+still works:
+
+```bash
+git tag -a v0.1.2 -m "Release v0.1.2"
+git push origin v0.1.2
+```
+
+`pypi-release.yml` doesn't care how the tag arrived — it fires on any
+tag matching `v[0-9]+.[0-9]+.[0-9]+`.
+
+### Pre-release versions
+
+The `auto-tag.yml` workflow only tags **stable** SemVer versions. Versions
+containing `-rc`, `-beta`, `-alpha`, `.dev`, or `.pre` suffixes (or any
+string not matching `^[0-9]+\.[0-9]+\.[0-9]+$`) are logged and skipped.
+Pre-release publishing is out of scope; if needed, a separate workflow
+would handle pre-release tag patterns.
+
 ## Cost tracking via `agent_acus`
 
 The methodology's post-execution notes include an `agent_acus` field that
@@ -259,6 +302,42 @@ ruff format --check src/methodology_framework
 mypy --strict src/methodology_framework
 ```
 
+### Shape-def expansion (v0.1.2+)
+
+`workflow.yaml` now includes a `statusCategory` field on each status
+(`TODO`, `IN_PROGRESS`, or `DONE`). The `--apply` handler validates
+this field at load time and exits with a clear error if any status is
+missing it.
+
+`custom_fields.yaml` uses canonical shorthand types (`text`, `string`,
+`multi-value`, `numeric`) that are mapped to fully-qualified Jira
+identifiers at apply time. Fields may also specify a fully-qualified
+type directly (any value containing `:` is passed through unchanged).
+
+### Recording new VCR cassettes
+
+Integration tests under `tests/integration/` replay pre-recorded VCR
+cassettes in CI (no network access required). To record fresh cassettes
+against a real Jira instance:
+
+```bash
+export JIRA_USER_EMAIL="<your-email>"
+export JIRA_ADMIN_TOKEN="<your-api-token>"
+PYTEST_VCR_MODE=record pytest tests/integration/ -v
+```
+
+Cassettes are stored at `tests/fixtures/vcr/*.yaml`. The VCR config in
+`tests/integration/conftest.py` automatically strips `Authorization`
+headers from recorded interactions. **Never commit a cassette with a
+real token in any header.**
+
+After recording, verify no credentials leaked:
+
+```bash
+grep -i 'authorization' tests/fixtures/vcr/*.yaml
+# Expected: no output
+```
+
 ## License
 
 Apache-2.0

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/src/methodology_framework.egg-info/requires.txt

@@ -9,3 +9,4 @@ ruff==0.15.14
 mypy<2,>=1.10
 types-requests<3,>=2.31
 types-PyYAML<7,>=6.0
+vcrpy<9,>=7.0

{methodology_framework-0.1.0 → methodology_framework-0.1.2}/tests/test_bootstrap_jira.py

@@ -11,10 +11,12 @@ import pytest
 import yaml
 
 from methodology_framework.bootstrap_jira import (
+    _VALID_STATUS_CATEGORIES,
     JiraAdminClient,
     build_parser,
     load_all_shapes,
     main,
+    resolve_field_type,
     substitute_project_key,
 )
 
@@ -50,6 +52,11 @@ class TestWorkflowYamlLoads:
             assert "name" in status
             assert "description" in status
             assert "status_id" in status
+            assert "statusCategory" in status, f"Status '{status['name']}' missing statusCategory"
+            assert status["statusCategory"] in _VALID_STATUS_CATEGORIES, (
+                f"Status '{status['name']}' has invalid statusCategory "
+                f"'{status['statusCategory']}'"
+            )
             assert "transitions" in status
             for t in status["transitions"]:
                 assert "name" in t
@@ -77,6 +84,9 @@ class TestCustomFieldsYamlLoads:
             assert "type" in field
             assert "description" in field
             assert "required_at_create" in field
+            # Every type must be resolvable (shorthand or FQ)
+            fq_type, _ = resolve_field_type(field["type"])
+            assert fq_type, f"Field '{field['name']}' has unresolvable type"
 
 
 class TestAutomationRulesYamlLoads:
@@ -144,6 +154,23 @@ class TestCliTokenRequiredForApply:
     def test_cli_token_required_for_apply(self) -> None:
         env = os.environ.copy()
         env.pop("JIRA_ADMIN_TOKEN", None)
+        env.pop("JIRA_USER_EMAIL", None)
+        with patch.dict(os.environ, env, clear=True):
+            result = main(
+                [
+                    "--project-key=TESTPROJ",
+                    "--jira-host=test.atlassian.net",
+                    "--apply",
+                ]
+            )
+        assert result == 1
+
+
+class TestApplyRequiresJiraUserEmail:
+    """test_apply_requires_jira_user_email — --apply without JIRA_USER_EMAIL exits 1."""
+
+    def test_apply_requires_jira_user_email(self, capsys: pytest.CaptureFixture[str]) -> None:
+        env = {"JIRA_ADMIN_TOKEN": "fake-token"}
         with patch.dict(os.environ, env, clear=True):
             result = main(
                 [
@@ -153,6 +180,9 @@ class TestCliTokenRequiredForApply:
                 ]
             )
         assert result == 1
+        captured = capsys.readouterr()
+        assert "JIRA_USER_EMAIL" in captured.err
+        assert "--apply mode" in captured.err
 
 
 # ---------------------------------------------------------------------------
@@ -178,6 +208,45 @@ class TestDryRunNoApiCalls:
         assert "dry-run" in captured.out.lower()
 
 
+class TestDryRunDoesNotRequireEmail:
+    """test_dry_run_does_not_require_email — --dry-run without JIRA_USER_EMAIL succeeds."""
+
+    def test_dry_run_does_not_require_email(self) -> None:
+        env = os.environ.copy()
+        env.pop("JIRA_USER_EMAIL", None)
+        env.pop("JIRA_ADMIN_TOKEN", None)
+        with patch.dict(os.environ, env, clear=True):
+            result = main(
+                [
+                    "--project-key=TESTPROJ",
+                    "--jira-host=test.atlassian.net",
+                    "--dry-run",
+                ]
+            )
+        assert result == 0
+
+
+class TestExportDoesNotRequireEmail:
+    """test_export_does_not_require_email — --export without JIRA_USER_EMAIL succeeds."""
+
+    def test_export_does_not_require_email(self, tmp_path: Path) -> None:
+        export_path = str(tmp_path / "test-bundle.yaml")
+        env = os.environ.copy()
+        env.pop("JIRA_USER_EMAIL", None)
+        env.pop("JIRA_ADMIN_TOKEN", None)
+        with patch.dict(os.environ, env, clear=True):
+            result = main(
+                [
+                    "--project-key=TESTPROJ",
+                    "--jira-host=test.atlassian.net",
+                    "--export",
+                    export_path,
+                ]
+            )
+        assert result == 0
+        assert Path(export_path).exists()
+
+
 class TestExportEmitsBundle:
     """test_export_emits_bundle — --export <tmpfile> produces a file."""
 
@@ -214,6 +283,8 @@ def _build_mock_client(existing_statuses: list[dict[str, Any]] | None = None) ->
     """Build a mock JiraAdminClient with canned responses."""
     client = MagicMock(spec=JiraAdminClient)
     client.check_connectivity.return_value = None
+    client._resolve_project_id.return_value = "10000"
+    client._project_id_cache = {}
     if existing_statuses is None:
         existing_statuses = [
             {"id": "10000", "name": "To Do"},
@@ -239,6 +310,36 @@ def _build_mock_client(existing_statuses: list[dict[str, Any]] | None = None) ->
     return client
 
 
+class TestApplyUsesBasicAuthWithEmailAndToken:
+    """test_apply_uses_basic_auth_with_email_and_token — mocked client receives HTTP Basic auth."""
+
+    def test_apply_uses_basic_auth_with_email_and_token(self) -> None:
+        mock_client = _build_mock_client()
+        test_email = "admin@example.com"
+        test_token = "my-api-token"
+
+        with (
+            patch(
+                "methodology_framework.bootstrap_jira.JiraAdminClient",
+            ) as mock_cls,
+            patch.dict(
+                os.environ,
+                {"JIRA_ADMIN_TOKEN": test_token, "JIRA_USER_EMAIL": test_email},
+            ),
+        ):
+            mock_cls.return_value = mock_client
+            result = main(
+                [
+                    "--project-key=TESTPROJ",
+                    "--jira-host=test.atlassian.net",
+                    "--apply",
+                    "--force",
+                ]
+            )
+            assert result == 0
+            mock_cls.assert_called_once_with("test.atlassian.net", test_token, test_email)
+
+
 class TestApplyIdempotent:
     """test_apply_idempotent — second apply is a no-op."""
 
@@ -250,7 +351,10 @@ class TestApplyIdempotent:
                 "methodology_framework.bootstrap_jira.JiraAdminClient",
                 return_value=mock_client,
             ),
-            patch.dict(os.environ, {"JIRA_ADMIN_TOKEN": "fake-token"}),
+            patch.dict(
+                os.environ,
+                {"JIRA_ADMIN_TOKEN": "fake-token", "JIRA_USER_EMAIL": "user@example.com"},
+            ),
         ):
             result1 = main(
                 [