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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodology-framework
-Version: 0.2.0
+Version: 0.3.3
 Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
 Author: whiteout59
 License-Expression: Apache-2.0
@@ -163,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
@@ -189,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 }}
 ```
@@ -213,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,
@@ -244,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
@@ -268,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
 
@@ -326,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

{methodology_framework-0.2.0 → methodology_framework-0.3.3}/README.md

@@ -139,10 +139,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
@@ -165,17 +218,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 }}
 ```
@@ -189,6 +242,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,
@@ -220,6 +301,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
@@ -244,31 +335,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
 
@@ -302,6 +399,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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "methodology-framework"
-version = "0.2.0"
+version = "0.3.3"
 description = "Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs."
 readme = "README.md"
 license = "Apache-2.0"
@@ -37,6 +37,7 @@ where = ["src"]
 [tool.setuptools.package-data]
 methodology_framework = [
     "playbooks/*.md",
+    "playbooks/bindings/*.yaml",
     "templates/*.md",
     "templates/github_workflows/*.yml",
     "specs/*.md",

{methodology_framework-0.2.0 → methodology_framework-0.3.3}/src/methodology_framework/build_playbook.py

@@ -10,15 +10,21 @@ documentation remains legible in the rendered output.  The frontmatter
 ``version:`` value is injected as the ``{{VERSION}}`` binding automatically.
 
 Usage:
-    python scripts/build_playbook.py [--output PATH] [--check]
+    python -m methodology_framework.build_playbook \
+        [--body PATH] [--bindings PATH] [--output PATH] [--check]
 
 Options:
+    --body PATH     Path to the parameterized playbook body (default: auto-detected
+                    relative to repo root).
+    --bindings PATH Path to the bindings file containing a playbook_bindings: YAML block
+                    (default: auto-detected relative to repo root).
     --output PATH   Write the built playbook to PATH (default: stdout).
     --check         Validate only: exit 0 if no unreplaced tokens, exit 1 otherwise.
                     Does not write output.
 
-The script is designed to be run from the repo root. It uses relative paths to locate
-the body and bindings files.
+When --body and --bindings are omitted, the script falls back to the legacy
+hardcoded paths (methodology/playbooks/scrum-router.body.md and
+docs/jira-pickup-config.md relative to the repo root).
 """
 
 from __future__ import annotations
@@ -112,6 +118,18 @@ def find_unreplaced(text: str) -> list[str]:
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--body",
+        type=str,
+        default=None,
+        help="Path to the parameterized playbook body (default: auto-detected)",
+    )
+    parser.add_argument(
+        "--bindings",
+        type=str,
+        default=None,
+        help="Path to bindings file with playbook_bindings: YAML block",
+    )
     parser.add_argument(
         "--output",
         type=str,
@@ -123,16 +141,19 @@ def main() -> int:
     )
     args = parser.parse_args()
 
-    if not BODY_PATH.exists():
-        print(f"ERROR: Body file not found: {BODY_PATH}", file=sys.stderr)
+    body_path = Path(args.body) if args.body else BODY_PATH
+    config_path = Path(args.bindings) if args.bindings else CONFIG_PATH
+
+    if not body_path.exists():
+        print(f"ERROR: Body file not found: {body_path}", file=sys.stderr)
         return 1
 
-    if not CONFIG_PATH.exists():
-        print(f"ERROR: Config file not found: {CONFIG_PATH}", file=sys.stderr)
+    if not config_path.exists():
+        print(f"ERROR: Config/bindings file not found: {config_path}", file=sys.stderr)
         return 1
 
-    body = BODY_PATH.read_text()
-    config = CONFIG_PATH.read_text()
+    body = body_path.read_text()
+    config = config_path.read_text()
 
     bindings = extract_bindings(config)
     if not bindings: