methodology-framework 0.1.1__tar.gz → 0.2.0__tar.gz

{methodology_framework-0.1.1/src/methodology_framework.egg-info → methodology_framework-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.1.1
+Version: 0.2.0
 Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
 Author: whiteout59
 License-Expression: Apache-2.0
@@ -10,6 +10,7 @@ License-File: LICENSE
 Requires-Dist: requests<3,>=2.31
 Requires-Dist: python-frontmatter<2,>=1.1
 Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: colorama<1,>=0.4
 Provides-Extra: dev
 Requires-Dist: pytest<9,>=8.0; extra == "dev"
 Requires-Dist: requests-mock<2,>=1.12; extra == "dev"
@@ -17,6 +18,8 @@ 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: types-colorama<1,>=0.4; extra == "dev"
+Requires-Dist: vcrpy<9,>=7.0; extra == "dev"
 Dynamic: license-file
 
 # methodology-framework
@@ -37,69 +40,101 @@ pip install -e .
 - `methodology_framework/playbooks/` -- parameterized playbook bodies (package data)
 - `methodology_framework/templates/` -- story and process templates (package data)
 - `methodology_framework/specs/` -- format specs (package data)
-- `methodology_framework.bootstrap_jira` -- bootstrap a Jira project with the canonical workflow, custom fields, and automation rules
+- `methodology_framework.bootstrap_jira` -- verify a Jira project matches the canonical shape (read-only spec-compliance checker)
 - `methodology_framework/jira_shapes/` -- canonical Jira shape definitions (YAML, package data)
 
-## Jira Bootstrap
+## Jira Bootstrap (Verify Mode)
 
-Adopting projects provision their Jira project shape from a single CLI command
-instead of manually configuring 30+ admin UI screens.
+The CLI checks whether a Jira project matches the methodology-framework's
+canonical shape and reports gaps. It does **not** provision — operators apply
+gaps via the Jira UI. This read-only design lets the tool run in CI as a gate.
+
+> **v0.2.0 breaking change:** `--apply` and `--dry-run` were removed.
+> The CLI is now a spec-compliance verifier. See `operator-verify-runbook.md`
+> for the operator workflow.
 
 ### Prerequisites
 
 - 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, and `JIRA_USER_EMAIL` set to the email of the Atlassian
-  account that owns that token
+- For `--verify` mode: `JIRA_ADMIN_TOKEN` environment variable set to a Jira
+  API token (admin scope is **not** required; a regular user token with read
+  access is sufficient), and `JIRA_USER_EMAIL` set to the email of the
+  Atlassian account that owns the token
 
 ### Usage
 
 ```bash
-# Dry-run (default) — print what would be applied, no side-effects
+# Verify — query Jira and report spec-compliance gaps (read-only)
+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 \
-  --dry-run
+  --verify
 
-# Export — emit an importable config bundle (YAML); no API calls
+# JSON output (stable schema — safe for CI parsing)
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --export /tmp/jira-bundle.yaml
+  --verify --output=json
 
-# Apply — provision the Jira project via admin API
-export JIRA_ADMIN_TOKEN="<your-token>"
-export JIRA_USER_EMAIL="<your-email>"
+# Markdown output
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --apply
+  --verify --output=markdown
 
-# Apply with --force to skip confirmation prompts
+# Export — emit an importable config bundle (YAML); no API calls
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --apply --force
+  --export /tmp/jira-bundle.yaml
 ```
 
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All spec items verified OK |
+| `1` | One or more items missing (gaps found) |
+| `2` | One or more items unverifiable (API limitation; operator must inspect manually) |
+| `3` | Error (connectivity, auth, or runtime failure) |
+
 ### Flags
 
 | Flag | Required | Description |
 |------|----------|-------------|
 | `--project-key` | Yes | Jira project key (e.g. `SCRUM`). Substituted for `{{PROJECT_KEY}}` in shape defs. |
 | `--jira-host` | Yes | Jira Cloud host (e.g. `myorg.atlassian.net`). No `https://` prefix. |
-| `--dry-run` | No | Print what would be applied (default if no mode specified). |
-| `--apply` | No | POST/PUT to Jira admin API. Requires `JIRA_ADMIN_TOKEN` env var. |
-| `--export <path>` | No | Emit importable config bundle at `<path>`. |
-| `--force` | No | Skip confirmation prompts during `--apply`. |
+| `--verify` | No | Query Jira and report spec-compliance gaps (read-only). |
+| `--export <path>` | No | Emit importable config bundle at `<path>`. No API calls. |
+| `--output` | No | Output format for `--verify`: `text` (default), `json`, `markdown`. |
 
 ### Environment variables
 
 | 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. |
+| `JIRA_ADMIN_TOKEN` | `--verify` mode | Jira API token. Admin scope is **not** required; a regular user token with read access is sufficient. **Never** accepted as a CLI flag. |
+| `JIRA_USER_EMAIL` | `--verify` 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. |
+
+### JSON output schema (v0.2.0)
+
+```json
+{
+  "spec_version": "0.2.0",
+  "project_key": "METH",
+  "verified_at": "2025-05-31T00:00:00Z",
+  "items": [
+    {"resource_type": "status", "name": "To Do", "result": "ok", "details": null},
+    {"resource_type": "custom_field", "name": "Story File", "result": "missing", "details": "Operator must create via Settings → Custom fields → Create"}
+  ],
+  "summary": {"total": 14, "ok": 12, "missing": 1, "unverifiable": 1},
+  "exit_code": 1
+}
+```
+
+Any breaking change to this schema requires a MAJOR version bump.
 
 ### Shape definitions
 
@@ -228,6 +263,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
@@ -262,6 +336,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.1 → methodology_framework-0.2.0}/README.md

