methodology-framework 0.1.0__py3-none-any.whl

methodology_framework/templates/github_workflows/populate-story-acus-caller.yml

@@ -0,0 +1,29 @@
+# Adopter-side caller workflow for the agent_acus populator.
+#
+# Copy this file into your repo at .github/workflows/populate-story-acus.yml
+# and configure the DEVIN_API_TOKEN secret in your repo settings
+# (Settings > Secrets and variables > Actions > New repository secret).
+#
+# This workflow fires after a PR that touches story files is merged,
+# scans for story files with unpopulated agent_acus fields, fetches
+# ACU data from the Devin API, and opens a follow-on PR to backfill.
+
+name: Populate story agent_acus
+
+on:
+  pull_request_target:
+    types: [closed]
+    paths:
+      - "docs/stories/**/*.md"
+
+jobs:
+  populate:
+    if: github.event.pull_request.merged == true
+    uses: whiteout59/methodology-framework/.github/workflows/populate-story-acus.yml@v0.1.0
+    with:
+      story-path-pattern: "docs/stories/**/*.md"
+      default-branch: main
+    secrets:
+      # Set DEVIN_API_TOKEN as a repository secret:
+      # Settings > Secrets and variables > Actions > New repository secret
+      DEVIN_API_TOKEN: ${{ secrets.DEVIN_API_TOKEN }}

methodology_framework/templates/story.md

