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

{methodology_framework-0.1.2/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.2
+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,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: types-colorama<1,>=0.4; extra == "dev"
 Requires-Dist: vcrpy<9,>=7.0; extra == "dev"
 Dynamic: license-file
 
@@ -38,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
 

{methodology_framework-0.1.2 → 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
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.1.2"
+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,7 @@ dev = [
     "mypy>=1.10,<2",
     "types-requests>=2.31,<3",
     "types-PyYAML>=6.0,<7",
+    "types-colorama>=0.4,<1",
     "vcrpy>=7.0,<9",
 ]