@@ -16,69 +16,101 @@ pip install -e .
 - `methodology_framework/playbooks/` -- parameterized playbook bodies (package data)
 - `methodology_framework/templates/` -- story and process templates (package data)
 - `methodology_framework/specs/` -- format specs (package data)
-- `methodology_framework.bootstrap_jira` -- bootstrap a Jira project with the canonical workflow, custom fields, and automation rules
+- `methodology_framework.bootstrap_jira` -- verify a Jira project matches the canonical shape (read-only spec-compliance checker)
 - `methodology_framework/jira_shapes/` -- canonical Jira shape definitions (YAML, package data)
 
-## Jira Bootstrap
+## Jira Bootstrap (Verify Mode)
 
-Adopting projects provision their Jira project shape from a single CLI command
-instead of manually configuring 30+ admin UI screens.
+The CLI checks whether a Jira project matches the methodology-framework's
+canonical shape and reports gaps. It does **not** provision — operators apply
+gaps via the Jira UI. This read-only design lets the tool run in CI as a gate.
+
+> **v0.2.0 breaking change:** `--apply` and `--dry-run` were removed.
+> The CLI is now a spec-compliance verifier. See `operator-verify-runbook.md`
+> for the operator workflow.
 
 ### Prerequisites
 
 - 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, and `JIRA_USER_EMAIL` set to the email of the Atlassian
-  account that owns that token
+- For `--verify` mode: `JIRA_ADMIN_TOKEN` environment variable set to a Jira
+  API token (admin scope is **not** required; a regular user token with read
+  access is sufficient), and `JIRA_USER_EMAIL` set to the email of the
+  Atlassian account that owns the token
 
 ### Usage
 
 ```bash
-# Dry-run (default) — print what would be applied, no side-effects
+# Verify — query Jira and report spec-compliance gaps (read-only)
+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 \
-  --dry-run
+  --verify
 
-# Export — emit an importable config bundle (YAML); no API calls
+# JSON output (stable schema — safe for CI parsing)
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --export /tmp/jira-bundle.yaml
+  --verify --output=json
 
-# Apply — provision the Jira project via admin API
-export JIRA_ADMIN_TOKEN="<your-token>"
-export JIRA_USER_EMAIL="<your-email>"
+# Markdown output
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --apply
+  --verify --output=markdown
 
-# Apply with --force to skip confirmation prompts
+# Export — emit an importable config bundle (YAML); no API calls
 python -m methodology_framework bootstrap-jira \
   --project-key=MYPROJ \
   --jira-host=myorg.atlassian.net \
-  --apply --force
+  --export /tmp/jira-bundle.yaml
 ```
 
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All spec items verified OK |
+| `1` | One or more items missing (gaps found) |
+| `2` | One or more items unverifiable (API limitation; operator must inspect manually) |
+| `3` | Error (connectivity, auth, or runtime failure) |
+
 ### Flags
 
 | Flag | Required | Description |
 |------|----------|-------------|
 | `--project-key` | Yes | Jira project key (e.g. `SCRUM`). Substituted for `{{PROJECT_KEY}}` in shape defs. |
 | `--jira-host` | Yes | Jira Cloud host (e.g. `myorg.atlassian.net`). No `https://` prefix. |
-| `--dry-run` | No | Print what would be applied (default if no mode specified). |
-| `--apply` | No | POST/PUT to Jira admin API. Requires `JIRA_ADMIN_TOKEN` env var. |
-| `--export <path>` | No | Emit importable config bundle at `<path>`. |
-| `--force` | No | Skip confirmation prompts during `--apply`. |
+| `--verify` | No | Query Jira and report spec-compliance gaps (read-only). |
+| `--export <path>` | No | Emit importable config bundle at `<path>`. No API calls. |
+| `--output` | No | Output format for `--verify`: `text` (default), `json`, `markdown`. |
 
 ### Environment variables
 
 | 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. |
+| `JIRA_ADMIN_TOKEN` | `--verify` mode | Jira API token. Admin scope is **not** required; a regular user token with read access is sufficient. **Never** accepted as a CLI flag. |
+| `JIRA_USER_EMAIL` | `--verify` 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. |
+
+### JSON output schema (v0.2.0)
+
+```json
+{
+  "spec_version": "0.2.0",
+  "project_key": "METH",
+  "verified_at": "2025-05-31T00:00:00Z",
+  "items": [
+    {"resource_type": "status", "name": "To Do", "result": "ok", "details": null},
+    {"resource_type": "custom_field", "name": "Story File", "result": "missing", "details": "Operator must create via Settings → Custom fields → Create"}
+  ],
+  "summary": {"total": 14, "ok": 12, "missing": 1, "unverifiable": 1},
+  "exit_code": 1
+}
+```
+
+Any breaking change to this schema requires a MAJOR version bump.
 
 ### Shape definitions
 
@@ -207,6 +239,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
@@ -241,6 +312,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.1 → methodology_framework-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.1.1"
+version = "0.2.0"
 description = "Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs."
 readme = "README.md"
 license = "Apache-2.0"
@@ -16,6 +16,7 @@ dependencies = [
     "requests>=2.31,<3",
     "python-frontmatter>=1.1,<2",
     "pyyaml>=6.0,<7",
+    "colorama>=0.4,<1",
 ]
 
 [project.optional-dependencies]
@@ -26,6 +27,8 @@ dev = [
     "mypy>=1.10,<2",
     "types-requests>=2.31,<3",
     "types-PyYAML>=6.0,<7",
+    "types-colorama>=0.4,<1",
+    "vcrpy>=7.0,<9",
 ]
 
 [tool.setuptools.packages.find]