diff --git a/meta/activities/04-end-workflow.yaml b/meta/activities/04-end-workflow.yaml index 5c3423b4d..a24a80b37 100644 --- a/meta/activities/04-end-workflow.yaml +++ b/meta/activities/04-end-workflow.yaml @@ -1,23 +1,24 @@ id: end-workflow -version: 4.2.0 +version: 4.4.0 name: End Workflow description: Close out the client workflow. required: true steps: + - kind: technique + id: read-session + technique: workflow-engine::read-session - kind: technique id: verify-outcomes technique: name: workflow-engine::verify-outcomes inputs: outcomes: target_workflow_outcomes - state: client_state - kind: technique id: generate-summary technique: name: workflow-engine::generate-summary inputs: workflow_definition: target_workflow_id - execution_trace: client_trace - kind: checkpoint id: completion-confirmed message: Session summary presented above. Confirm closure or return to the workflow to address remaining items. diff --git a/meta/techniques/agent-conduct.md b/meta/techniques/agent-conduct.md index da63f0034..6992f26fe 100644 --- a/meta/techniques/agent-conduct.md +++ b/meta/techniques/agent-conduct.md @@ -1,6 +1,6 @@ --- metadata: - version: 4.5.0 + version: 4.6.0 --- ## Capability @@ -95,7 +95,7 @@ On resume, still dispatch a worker via [dispatch-activity](./workflow-engine/dis ### orchestrator-component-path-scope -Branch creation, PR creation, and code commits MUST be performed inside the component directory (the submodule), NEVER in the host monorepo root. Planning artifact commits (`.engineering/artifacts/`) MUST be performed in the host repo where that directory lives, on the current branch — do NOT create a new branch in the host repo. +Branch creation, PR creation, and code commits MUST be performed inside the component directory (the submodule), NEVER in the host monorepo root. Planning artifact commits (`.engineering/artifacts/`) land on the current branch of the checkout that holds that directory — which checkout that is, and the primitive it takes, are resolved by [commit-and-persist](./workflow-engine/commit-and-persist.md). Do NOT create a new branch for them. ### orchestrator-automatic-transitions diff --git a/meta/techniques/gitnexus-operations/TECHNIQUE.md b/meta/techniques/gitnexus-operations/TECHNIQUE.md index 1aaf85c8f..8f070cb05 100644 --- a/meta/techniques/gitnexus-operations/TECHNIQUE.md +++ b/meta/techniques/gitnexus-operations/TECHNIQUE.md @@ -1,6 +1,6 @@ --- metadata: - version: 3.2.0 + version: 3.3.0 --- ## Capability @@ -11,7 +11,7 @@ Codebase intelligence via the GitNexus knowledge graph — indexing, structural ### query-not-grep -Apply [query](./query.md) / [context](./context.md) for execution flows and relationships. Grep is for text patterns and string literals only — when structure matters, use GitNexus. +Apply [query](./query.md) / [context](./context.md) for execution flows and relationships among code symbols — that is what the graph holds. For a markdown tree it holds paths and no prose, so a question about which text states a claim is a grep question, and [query](./query.md) answers it with unrelated matches rather than nothing, which means a miss there does not read as a miss. Grep is also for text patterns and string literals in code. ### detect-changes-after-edit @@ -19,7 +19,11 @@ Always apply [detect-changes](./detect-changes.md) after applying a rename or ba ### index-freshness-first -Apply [verify-index](./verify-index.md) at the start of any GitNexus session. Stale indexes return misleading results. +Apply [verify-index](./verify-index.md) at the start of any GitNexus session, and again before any operation whose answer turns on the current tree — [impact](./impact.md), [detect-changes](./detect-changes.md), [orphan-scan](./orphan-scan.md), [diff-coverage-map](./diff-coverage-map.md). A stale index answers in the same shape as a fresh one and says nothing about its own age, so an unverified answer is indistinguishable from a correct one. + +### keyword-shaped-queries + +Phrase [query](./query.md) as keywords, not as a natural-language question. Its ranking fuses keyword and semantic scoring, and the semantic half contributes only where the index carries embeddings — which is a property of how the repo was indexed, not something the query can assert. Keyword-shaped input is the phrasing that works either way. ### must-use-operations diff --git a/meta/techniques/workflow-engine/commit-and-persist.md b/meta/techniques/workflow-engine/commit-and-persist.md index 6eb928e3f..08c1ba5b7 100644 --- a/meta/techniques/workflow-engine/commit-and-persist.md +++ b/meta/techniques/workflow-engine/commit-and-persist.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.7.0 + version: 1.8.0 --- ## Capability @@ -28,14 +28,17 @@ Path to the planning folder. 2. Set the header-line `**Status:**` to the current lifecycle milestone for that workflow (text — distinct from Progress Status; see [Progress table](../../resources/planning-readme.md#progress-table)). 3. If the README already matches after steps 1–2, leave content equivalent — still include the file in the engineering commit below so a prior local-only edit is pushed. 4. If `{host_repo_path}/{component_path}` has uncommitted changes (`git status --porcelain` non-empty), apply [version-control](../version-control/TECHNIQUE.md)::[commit-submodule](../version-control/commit-submodule.md)(*paths*=changed files, *submodule_message*=`'(): source changes'` with the Conventional Commits type that fits the activity — feat for implement, fix for post-impl-review fixes, refactor for cleanup, *parent_branch*=current parent branch). Skip when the working tree is clean. -5. **Engineering commit + push:** Apply [version-control](../version-control/TECHNIQUE.md)::[commit-regular-files](../version-control/commit-regular-files.md)(*paths*=ALL changes under `.engineering/artifacts/` within `{planning_folder_path}`, including `README.md`, `session.json` and `.session-token`, *message*=`docs(): artifacts`). This post-activity hook **is** the commit request — do not wait for a separate user confirmation. Push must succeed before this operation returns: Engineering links and resume assume the remote holds the commit, so a local-only README or artifact update does not satisfy this step. +5. **Engineering commit + push:** Commit ALL changes under `.engineering/artifacts/` within `{planning_folder_path}`, including `README.md`, `session.json` and `.session-token`, with *message*=`docs(): artifacts`. The primitive follows the layout, classified by `version-control.infrastructure-submodule-paths`. This post-activity hook **is** the commit request — do not wait for a separate user confirmation. Push must succeed before this operation returns: Engineering links and resume assume the remote holds the commit, so a local-only README or artifact update does not satisfy this step. + > When `.engineering` is a checkout of its own, apply [commit-submodule](../version-control/commit-submodule.md)(*submodule_path*=`.engineering`) — its own branch and remote carry the artifacts. + > Otherwise apply [commit-regular-files](../version-control/commit-regular-files.md) — the artifacts are ordinary files of the host checkout. + > Where the host branch accepts changes only through pull requests, the parent's submodule-pointer bump lands in a PR; a direct push to that branch is refused, and the engineering push above already satisfies this step without it. 6. Confirm the engineering push landed (remote tracking branch includes the new commit). If push failed, retry once; if still failing, surface the error and do not advance to the next activity. ## Rules ### commit-after-activity -After every completed activity, BOTH source-side changes (under `{host_repo_path}/{component_path}`, via [commit-submodule](../version-control/commit-submodule.md)) AND engineering artifacts (under `.engineering/artifacts/`, via [commit-regular-files](../version-control/commit-regular-files.md)) MUST be committed and **pushed** before evaluating transitions to the next activity. Skipping either scope leaves a dirty or remote-stale tree that breaks resume, Engineering links, and downstream activities. The submodule commit may be skipped only when the working tree at `{host_repo_path}/{component_path}` is clean. The engineering commit may be skipped only when the planning folder has no local changes **and** README Progress Status for `{activity_id}` already shows the intended post-activity status on the remote (complete, or cancelled/N/A when `{mark_progress_na}` applied) per [Status vocabulary](../../resources/planning-readme.md#status-vocabulary) — otherwise Apply sync-progress-status (step 1) then commit and push. Scope: this orchestrator post-activity hook only — distinct from [explicit-commit](../version-control/TECHNIQUE.md#explicit-commit), which governs ad-hoc commits outside this hook. +After every completed activity, BOTH source-side changes (under `{host_repo_path}/{component_path}`) AND engineering artifacts (under `.engineering/artifacts/`) MUST be committed and **pushed** before evaluating transitions to the next activity. Skipping either scope leaves a dirty or remote-stale tree that breaks resume, Engineering links, and downstream activities. The submodule commit may be skipped only when the working tree at `{host_repo_path}/{component_path}` is clean. The engineering commit may be skipped only when the planning folder has no local changes **and** README Progress Status for `{activity_id}` already shows the intended post-activity status on the remote (complete, or cancelled/N/A when `{mark_progress_na}` applied) per [Status vocabulary](../../resources/planning-readme.md#status-vocabulary) — otherwise Apply [sync-progress-status](./sync-progress-status.md) then commit and push. Scope: this orchestrator post-activity hook only — distinct from [explicit-commit](../version-control/TECHNIQUE.md#explicit-commit), which governs ad-hoc commits outside this hook. ### readme-progress-before-persist diff --git a/meta/techniques/workflow-engine/generate-summary.md b/meta/techniques/workflow-engine/generate-summary.md index 45e177173..a56f85ab0 100644 --- a/meta/techniques/workflow-engine/generate-summary.md +++ b/meta/techniques/workflow-engine/generate-summary.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.0.0 + version: 1.2.0 --- ## Capability @@ -15,7 +15,7 @@ Workflow definition (id, title, outcomes) ### execution_trace -Completed activities, checkpoint decisions, artifacts produced +Completed activities, checkpoint decisions, and artifacts produced. ## Outputs @@ -26,7 +26,6 @@ Completed activities, checkpoint decisions, artifacts produced ## Protocol 1. Draw from `{execution_trace}` to compose the summary sections: workflow id and title, start/completion timestamps, activities completed, key checkpoint decisions, artifacts with paths, outcomes satisfied vs. unmet, follow-up items. Return the assembled markdown as `{completion_summary}`. - > Obtain the execution trace through the `inspect_session` tool — `view: activities` for completed activities, `view: checkpoints` for checkpoint decisions, `view: history` for the event trace, or `view: summary` for all of it — rather than reading `session.json` directly. ## Rules diff --git a/meta/techniques/workflow-engine/read-session.md b/meta/techniques/workflow-engine/read-session.md new file mode 100644 index 000000000..470a3436d --- /dev/null +++ b/meta/techniques/workflow-engine/read-session.md @@ -0,0 +1,32 @@ +--- +metadata: + version: 1.0.0 +--- + +## Capability + +The live session record — its variable bag and its execution trace — for a consumer that reasons over what the session has actually done. + +## Outputs + +### session_state + +The session's variable bag as the server holds it. + +### execution_trace + +Completed activities, checkpoint decisions, artifacts produced, and the event history behind them. + +## Protocol + +1. Read the session through the `inspect_session` tool: `view: variables` yields `{session_state}`; `view: activities`, `view: checkpoints` and `view: history` each yield a slice of `{execution_trace}`, and `view: summary` yields both products in one call. + +## Rules + +### session-file-is-not-a-source + +The session file on disk is the server's own store, not a read surface: it may be sealed, and it lags a call still in flight. Every consumer of the two products above takes them from this operation, so one contract governs what a session read returns. + +### trace-is-not-the-only-witness + +A worker's `activity_complete` envelope holds ground truth from its own user interaction, so where the record and a just-completed envelope disagree on a value an orchestrator decision rests on, apply [dispatch-activity](./dispatch-activity.md#distrust-then-reconcile). diff --git a/meta/techniques/workflow-engine/verify-outcomes.md b/meta/techniques/workflow-engine/verify-outcomes.md index 190851b42..9432e3540 100644 --- a/meta/techniques/workflow-engine/verify-outcomes.md +++ b/meta/techniques/workflow-engine/verify-outcomes.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.2.0 + version: 1.4.0 --- ## Capability @@ -13,9 +13,13 @@ Compare a workflow's declared `outcomes` against state and identify gaps. Array of expected outcome strings to evaluate. -### state +### session_state -Current variable state and completed-activities trace +The session's variable bag. + +### execution_trace + +Completed activities and the event history behind them. ## Outputs @@ -26,5 +30,4 @@ Array of unsatisfied outcomes ## Protocol 1. Resolve the outcome list to evaluate: prefer a non-empty `{outcomes}` binding when supplied; otherwise fall back to the calling activity's declared `outcome:` list. Outcome strings are plain declarative prose — never encode or parse conditional predicates inside them. When a producing step was structurally gated out on the path taken, skip the outcomes that step would have satisfied rather than reporting them as unmet gaps. -2. For each entry in that list, evaluate satisfaction against state variables, artifact presence in `planning_folder_path`, and the completed-activities trace; collect every unmet item into `{gaps}`. - > Read the state variables and completed-activities trace through the `inspect_session` tool (`view: variables` and `view: activities`, or `view: summary` for both) rather than reading `session.json` directly. When `inspect_session` disagrees with a just-completed worker envelope for a critical path, prefer the envelope and planning-folder evidence (same reconcile stance as [dispatch-activity](./dispatch-activity.md#distrust-then-reconcile)). +2. For each entry in that list, evaluate satisfaction against `{session_state}`, artifact presence in `planning_folder_path`, and `{execution_trace}`; collect every unmet item into `{gaps}`. diff --git a/meta/workflow.yaml b/meta/workflow.yaml index 1ebf255c1..ce39ab368 100644 --- a/meta/workflow.yaml +++ b/meta/workflow.yaml @@ -1,6 +1,6 @@ $schema: ../../schemas/workflow.schema.json id: meta -version: 5.12.0 +version: 5.14.0 title: Meta Workflow description: Top-level lifecycle workflow that orchestrates client workflow sessions. Excluded from list_workflows — bootstrap navigates here directly. author: m2ux @@ -53,13 +53,7 @@ variables: defaultValue: false - name: target_workflow_outcomes type: string - description: The client workflow's declared outcomes, read by verify-outcomes during end-workflow close-out - - name: client_state - type: string - description: The dispatched client workflow's final variable state, read by verify-outcomes during end-workflow - - name: client_trace - type: string - description: The dispatched client workflow's execution trace, read by generate-summary during end-workflow + description: The client workflow's own outcome list, seeded in its bag - name: workflow_match_ambiguous type: boolean description: Whether the user request matched multiple workflows — gates the workflow-selection checkpoint in discover-session diff --git a/work-package/activities/13-submit-for-review.yaml b/work-package/activities/13-submit-for-review.yaml index f401ff618..5dfdb62d7 100644 --- a/work-package/activities/13-submit-for-review.yaml +++ b/work-package/activities/13-submit-for-review.yaml @@ -1,5 +1,5 @@ id: submit-for-review -version: 1.14.0 +version: 1.15.0 name: Submit for Review description: Submit the work for review — PR review lifecycle normally; a verified private-remote push in stealth mode. required: true @@ -18,8 +18,22 @@ steps: operator: == value: true - kind: technique - id: publish-review-artifacts - technique: publish-review-artifacts + id: resolve-artifact-publish + technique: resolve-artifact-publish + condition: + type: simple + variable: is_review_mode + operator: == + value: true + - kind: technique + id: commit-review-artifacts + technique: + name: manage-git::artifact-commits + inputs: + activity_name: submit-for-review + issue_key: issue_number + files: publishable_files + branch: artifact_publish_ref condition: type: simple variable: is_review_mode diff --git a/work-package/activities/14-complete.yaml b/work-package/activities/14-complete.yaml index dd21d30e2..e2da7ebf8 100644 --- a/work-package/activities/14-complete.yaml +++ b/work-package/activities/14-complete.yaml @@ -1,5 +1,5 @@ id: complete -version: 1.7.0 +version: 1.9.0 name: Complete Work Package description: Wrap up the work package after PR merge (or after review-mode close-out). required: true @@ -66,6 +66,9 @@ steps: variable: is_review_mode operator: "!=" value: true + - kind: technique + id: read-session + technique: workflow-engine::read-session - kind: technique id: conduct-retrospective technique: conduct-retrospective::retrospective @@ -81,12 +84,23 @@ steps: - action: validate target: broken_artifact_links == [] message: "Planning artifacts carry links that do not resolve: {broken_artifact_links}. Repoint each to a target that resolves at the publish ref, then re-run." + - kind: technique + id: resolve-close-out-publish + technique: resolve-artifact-publish + condition: + type: simple + variable: is_review_mode + operator: == + value: true - kind: technique id: publish-close-out-artifacts technique: - name: publish-review-artifacts + name: manage-git::artifact-commits inputs: - publishing_activity: complete + activity_name: complete + issue_key: issue_number + files: publishable_files + branch: artifact_publish_ref condition: type: simple variable: is_review_mode diff --git a/work-package/activities/README.md b/work-package/activities/README.md index f0aa522be..4a638b4c3 100644 --- a/work-package/activities/README.md +++ b/work-package/activities/README.md @@ -366,11 +366,10 @@ Definition: [`13-submit-for-review.yaml`](./13-submit-for-review.yaml) ```mermaid graph TD entryNode(["Entry"]) --> reviewMode{"Review mode?"} - reviewMode -->|"yes"| consolidate["Consolidate review findings"] - consolidate --> genSummary["Generate review summary"] - genSummary --> cpSummaryApproval{"review-summary-approval checkpoint"} - cpSummaryApproval --> postReview["Post PR review"] - postReview --> awaitReview + reviewMode -->|"yes"| consolidate["Consolidate review findings → resolve publish ref → commit artifacts → generate review summary"] + consolidate --> cpSummaryApproval{"review-summary-approval checkpoint"} + cpSummaryApproval --> persistSummary["Persist review summary → post PR review"] + persistSummary --> awaitReview reviewMode -->|"no"| cpDco{"dco-sign-off-confirmation checkpoint"} cpDco --> stealthMode{"Stealth mode?"} @@ -431,7 +430,7 @@ graph TD docsGate -->|"yes"| retrospective["Conduct the retrospective into COMPLETE.md, then verify planning-folder links"] retrospective --> publishGate{"Review mode?"} - publishGate -->|"yes"| republish["Publish close-out artifacts on the publish branch"] + publishGate -->|"yes"| republish["Resolve the publish ref, then commit the close-out artifacts onto it"] publishGate -->|"no"| removeWorktree republish --> removeWorktree["Remove component worktree (when this run created one)"] removeWorktree --> selectNext["Select next work package"] diff --git a/work-package/resources/pr-description.md b/work-package/resources/pr-description.md index 71e0a7a6d..b24cc2c2d 100644 --- a/work-package/resources/pr-description.md +++ b/work-package/resources/pr-description.md @@ -2,7 +2,7 @@ name: pr-description description: PR description templates and link-row rendering forms. metadata: - version: 1.6.0 + version: 1.8.0 order: 12 legacy_id: 12 --- @@ -140,9 +140,11 @@ Optional sections (add when applicable): `## Migration Notes` (required steps fo **Standard link row** (Issue = the GitHub issue in the target repo, never the Jira ticket): ```markdown -🐛 [Issue]({TARGET_REPO_URL}/issues/{GITHUB_ISSUE_NUMBER}) 📐 [Engineering]({ENG_REPO_URL}/blob/{ENG_BRANCH}/.engineering/artifacts/planning/{PLANNING_FOLDER}/README.md) +🐛 [Issue]({TARGET_REPO_URL}/issues/{GITHUB_ISSUE_NUMBER}) 📐 [Engineering]({ENG_REPO_URL}/blob/{ENG_BRANCH}/{ENG_PLANNING_PATH}/{PLANNING_FOLDER}/README.md) ``` +`{ENG_PLANNING_PATH}` is the planning root relative to the root of the checkout `{ENG_BRANCH}` belongs to, so it carries the `.engineering/` segment only when the artifacts live directly in that checkout. + **Issue-skipped placeholder** (when `issue_skipped == true` — the line is rendered, italicised, no link, so reviewers can tell the omission was intentional): ```markdown @@ -156,3 +158,35 @@ _Jira: [{JIRA_ISSUE_KEY}](https://{JIRA_DOMAIN}/browse/{JIRA_ISSUE_KEY})_ ``` ADR and test-plan links are added to the row when those artifacts exist (see [architecture-review](architecture-review.md), [test-plan](test-plan.md)). + +## Rules + +Conformance criteria for a rendered body. Each is evaluated against the rendered text and yields one finding per failure, named by its heading here. + +### Mandated sections present + +Every section the selected template variant mandates appears in the rendered body as a literal heading, checked by name — each `## ` the variant requires, plus the Issue and Engineering link row. `Migration Notes` and `Screenshots` are never required. A missing section is a finding naming that section, and the per-section criteria below do not substitute for this one: a body that omits a section passes them vacuously. + +### Summary length + +The Summary section is one or two sentences, leads with the outcome, and carries measurable impact where a figure is known. + +### Engineering link present + +The Engineering link is present and resolves to a committed file on the remote. Its ref and repository come from the checkout holding the planning folder, never from the host repo's when that folder is a checkout of its own. + +### Issue line present + +The Issue line is present. When `issue_skipped` is true it renders the [Issue-skipped placeholder](#link-row-forms) rather than dropping the line or carrying a fabricated number. + +### Changes grouped by component + +The Changes section groups bullets by component, the component name in bold — not by Conventional Commits header and not by commit message. + +### Changes carry no file list + +The Changes section does not enumerate file paths. File-level detail is already in the PR's Files-changed tab. + +### Changes carry no code + +The Changes section is plain-language bullets saying what changed and why: no fenced blocks, no snippets, no pasted signatures, and no inline code beyond an unavoidable bare identifier. The diff is the source of truth for code. diff --git a/work-package/resources/review-mode.md b/work-package/resources/review-mode.md index 2c3abbbb3..89737187e 100644 --- a/work-package/resources/review-mode.md +++ b/work-package/resources/review-mode.md @@ -2,7 +2,7 @@ name: review-mode description: Guidelines for using the work-package workflow in review mode to conduct structured PR reviews. Covers detection, adapted workflow behavior, and output generation. Organized by review category for per-section delivery to the technique that renders that category. metadata: - version: 1.13.0 + version: 1.14.0 order: 24 legacy_id: 24 --- @@ -38,10 +38,10 @@ The summary header carries `PR`, `Plan`, `Reviewers`, `Reports`, and `Date` fiel **Reports list:** The header includes a `Reports` field naming each report the summary links to, as hyperlinks. Each entry links the report by name to its artifact, under the engineering-artifacts base URL: ``` -https://github.com/{ENG_REPO_OWNER}/{ENG_REPO_NAME}/blob/{ARTIFACT_PUBLISH_REF}/artifacts/planning/{PLANNING_FOLDER}/ +https://github.com/{ENG_REPO_OWNER}/{ENG_REPO_NAME}/blob/{ARTIFACT_PUBLISH_REF}/{ENG_PLANNING_PATH}/{PLANNING_FOLDER}/ ``` -`{ARTIFACT_PUBLISH_REF}` is the **branch** the linked artifacts are published on, so the linked tree carries whatever the run adds after the link is written — close-out, retrospective, session trace and follow-ups all land on that branch and resolve from the same URL. Resolve `{ENG_REPO_OWNER}` and `{ENG_REPO_NAME}` from the artifacts checkout's remote; never hardcode `main`. The path after the ref is relative to the root of the checkout that ref belongs to: `artifacts/planning/…` when `.engineering/` is itself a checkout, and `.engineering/artifacts/planning/…` when the artifacts live directly in the product checkout. The set of reports and their artifact filenames are supplied by the rendering step — one entry per review category the run produced — not fixed by this template. +`{ARTIFACT_PUBLISH_REF}` is the **branch** the linked artifacts are published on, so the linked tree carries whatever the run adds after the link is written — close-out, retrospective, session trace and follow-ups all land on that branch and resolve from the same URL. Resolve `{ENG_REPO_OWNER}` and `{ENG_REPO_NAME}` from the engineering checkout's remote; never hardcode `main`. `{ENG_PLANNING_PATH}` is relative to the root of the checkout that ref belongs to: `artifacts/planning` when `.engineering/` is itself a checkout, and `.engineering/artifacts/planning` when the artifacts live directly in the product checkout. The set of reports and their artifact filenames are supplied by the rendering step — one entry per review category the run produced — not fixed by this template. **Ref split — engineering artifacts by branch, reviewed code by sha:** every engineering-artifact link (`Plan`, `Reports`, a designator's report anchor) carries `{ARTIFACT_PUBLISH_REF}`. Every citation of the reviewed code carries the reviewed head sha instead, as a permanent blob URL under the reviewed repository: diff --git a/work-package/techniques/conduct-retrospective/retrospective.md b/work-package/techniques/conduct-retrospective/retrospective.md index 6ea8c780f..741fbfd31 100644 --- a/work-package/techniques/conduct-retrospective/retrospective.md +++ b/work-package/techniques/conduct-retrospective/retrospective.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.4.0 + version: 1.5.0 --- ## Capability @@ -25,6 +25,10 @@ Path to the planning folder where the final outcome, session-trace, and retrospe *(optional)* Opaque trace tokens accumulated across the run. +### execution_trace + +Completed activities, checkpoint decisions, and the event history behind them. + ## Outputs ### retrospective_document @@ -44,7 +48,7 @@ Lean mechanical summary of resolved trace events (dispatch counts, tool counts, ### 1. Capture History -- If metadata repository exists, capture session history via `inspect_session` (same stance as [generate-summary](../../../meta/techniques/workflow-engine/generate-summary.md) / [verify-outcomes](../../../meta/techniques/workflow-engine/verify-outcomes.md) — not by reading `session.json`). +- If metadata repository exists, capture session history from `{execution_trace}`. ### 2. Resolve Session Trace diff --git a/work-package/techniques/conduct-retrospective/select-next.md b/work-package/techniques/conduct-retrospective/select-next.md index bef896df3..782d47b36 100644 --- a/work-package/techniques/conduct-retrospective/select-next.md +++ b/work-package/techniques/conduct-retrospective/select-next.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.0.0 + version: 1.1.0 --- ## Capability @@ -13,6 +13,10 @@ Identify the next work package and prepare context for the transition. Path to the current work package's planning folder, read for follow-up items and carried context that inform what the next work package should be. +### execution_trace + +*(optional)* Completed activities and the event history behind them. + ## Outputs ### next_work_package_context @@ -24,4 +28,4 @@ The identified next work package (when applicable) together with the context pre ### 1. Select Next - Identify next work package if applicable. -- Prepare context for transition. When carried context depends on session record, use `inspect_session` per [generate-summary](../../../meta/techniques/workflow-engine/generate-summary.md) / [verify-outcomes](../../../meta/techniques/workflow-engine/verify-outcomes.md). +- Prepare context for transition. Carried context that depends on the session record comes from `{execution_trace}`. diff --git a/work-package/techniques/manage-artifacts/TECHNIQUE.md b/work-package/techniques/manage-artifacts/TECHNIQUE.md index 93bb6524e..af8560420 100644 --- a/work-package/techniques/manage-artifacts/TECHNIQUE.md +++ b/work-package/techniques/manage-artifacts/TECHNIQUE.md @@ -1,6 +1,6 @@ --- metadata: - version: 3.4.0 + version: 3.5.0 --- ## Capability @@ -79,10 +79,6 @@ Specific, plain technical language: no vague descriptions ("various improvements Artifact filenames are prefixed with the server-provided `artifactPrefix`. Techniques declare bare names (e.g., `code-review.md`); the prefix is applied at write time (e.g., `09-code-review.md`). This groups related artifacts and sorts them in workflow order. -### committed-to-parent - -Planning artifacts are regular files in the parent repo (`.engineering/artifacts/`). They MUST be committed and pushed to the parent repo before any PR or issue references them via URL, otherwise the link will 404. - ### push-before-linking -Any engineering link included in a PR body (📐 Engineering) MUST resolve to a committed file on the remote. Commit and push the planning folder BEFORE creating or updating the PR. +Any engineering link — in a PR body (📐 Engineering), an issue, or a posted review — MUST resolve to a committed file on the remote, or the reader gets a 404. Commit and push the planning folder BEFORE writing a URL that points into it, via [manage-git](../manage-git/TECHNIQUE.md)::[artifact-commits](../manage-git/artifact-commits.md), which owns the checkout the commit lands in. diff --git a/work-package/techniques/publish-review-artifacts.md b/work-package/techniques/resolve-artifact-publish.md similarity index 53% rename from work-package/techniques/publish-review-artifacts.md rename to work-package/techniques/resolve-artifact-publish.md index 14a3257eb..2d9d5cbea 100644 --- a/work-package/techniques/publish-review-artifacts.md +++ b/work-package/techniques/resolve-artifact-publish.md @@ -1,11 +1,11 @@ --- metadata: - version: 1.3.0 + version: 1.0.0 --- ## Capability -Commit and push review-linked planning artifacts to the engineering-checkout ref the consolidated review links, emitting the publish ref for hyperlink construction. +Resolve the engineering checkout's publish branch and the planning-folder files that ride on it, for artifact hyperlink construction. ## Inputs @@ -17,29 +17,23 @@ Path to the planning folder whose artifacts the consolidated review links (`READ Path to the product repo root (monorepo or standalone); the `.engineering/` artifacts directory sits under it. -### publishing_activity - -Name recorded on the publish commit, identifying which activity's artifacts it carries. - -#### default - -`submit-for-review` - ## Outputs ### artifact_publish_ref The engineering checkout's branch name — the ref engineering-artifact hyperlinks resolve against. +### publishable_files + +Every changed file under `{planning_folder_path}`, including `README.md`, the linked report artifacts, `review-summary.md`, `session.json` and `.session-token`. ## Protocol 1. Resolve `{$eng_git_dir}`: `{host_repo_path}/.engineering` when that path is a git checkout (submodule or nested clone); otherwise `{host_repo_path}`. Resolve `{$eng_branch}`: `git -C {eng_git_dir} branch --show-current` — never hardcode `main`. -2. Apply [manage-git::artifact-commits](./manage-git/artifact-commits.md) for ALL changed files under `{planning_folder_path}` (including `README.md`, linked report artifacts, `review-summary.md`, `session.json`, and `.session-token`) with `branch` = `{eng_branch}`, `activity_name` = `{publishing_activity}`, and `issue_key` = `{issue_number}`. That op stages, commits and pushes inside the engineering checkout, so the branch tip carries these artifacts. -3. Emit `{eng_branch}` as `{artifact_publish_ref}`. +2. Collect every changed path under `{planning_folder_path}` as `{publishable_files}` (`git -C {eng_git_dir} status --porcelain` restricted to that folder), and emit `{eng_branch}` as `{artifact_publish_ref}`. ## Rules ### publish-ref-is-a-branch -The emitted ref is the branch, never a commit SHA. The planning folder keeps growing after a review is posted — close-out, retrospective, session trace and follow-ups all arrive later — so a reader following a branch link sees the current tree while a reader following a sha link sees the tree as it stood before those files existed. Re-running this op on a later activity refreshes the branch tip without changing any link already posted. +The emitted ref is the branch, never a commit SHA. The planning folder keeps growing after a review is posted — close-out, retrospective, session trace and follow-ups all arrive later — so a reader following a branch link sees the current tree while a reader following a sha link sees the tree as it stood before those files existed. Re-resolving on a later activity refreshes the branch tip without changing any link already posted. diff --git a/work-package/techniques/update-pr/TECHNIQUE.md b/work-package/techniques/update-pr/TECHNIQUE.md index 124e430e5..c712954f7 100644 --- a/work-package/techniques/update-pr/TECHNIQUE.md +++ b/work-package/techniques/update-pr/TECHNIQUE.md @@ -1,6 +1,6 @@ --- metadata: - version: 2.5.1 + version: 2.7.0 --- ## Capability @@ -71,13 +71,7 @@ Typical binds: `plan-prepare` → `initial`; `strategic-review` and `submit-for- ### pr-body-conformance -- all-mandated-sections-present: Every section the selected pr-description template variant mandates is present in the rendered body as a literal heading. The mandated sections are defined in the resource — [Template (Initial)](../../resources/pr-description.md#template-initial) or [Template (Final)](../../resources/pr-description.md#template-final) — and are checked by name (e.g. `grep -F` each `## ` the template requires, plus the Issue/Engineering link row). Optional sections (`Migration Notes`, `Screenshots`) are never required. A missing mandated section is a finding naming that section — the intra-section rules below do not substitute for this check, since a body that omits a section passes them vacuously. -- summary-max-two-sentences: Summary section is 1-2 sentences, leads with the outcome, and includes measurable impact when available. -- engineering-link-mandatory: Engineering link is present, resolved from the parent repo's `git remote get-url origin` and current `git branch --show-current`, and resolves to a committed file on the remote. -- issue-link-or-explicit-placeholder: Issue line is present. When `issue-skipped == true`, render `🐛 _Issue: skipped_` as an explicit placeholder rather than dropping the line or fabricating a number. -- no-commit-headings-in-changes: Changes section groups bullets by component (bold component name), not by Conventional Commits header or commit message. -- no-files-changed-list: Changes section does not enumerate file paths. File-level detail belongs in the PR's Files-changed tab. -- no-code-in-changes: Changes section is plain-language summary bullets describing what changed and why; no fenced code blocks, code snippets, or pasted signatures, and no inline code beyond unavoidable bare identifiers. The diff is the source of truth for code. +A rendered body satisfies every criterion in [Rules](../../resources/pr-description.md#rules), which is their home — the guide that lays out the body owns what a conforming body looks like. Each failure is one finding named by the criterion it breaks. ### draft-first diff --git a/work-package/techniques/update-pr/create-pr.md b/work-package/techniques/update-pr/create-pr.md index 379bf10c1..e6a300ef6 100644 --- a/work-package/techniques/update-pr/create-pr.md +++ b/work-package/techniques/update-pr/create-pr.md @@ -32,7 +32,7 @@ URL to the PR ### 1. Prepare PR Inputs -- BEFORE creating the PR: honor [push-before-linking](../manage-artifacts/TECHNIQUE.md#push-before-linking) / [committed-to-parent](../manage-artifacts/TECHNIQUE.md#committed-to-parent) for `{planning_folder_path}`. +- BEFORE creating the PR: honor [push-before-linking](../manage-artifacts/TECHNIQUE.md#push-before-linking) for `{planning_folder_path}`. - Compose the PR title and body using the [Template (Initial)](../../resources/pr-description.md#template-initial). Reference `{issue_number}` per `{issue_platform}` (GitHub `#N` vs Jira `KEY-N`). ### 2. Create Draft PR diff --git a/work-package/techniques/update-pr/render.md b/work-package/techniques/update-pr/render.md index 33a93b1bb..5e216db35 100644 --- a/work-package/techniques/update-pr/render.md +++ b/work-package/techniques/update-pr/render.md @@ -52,5 +52,5 @@ The rendered PR description body now live on the `{pr_number}` PR — composed f - `{$target_repo_url}`: `git -C {target_path} remote get-url origin`, strip the `.git` suffix, convert SSH form to HTTPS (`git@github.com:org/repo.git` → `https://github.com/org/repo`). - `{$eng_repo_url}`: same remote commands against `{eng_git_dir}`. Target and engineering remotes may differ. - `{$eng_branch}`: `git -C {eng_git_dir} branch --show-current` — do NOT assume `main`; planning artifacts may live on another branch. When `{eng_git_dir}` is `{host_repo_path}`, the Engineering link path includes `/.engineering/artifacts/planning/…`; when `{eng_git_dir}` is the eng checkout itself, the path is `/artifacts/planning/…` relative to that remote. The link must resolve to a committed file on the remote (manage-artifacts.push-before-linking). -4. Compose the link row per the [link-row forms](../../resources/pr-description.md#link-row-forms): the Issue link always present, pointing at the GitHub issue in the target repo via the `github_issue_number` variable — never the Jira key, never a guessed number; when `issue_skipped` is true, render the literal `🐛 _Issue: skipped_` placeholder per `rules.pr-body-conformance.issue-link-or-explicit-placeholder`. The Engineering link is always present on the same line. When `issue_platform` is `jira` and a `jira_issue_key` was captured, append the Jira ticket as the secondary reference line. Add ADR and test-plan links when those artifacts exist. +4. Compose the link row per the [link-row forms](../../resources/pr-description.md#link-row-forms): the Issue link always present, pointing at the GitHub issue in the target repo via the `github_issue_number` variable — never the Jira key, never a guessed number; when `issue_skipped` is true, render the [Issue-skipped placeholder](../../resources/pr-description.md#link-row-forms). The Engineering link is always present on the same line. When `issue_platform` is `jira` and a `jira_issue_key` was captured, append the Jira ticket as the secondary reference line. Add ADR and test-plan links when those artifacts exist. 5. Update the `{pr_number}` PR description via the GitHub REST API — write the body to a file and `gh api repos///pulls/ -X PATCH -F body=@`; do NOT use `gh pr edit`, whose GraphQL query fails on the Projects Classic deprecation. If the PR cannot be found because `{pr_number}` does not exist, verify the PR number and check `gh` auth before retrying. diff --git a/work-package/techniques/update-pr/verify-body.md b/work-package/techniques/update-pr/verify-body.md index 5221c74b3..7a0e23a43 100644 --- a/work-package/techniques/update-pr/verify-body.md +++ b/work-package/techniques/update-pr/verify-body.md @@ -1,6 +1,6 @@ --- metadata: - version: 1.1.1 + version: 1.2.0 --- ## Capability @@ -17,7 +17,7 @@ Final-template PR body markdown ([Template (Final)](../../resources/pr-descripti ### body_conforms -True when the rendered body passes every rule in `pr-body-conformance` against the [Final template](../../resources/pr-description.md#template-final) mandated sections and link row; false otherwise. +True when the rendered body satisfies every criterion in [Rules](../../resources/pr-description.md#rules); false otherwise. ### body_findings @@ -27,6 +27,6 @@ List of `{ rule_id, detail }` entries, one per failed conformance rule, in rule- ## Protocol 1. Render the Final-template body to `/tmp/pr-body.md`. -2. Evaluate `all-mandated-sections-present` first: check that each mandated section heading for the selected template variant appears literally in the rendered text, per the mandates of [Template (Initial)](../../resources/pr-description.md#template-initial) or [Template (Final)](../../resources/pr-description.md#template-final) (e.g. `grep -F` each `## ` the template variant requires, plus the Issue/Engineering link row). Append a `{ rule_id: all-mandated-sections-present, detail }` finding naming every mandated section that is absent. Do not treat a matching `## Summary` as evidence the remaining sections exist. -3. Evaluate each remaining rule in `pr-body-conformance` against the rendered text. For each failure append `{ rule_id, detail }` to `{body_findings}`. +2. Evaluate [Mandated sections present](../../resources/pr-description.md#mandated-sections-present) first, against the variant's own template — [Template (Initial)](../../resources/pr-description.md#template-initial) or [Template (Final)](../../resources/pr-description.md#template-final). Append one finding naming every mandated section that is absent. +3. Evaluate each remaining criterion in [Rules](../../resources/pr-description.md#rules) against the rendered text. For each failure append `{ rule_id, detail }` to `{body_findings}`. 4. Set `{body_conforms}` = true when `{body_findings}` is empty after all rules are evaluated; false otherwise. diff --git a/work-package/workflow.yaml b/work-package/workflow.yaml index 819d29ce1..08212e8bf 100644 --- a/work-package/workflow.yaml +++ b/work-package/workflow.yaml @@ -1,6 +1,6 @@ $schema: ../../schemas/workflow.schema.json id: work-package -version: 3.37.0 +version: 3.40.0 title: Work Package Implementation Workflow description: Defines how to plan and implement ONE work package from inception to merged PR. A work package is a discrete unit of work such as a feature, bug-fix, enhancement, refactoring, or any other deliverable change. For multiple related work packages, use the work-packages workflow to create a roadmap first. Also supports review mode for auditing an existing PR or implementation end-to-end. author: m2ux @@ -502,11 +502,11 @@ variables: defaultValue: "" - name: body_conforms type: boolean - description: "True once the rendered PR body has passed every rule in update-pr::rules.pr-body-conformance." + description: "True once the rendered PR body satisfies every conformance criterion in the pr-description guide." defaultValue: false - name: body_findings type: array - description: List of pr-body-conformance violations. + description: List of PR-body conformance violations. defaultValue: [] - name: body_override_recorded type: boolean diff --git a/workflow-design/resources/anti-patterns.md b/workflow-design/resources/anti-patterns.md index 1518d4fd7..2fcba7ebf 100644 --- a/workflow-design/resources/anti-patterns.md +++ b/workflow-design/resources/anti-patterns.md @@ -1780,3 +1780,27 @@ Protocol restates a tool parameter's shape, which the tool's own schema already **Do not flag:** The call signature naming which arguments a step passes (`next_activity { session_index, activity_id, step_manifest }`) — that is routing, not shape. What the caller does with the response. A workflow-specific constraint on an argument's *value* rather than its form, such as relaying a worker's map verbatim; and an obligation the schema cannot express, such as which dispatches must carry the argument at all. **Fix:** Keep the obligation and the reason; drop the shape. The schema is its one home ([Match the Harness Surface](./design-principles.md#21-match-the-harness-surface), [One Authoritative Home](./design-principles.md#6-one-authoritative-home)), and a restatement drifts from it — a Protocol bullet describing "two string fields" contradicts a schema that also accepts a keyed object for multi-output steps, and the caller cannot tell which governs. + +### AP-136. phase-cited-by-ordinal + +"the primitive step 5 resolves for the layout" / "[render](./render.md) step 3 owns that resolution" + +A durable reference identifies a Protocol phase by its position, so it keeps resolving after a renumber and points at work it no longer names. + +**Detect:** A rule, I/O description, Capability, resource body, README, or another technique's Protocol cites a phase of some `## Protocol` by ordinal — "step N", "phase N", "the Nth step" — rather than by the technique or op that owns it. An ordinal is not a symbol: it survives insertion, deletion and reordering by silently addressing whichever phase now holds that index, so the claim goes false with nothing failing. Test: insert one phase above the cited one and re-read the citing sentence; if it now names the wrong work, flag it. + +**Do not flag:** Ordinals inside the same `## Protocol` that owns the numbering, where the phases and the reference move in one edit. A link to the phase's heading anchor, which fails a guard rather than drifting when the heading changes. Rules cited by dotted address — a rule name is not a position (`dotted-rule-address`). An ordinal that is part of a declared id, heading text, or quoted output rather than a citation. + +**Fix:** Cite the owner, not the index — name the technique or op holding the phase and let the reader find it there; anchor the heading where the citation genuinely needs that one phase. Where the pointer exists only to explain how the cited work happens, the citing invariant rarely needs it: delete the pointer and keep the constraint. See also `no-rule-protocol-restatement`, `anchored-protocol-references`, `stale-restatement-after-change`. + +### AP-137. unowned-harness-capability + +"capture session history via `inspect_session` (same stance as [generate-summary] / [verify-outcomes])" + +Several techniques reach a harness capability directly because no operation owns it, so each re-derives the call and the newest cites a fellow caller as though a caller were a home. + +**Detect:** One harness/MCP tool is named for the same capability in two or more technique bodies, and no operation in the tree declares that capability's product as its own Outputs. Signals: the tool's permitted argument values enumerated at more than one site; a citation whose target is another *consumer* of the tool rather than an owner of the capability — the bridge phrasings `single-rule-authority` lists, pointing sideways. Test: name the operation a caller would bind to obtain the value. If no file answers, the capability is unowned and every site is a private re-derivation that drifts on its own. + +**Do not flag:** A single call site — one consumer is not duplication, and inventing a wrapper against a hypothetical second is premature (`duplicate-shared-capability`). Sites that already bind or Apply a wrapping op, and the wrapper itself, where naming the tool is the point (`canonical-technique-reference`). Surfaces whose domain is the harness — engine, conduct, bootstrap and agent-entry prompts. Distinct callers of one tool for genuinely different capabilities. + +**Fix:** Author the operation that owns the capability, declaring its product on `## Outputs`; bind it as an activity step ahead of its consumers and let them declare that product as an input — never a Protocol `Apply` from each consumer (`pass-orchestration-in-technique`). Repoint every sideways citation at the owner. See also `no-duplicated-guidance`, `tool-contract-restated-in-protocol`.