@@ -0,0 +1,152 @@
+---
+title: <One-line title — becomes the Jira summary>
+type: task
+labels: [<phase1-backfill | phase2>, <area-1>, <area-2>]
+requirements: [<REQ-...>, <REQ-...>]
+depends_on: []
+parent: null
+tasks: []
+estimate: <2h | 4h | 8h | 16h | 24h>
+jira_key: null
+---
+
+# <One-line title — same as frontmatter>
+
+**Requirement(s):** <REQ-...>, <REQ-...>
+
+## Context
+
+<Why this story exists, in 1–3 sentences. Cite related docs/stories by path. Don't re-explain `../../docs/alignment.md` or `../../docs/use-cases.md` — link to the relevant section.>
+
+## Goal
+
+<The deliverable in one sentence. If you can't, the story is too big — split it.>
+
+## Acceptance criteria
+
+- <testable, **concrete** bullet — exact paths, commands, JSON shapes, or expected outputs>
+- <testable, concrete bullet 2>
+- <…>
+
+## Files
+
+- `path/to/file.ext` — (new | modified) — short note on the change
+- `path/to/another` — (new | modified) — …
+
+## Validation
+
+```bash
+# concrete commands a reviewer can run to confirm the story is done
+```
+
+Expected: <plain-prose description of expected output>.
+
+## Out of scope
+
+- <Thing that looks like this story but isn't — name it explicitly>
+- <Followup or different concern>
+
+## Dependencies
+
+- `<slug-of-prior-story>` — short reason
+- (or "None.")
+
+## Execution recipe
+
+<!-- Per-story strategy: how Devin goes from cold start to AC-satisfied state for THIS task.
+     Strictly additive to the 8 contract sections above. Universal rules (forbidden actions,
+     drift-trigger handling, required reading) live in the router playbook — NOT here.
+     See methodology/templates/execution-recipe.template.md for the canonical template and
+     a filled-in example. -->
+
+### Procedure
+
+<!-- 5–15 imperative steps. Action verb first. Reference exact files / commands / strings.
+     For verification, reference `## Validation` rather than duplicating its commands. -->
+
+1. <imperative step — action verb first; reference exact files / commands / strings>
+2. <imperative step>
+3. <…>
+4. Run the commands in `## Validation` and confirm green.
+
+### Inputs needed from user
+
+<!-- Anything Devin cannot obtain from the repo, the methodology docs, or the Jira ticket.
+     Default "None." for a well-scoped story. -->
+
+- <input — why it's needed>
+- <or "None.">
+
+### Story-specific advice
+
+<!-- Optional. Omit this subsection entirely if there's nothing to add.
+     Gotchas / context Devin would not infer from CLAUDE.md, methodology docs,
+     the runbook, or the rest of the story body. -->
+
+- <tip>
+
+### Story-specific forbidden actions
+
+<!-- Optional. Omit this subsection entirely if there's nothing to add.
+     Constraints beyond the universal forbidden actions in the router playbook. -->
+
+- <constraint>
+
+## Scoping notes (pre-execution)
+
+<!-- Written by the agent at session start, before any implementation work.
+     Source of truth for the agent's pre-execution understanding. The agent
+     populates this section and commits it as the FIRST commit on the
+     implementation branch (message: `docs(stories): scope <story-slug>`).
+     The Jira scoping comment is a duplicate for operator convenience;
+     this section is the canonical in-git record. -->
+
+```yaml
+understanding_of_goal: ""
+implementation_plan: []
+files_expected_to_touch: []
+ac_verification_approach: []
+confidence: ""          # HIGH | MEDIUM | LOW
+confidence_reasoning: ""
+```
+
+## Post-execution notes
+
+<!-- Filled by the agent (Devin or similar) after the implementation PR merges.
+     Lead reviews on the implementation PR and may edit. Structured YAML for
+     DB ingestion alongside cross-project comparison. Use empty list `[]` for
+     "none" rather than deleting the field — downstream tooling expects the
+     keys. The free-text bullets inside `surprises` are the most important
+     field for compounding lessons. See docs/devin-story-format.md § "Feedback
+     loop and post-execution notes" for the full spec. -->
+
+```yaml
+actual_hours: 0
+estimated_hours: 0
+estimate_delta_pct: 0
+ac_bullets_clarified: 0
+ac_clarifications: []
+drift_events: []
+rescoping_required: false
+rescoping_reason: ""
+files_touched_outside_spec: []
+surprises: []
+recommended_runbook_updates: []
+```
+
+<!--
+Notes for the author (delete before filing in Jira):
+
+- `type: task` is the default. Change to `type: story` ONLY if this ticket
+  collects multiple child tasks via the `tasks:` list. See
+  `../devin-story-format.md` § "Story vs task — when to bundle."
+- `estimate` cap for tasks is 24h. If your work exceeds 24h, split into
+  parent + leaves before drafting.
+- AC must be concrete. "Works correctly" / "looks right" are rejected.
+- The `## Execution recipe` section is mandatory for Phase-2 forward stories.
+  Phase-1 backfill stories (those carrying the `manual-gate` label) may omit
+  it since they're documentation tickets, not execution tickets.
+- The `<!-- comments -->` are stripped on Jira paste; the YAML frontmatter
+  is also not pasted (it's repo-internal). Only the body below the
+  frontmatter goes into Jira's description.
+-->

methodology_framework-0.1.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: methodology-framework
+Version: 0.1.0
+Summary: Portable process tooling for agent-driven delivery — scripts, playbooks, templates, and specs.
+Author: whiteout59
+License-Expression: Apache-2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.31
+Requires-Dist: python-frontmatter<2,>=1.1
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+Requires-Dist: requests-mock<2,>=1.12; extra == "dev"
+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"
+Dynamic: license-file
+
+# methodology-framework
+
+Portable process tooling for agent-driven delivery -- scripts, playbooks, templates, and specs.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Package contents
+
+- `methodology_framework.sync_stories_to_jira` -- one-way repo-to-Jira story sync
+- `methodology_framework.build_playbook` -- build a concrete playbook from a parameterized body + bindings
+- `methodology_framework.register_playbook_with_devin` -- register a rendered playbook with Devin's API
+- `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/jira_shapes/` -- canonical Jira shape definitions (YAML, package data)
+
+## Jira Bootstrap
+
+Adopting projects provision their Jira project shape from a single CLI command
+instead of manually configuring 30+ admin UI screens.
+
+### 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 or OAuth Bearer token
+
+### Usage
+
+```bash
+# Dry-run (default) — print what would be applied, no side-effects
+python -m methodology_framework bootstrap-jira \
+  --project-key=MYPROJ \
+  --jira-host=myorg.atlassian.net \
+  --dry-run
+
+# Export — emit an importable config bundle (YAML); no API calls
+python -m methodology_framework bootstrap-jira \
+  --project-key=MYPROJ \
+  --jira-host=myorg.atlassian.net \
+  --export /tmp/jira-bundle.yaml
+
+# Apply — provision the Jira project via admin API
+export JIRA_ADMIN_TOKEN="<your-token>"
+python -m methodology_framework bootstrap-jira \
+  --project-key=MYPROJ \
+  --jira-host=myorg.atlassian.net \
+  --apply
+
+# Apply with --force to skip confirmation prompts
+python -m methodology_framework bootstrap-jira \
+  --project-key=MYPROJ \
+  --jira-host=myorg.atlassian.net \
+  --apply --force
+```
+
+### 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`. |
+
+### Environment variables
+
+| Variable | When needed | Description |
+|----------|-------------|-------------|
+| `JIRA_ADMIN_TOKEN` | `--apply` mode | Jira admin API token. **Never** accepted as a CLI flag. |
+
+### Shape definitions
+
+The three canonical shape files shipped as package data:
+
+- `jira_shapes/workflow.yaml` — workflow statuses (To Do, Ready for AI agent,
+  In Progress, In Review, Waiting, Blocked, Done, Won't do) and transitions
+  with actor permissions
+- `jira_shapes/custom_fields.yaml` — Story File (URL), Requirement IDs
+  (labels), Agent Estimate (number)
+- `jira_shapes/automation_rules.yaml` — PR-title-key auto-transition,
+  dependency resolution, BLOCKED protection
+
+For full methodology context see the methodology requirements doc § 4.13.3
+("Jira Bootstrap CLI").
+
+## Adopter Integration
+
+Adopting projects consume the methodology framework's CI pipelines via
+**reusable GitHub Actions workflows**. Instead of copying workflow YAML
+into each repo, adopters write a thin caller that references the
+framework's workflows by SemVer tag.
+
+> **Version pinning requirement:** adopters MUST pin to a specific tag
+> (`@v0.X.Y`), never `@main`. The framework version must be explicit
+> in the caller so updates are deliberate, not silent. This matches the
+> version-pinning model per methodology requirements § 4.13.
+
+### Story sync workflow
+
+Syncs story `.md` files from the adopter's repo to Jira. Create
+`.github/workflows/sync.yml` in the adopter repo:
+
+```yaml
+name: Sync stories to Jira
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/stories/**/*.md"
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "Sync mode"
+        required: true
+        default: "since-ref"
+        type: choice
+        options:
+          - since-ref
+          - all
+
+jobs:
+  sync:
+    uses: whiteout59/methodology-framework/.github/workflows/sync.yml@v0.1.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"
+      mode: ${{ github.event.inputs.mode || 'since-ref' }}
+      jira_base_url: "https://myorg.atlassian.net"
+      jira_user_email: "devin-sync@myorg.atlassian.net"
+    secrets:
+      JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
+```
+
+The `mode` input defaults to `since-ref` for routine push-triggered
+runs (preserves the 250-story scale guard). Pass `mode: all` explicitly
+for nightly or `workflow_dispatch` full-corpus syncs.
+
+> **Secrets forwarding:** the caller's `secrets:` block must explicitly
+> map each secret the reusable workflow declares. Secrets are NOT
+> inherited by default in reusable workflows. Using `secrets: inherit`
+> works but is brittle — prefer explicit mapping.
+
+### Playbook build + register workflow
+
+Builds a concrete playbook from a parameterized body + bindings file,
+then registers it with Devin's API. Create
+`.github/workflows/build-and-register.yml` in the adopter repo:
+
+```yaml
+name: Build and register playbook
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "methodology/playbooks/*.body.md"
+      - "docs/jira-pickup-config.md"
+  workflow_dispatch:
+
+jobs:
+  build-and-register:
+    uses: whiteout59/methodology-framework/.github/workflows/build-and-register.yml@v0.1.0
+    with:
+      playbook_body_path: "methodology/playbooks/scrum-router.body.md"
+      bindings_path: "docs/jira-pickup-config.md"
+    secrets:
+      DEVIN_API_TOKEN: ${{ secrets.DEVIN_API_TOKEN }}
+```
+
+> **Nesting limit:** GitHub allows reusable workflow nesting up to
+> 4 levels deep. If your repo wraps these workflows in another
+> caller layer, verify the total nesting depth stays within limits.
+
+## PyPI Publishing
+
+The package is published to PyPI automatically via OIDC Trusted Publishers
+when a SemVer tag is pushed:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The `pypi-release.yml` workflow builds and publishes using
+`pypa/gh-action-pypi-publish` in OIDC mode -- no `PYPI_API_TOKEN` secret
+is needed. The job uses the `pypi` GitHub environment for protection rules.
+
+**Operator setup (one-time):** bind the PyPI project `methodology-framework`
+to the GitHub repo `whiteout59/methodology-framework`, workflow
+`pypi-release.yml`, environment `pypi` at
+[PyPI Trusted Publishers](https://pypi.org/manage/account/publishing/).
+
+## Cost tracking via `agent_acus`
+
+The methodology's post-execution notes include an `agent_acus` field that
+records per-story compute cost. Since agents cannot self-report ACU
+consumption mid-session, a post-merge populator workflow backfills the
+value from the Devin API after the session completes.
+
+**Adopter wiring (3 steps):**
+
+1. Copy the template caller into your repo:
+   ```bash
+   cp "$(python -c "import methodology_framework; import pathlib; \
+     print(pathlib.Path(methodology_framework.__file__).parent / \
+     'templates/github_workflows/populate-story-acus-caller.yml')")" \
+     .github/workflows/populate-story-acus.yml
+   ```
+2. Set the `DEVIN_API_TOKEN` repo secret (Settings > Secrets and
+   variables > Actions > New repository secret).
+3. Pin the framework version in the caller's `uses:` line.
+
+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.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+ruff check src/methodology_framework
+ruff format --check src/methodology_framework
+mypy --strict src/methodology_framework
+```
+
+## License
+
+Apache-2.0

methodology_framework-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+methodology_framework/__init__.py,sha256=ESIHybKFnmmZbuf2xuQLs7Vrwcd2VmODwh6EoWPN8eY,369
+methodology_framework/__main__.py,sha256=kXfpMr2bQZLAQUgfAVQXL95Wgu11Ma357PzKs_4QTGI,808
+methodology_framework/bootstrap_jira.py,sha256=ebPWkG4XpB-C5CI0wcNox_QRtb0hM2vORBAEgdKsXms,15963
+methodology_framework/build_playbook.py,sha256=S2y-HCpQF2XntNWe2HnsZFXeGyKEdp4YhMTybkveE-8,5622
+methodology_framework/populate_acus.py,sha256=ROgH5EFHkI10J9OI6ONraTbcRSGmYJlYd5dbti7NoEk,6674
+methodology_framework/register_playbook_with_devin.py,sha256=4W5ImbYVW90CMZX3eMsmKabPwQJhlRHzszygcOLlno0,10225
+methodology_framework/sync_stories_to_jira.py,sha256=j4QTj_h6J5wZqhq34dbQRrhusc5epOtxWgLjtRmY91A,38827
+methodology_framework/jira_shapes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+methodology_framework/jira_shapes/automation_rules.yaml,sha256=Mid3XM-dmk94uL9Euj1bxTjxpEzH2i0r6k451ZfTKYM,3393
+methodology_framework/jira_shapes/custom_fields.yaml,sha256=Hs_sAQhTmY0eAsWLmGgH8J_kV_plhXl6rKbHdawrvXQ,1506
+methodology_framework/jira_shapes/workflow.yaml,sha256=RykoRww1bvG0RF1IVPm_TQ8OkbzVw3GGywm0vBJmVOE,4357
+methodology_framework/playbooks/scrum-router.body.md,sha256=aYjf-ECejMYFR678WxAlfSliiJobcLxnXW66yr3n1-s,28274
+methodology_framework/specs/devin-story-format.md,sha256=UETitaH4Gyk5vAhZc72hB4SFrTLXQOUiIdJQZ_bgThA,43600
+methodology_framework/templates/story.md,sha256=OSlKoO312WgrCpnwpOxI6h6jZ5suacnfX015a_fi0O0,5047
+methodology_framework/templates/github_workflows/populate-story-acus-caller.yml,sha256=MXPPcsoEUWD9-dhww5b9COedimmIU1cfH1fwKHraN0k,1048
+methodology_framework-0.1.0.dist-info/licenses/LICENSE,sha256=gBrcDYRbLYLNFdvs81q_IFs2bT8Rli41A_eKqiNT5ew,1067
+methodology_framework-0.1.0.dist-info/METADATA,sha256=oouBG0-azmm7PN3KwVD17oaq55Y6hQ_yTWr0gybaonU,9123
+methodology_framework-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+methodology_framework-0.1.0.dist-info/top_level.txt,sha256=Azz1pUEpyIM2qQXNdAfoMGs-E0IhOUWmVoazLTnPxuU,22
+methodology_framework-0.1.0.dist-info/RECORD,,

methodology_framework-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

methodology_framework-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whiteout59
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

methodology_framework-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+methodology_framework