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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.1.2
+Version: 0.3.2
 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
 
@@ -129,10 +163,63 @@ framework's workflows by SemVer tag.
 > in the caller so updates are deliberate, not silent. This matches the
 > version-pinning model per methodology requirements § 4.13.
 
+### Required inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `project-key` | **Yes** | — | Jira project key (e.g. `METH`, `SCRUM`). No default — sync errors if absent. |
+| `jira-base-url` | **Yes** | — | Jira Cloud base URL (e.g. `https://icpipeline.atlassian.net`). |
+| `jira-user-email` | **Yes** | — | Jira service account email for HTTP Basic auth. |
+| `stories-dir` | No | `docs/stories` | Relative path to the stories directory. |
+| `phase-regex` | No | `^phase\d+$` | Regex for phase directory matching. Empty string (`""`) disables phase labeling entirely. |
+| `repo-url` | No | *(auto)* | Override repo URL. Normally derived from `GITHUB_SERVER_URL` + `GITHUB_REPOSITORY` (GHA-native). |
+
+### Per-tenant discovery
+
+Sync discovers all tenant-specific Jira IDs at runtime via the REST API,
+using canonical **names** as lookup keys. The names come from the framework's
+shape definitions (`jira_shapes/*.yaml`) — the same spec the verifier
+(`bootstrap-jira --verify`) enforces.
+
+**Custom fields** (discovered via `GET /rest/api/3/field`):
+
+| Name | Purpose |
+|------|---------|
+| `Requirement IDs` | Multi-value field for REQ-id traceability |
+| `Story File` | URL to the canonical story `.md` file in the repo |
+| `Agent Estimate` | Numeric estimate in agent-hours |
+
+**Statuses** (discovered via `GET /rest/api/3/project/{key}/statuses`):
+
+| Name | Category |
+|------|----------|
+| `To Do` | TODO |
+| `Ready for AI agent` | TODO |
+| `In Progress` | IN_PROGRESS |
+| `In Review` | IN_PROGRESS |
+| `Waiting` | IN_PROGRESS |
+| `Blocked` | IN_PROGRESS |
+| `Done` | DONE |
+| `Won't do` | DONE |
+
+**Transitions**: Sourced from the workflow spec (`jira_shapes/workflow.yaml`).
+
+**Link types** (discovered via `GET /rest/api/3/issueLinkType`):
+`Blocks` (inward: "is blocked by").
+
+**Issue types** (discovered via `GET /rest/api/3/issuetype`):
+`Story`, `Sub-task`.
+
+If any required name is missing from the target project, sync fails fast:
+```
+ERROR: Required custom field 'Story File' not found in Jira project METH;
+run 'methodology-framework bootstrap-jira --verify --project-key=METH' to identify the gap.
+```
+
 ### Story sync workflow
 
 Syncs story `.md` files from the adopter's repo to Jira. Create
-`.github/workflows/sync.yml` in the adopter repo:
+`.github/workflows/sync-stories.yml` in the adopter repo:
 
 ```yaml
 name: Sync stories to Jira
@@ -155,17 +242,17 @@ on:
 
 jobs:
   sync:
-    uses: whiteout59/methodology-framework/.github/workflows/sync.yml@v0.1.0
+    permissions:
+      contents: write
+      pull-requests: read
+    uses: whiteout59/methodology-framework/.github/workflows/sync.yml@v0.3.0
     with:
-      project_key: SCRUM
-      repo: whiteout59/centralized-pipeline-ui
-      story_path_pattern: "docs/stories/{phase1,phase2}/**/*.md"
-      cf_story_file: "customfield_10073"
-      cf_requirement_ids: "customfield_10141"
-      cf_agent_estimate: "customfield_10074"
+      project_key: MYPROJ
       mode: ${{ github.event.inputs.mode || 'since-ref' }}
       jira_base_url: "https://myorg.atlassian.net"
       jira_user_email: "devin-sync@myorg.atlassian.net"
+      # stories_dir: "docs/stories"    # default
+      # phase_regex: "^phase\\d+$"     # default; set "" to disable
     secrets:
       JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
 ```
@@ -179,6 +266,34 @@ for nightly or `workflow_dispatch` full-corpus syncs.
 > inherited by default in reusable workflows. Using `secrets: inherit`
 > works but is brittle — prefer explicit mapping.
 
+#### Required caller permissions
+
+The reusable sync workflow declares `permissions: contents: write`
+internally (for `jira_key` + `agent_acus` writeback commits). GitHub
+Actions requires the **caller** to grant at least the same permissions
+at the job level — otherwise the workflow fails at the `uses:`
+resolution step with:
+
+```
+The workflow is requesting 'contents: write', but is only allowed 'contents: read'.
+```
+
+Add a job-level `permissions:` block to your caller:
+
+```yaml
+jobs:
+  sync:
+    permissions:
+      contents: write
+      pull-requests: read
+    uses: whiteout59/methodology-framework/.github/workflows/sync.yml@v0.2.0
+    # ... with: / secrets: as above
+```
+
+> **Job-scoped, not workflow-scoped.** Keep `permissions:` on the job,
+> not the top-level `on:` — if future jobs are added to the same file,
+> they should not inherit write access they don't need.
+
 ### Playbook build + register workflow
 
 Builds a concrete playbook from a parameterized body + bindings file,
@@ -210,6 +325,16 @@ jobs:
 > 4 levels deep. If your repo wraps these workflows in another
 > caller layer, verify the total nesting depth stays within limits.
 
+## How this repo evolves
+
+The methodology-framework repo itself uses the same sync workflow it
+ships to adopters. Framework-side evolution stories (new specs, CLI
+features, workflow improvements) are drafted as `.md` files under
+`docs/stories/` and synced to the **METH** Jira project via
+[`.github/workflows/sync-stories.yml`](.github/workflows/sync-stories.yml).
+Adopter-side stories (product-specific work) file in each adopter's own
+Jira project (e.g. SCRUM for centralized-pipeline-ui).
+
 ## PyPI Publishing
 
 The package is published to PyPI automatically via OIDC Trusted Publishers
@@ -234,31 +359,37 @@ to the GitHub repo `whiteout59/methodology-framework`, workflow
 Version bumps in `pyproject.toml` drive the entire release cycle
 automatically. The operator's only decision surface is PR review.
 
-### Normal flow
+### Primary flow (chained via `workflow_call`)
 
-1. A PR bumps the `version` field in `pyproject.toml` (e.g. `"0.1.1"` → `"0.1.2"`).
+1. A PR bumps the `version` field in `pyproject.toml` (e.g. `"0.2.0"` → `"0.2.1"`).
 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.
+3. `auto-tag.yml` fires on the `pyproject.toml` change, extracts the version,
+   validates it as stable SemVer (`^[0-9]+\.[0-9]+\.[0-9]+$`), and creates an
+   annotated tag `v0.2.1`.
+4. `auto-tag.yml`'s `publish` job invokes `pypi-release.yml` via `workflow_call`,
+   passing the version as an input.
+5. `pypi-release.yml` checks out the tag, builds the package, and publishes to
+   PyPI via OIDC Trusted Publishers.
 
-**Operator surface = PR review only.** No manual `git tag` step required.
+**Operator surface = PR review only.** No manual `git tag` step, no manual
+publish trigger. The `workflow_call` chain bypasses GitHub's recursion guard
+that prevents `GITHUB_TOKEN`-authored tag pushes from triggering downstream
+workflows via `on: push: tags:`.
 
-### Manual fallback
+### Fallback (operator-pushed tag)
 
 If `auto-tag.yml` doesn't fire (workflow disabled, branch protection
-blocking the tag push, GitHub Actions outage, etc.), the manual fallback
-still works:
+blocking the tag push, GitHub Actions outage, etc.), or the operator needs
+to re-publish a yanked version, the manual fallback still works:
 
 ```bash
-git tag -a v0.1.2 -m "Release v0.1.2"
-git push origin v0.1.2
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin vX.Y.Z
 ```
 
-`pypi-release.yml` doesn't care how the tag arrived — it fires on any
-tag matching `v[0-9]+.[0-9]+.[0-9]+`.
+An operator-pushed tag directly triggers `pypi-release.yml` via the
+preserved `on: push: tags: ['v[0-9]+.[0-9]+.[0-9]+']` trigger. This
+path is independent of `auto-tag.yml` and requires no `workflow_call`.
 
 ### Pre-release versions
 
@@ -292,6 +423,20 @@ The caller fires on merged PRs that touch story files, invokes the
 reusable `populate-story-acus.yml` workflow, and opens a follow-on PR
 with the populated ACU values.
 
+## Contributing
+
+Framework evolution stories — new specs, CLI features, workflow improvements —
+are filed as Markdown story files under [`docs/stories/`](docs/stories/).
+See the [directory README](docs/stories/README.md) for the filing convention
+(slug-named directories, frontmatter shape, `depends_on` hygiene). Stories
+sync to the **METH** Jira project via the same sync workflow the framework
+ships to adopters.
+
+For the canonical story template and format spec, see
+[`whiteout59/centralized-pipeline-ui/methodology/templates/story.md`](https://github.com/whiteout59/centralized-pipeline-ui/blob/main/methodology/templates/story.md)
+and
+[`whiteout59/centralized-pipeline-ui/methodology/devin-story-format.md`](https://github.com/whiteout59/centralized-pipeline-ui/blob/main/methodology/devin-story-format.md).
+
 ## Development
 
 ```bash