diff --git a/cicd-pipeline-security-audit/techniques/execute-sub-agent.md b/cicd-pipeline-security-audit/techniques/execute-sub-agent.md index 3ebc19201..74199d5b7 100644 --- a/cicd-pipeline-security-audit/techniques/execute-sub-agent.md +++ b/cicd-pipeline-security-audit/techniques/execute-sub-agent.md @@ -56,7 +56,7 @@ per-file, per-pattern scan confirmation ### 1. Bootstrap - Inherit the dispatched session and load the assigned activity definition with its steps. - - If the workflow-server is unavailable or the activity cannot be loaded, fall back to the prompt instructions provided by the orchestrator and note that in the output. + > If the workflow-server is unavailable or the activity cannot be loaded, fall back to the prompt instructions provided by the orchestrator and note that in the output. ### 2. Execute Steps diff --git a/meta/techniques/github-cli-protocol/assign-issue.md b/meta/techniques/github-cli-protocol/assign-issue.md index 1588db23b..778f15ce2 100644 --- a/meta/techniques/github-cli-protocol/assign-issue.md +++ b/meta/techniques/github-cli-protocol/assign-issue.md @@ -27,4 +27,4 @@ Assignee login, or the literal `@me` for the authenticated user. 1. Apply [resolve-repo-coordinates](./resolve-repo-coordinates.md). 2. `gh api repos/{owner}/{repo}/issues/{issue_number}/assignees -f "assignees[]={$assignee_login}"`. - - When the issue is already assigned to `{$assignee_login}`, this is a no-op — skip silently. + > When the issue is already assigned to `{$assignee_login}`, this is a no-op — skip silently. diff --git a/meta/techniques/github-cli-protocol/post-pr-review.md b/meta/techniques/github-cli-protocol/post-pr-review.md index ae7d22baa..78c6d2132 100644 --- a/meta/techniques/github-cli-protocol/post-pr-review.md +++ b/meta/techniques/github-cli-protocol/post-pr-review.md @@ -45,11 +45,11 @@ The body the API holds for `{review_id}` as it stood before this call's write. U 1. Apply [resolve-repo-coordinates](./resolve-repo-coordinates.md). 2. Emit `{live_review_body}` as the body the API currently holds, so a caller can reconcile against it before it is replaced. A body read after the write is the write. - > When `{review_id}` is supplied: `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id} --jq .body`. - > Otherwise there is no review to read; leave `{live_review_body}` unset. + > - When `{review_id}` is supplied: `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id} --jq .body`. + > - Otherwise there is no review to read; leave `{live_review_body}` unset. ### 2. Post or Replace the Review - Send the body and emit `{review_posted}` true with `{posted_review_id}` naming the review the API accepted. - > Without `{review_id}`: `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews -F body=@ -f event={review_event}` (use `-f body="{body}"` when the body is a single-line string). - > With `{review_id}`: `gh api --method PUT repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id} -F body=@`, which keeps the review's id, state and comment thread. A second POST leaves two verdicts on one pull request. + > - Without `{review_id}`: `gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews -F body=@ -f event={review_event}` (use `-f body="{body}"` when the body is a single-line string). + > - With `{review_id}`: `gh api --method PUT repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id} -F body=@`, which keeps the review's id, state and comment thread. A second POST leaves two verdicts on one pull request. diff --git a/meta/techniques/gitnexus-operations/analyze.md b/meta/techniques/gitnexus-operations/analyze.md index 1e4805f75..16ef11a72 100644 --- a/meta/techniques/gitnexus-operations/analyze.md +++ b/meta/techniques/gitnexus-operations/analyze.md @@ -32,9 +32,9 @@ Post-analyze symbol / relationship / process counts emitted by the CLI ### 2. Run Analyze -- Otherwise run `npx gitnexus analyze` (or `npx gitnexus analyze --force` when `{force_rebuild}` is true) inside `{repo_path}`. The CLI exits non-zero on failure; surface its stderr. - - If `npx gitnexus` resolves to no binary (the gitnexus package is not installed), install it via `npm install -g gitnexus` (or the project-local equivalent), then retry. - - If the analyze CLI returns non-zero — typically a parser error inside the target codebase or an unsupported language — read the stderr; if it identifies a single offending file, exclude or fix it. For corrupted index state, retry with `force_rebuild=true`. +- Otherwise run `npx gitnexus analyze` (or `npx gitnexus analyze --force` when `{force_rebuild}` is true) inside `{repo_path}`. The CLI exits non-zero on failure; surface its stderr. + > - If `npx gitnexus` resolves to no binary (the gitnexus package is not installed), install it via `npm install -g gitnexus` (or the project-local equivalent), then retry. + > - If the analyze CLI returns non-zero — typically a parser error inside the target codebase or an unsupported language — read the stderr; if it identifies a single offending file, exclude or fix it. For corrupted index state, retry with `force_rebuild=true`. ### 3. Signal and Verify diff --git a/meta/techniques/workflow-engine/commit-and-persist.md b/meta/techniques/workflow-engine/commit-and-persist.md index bc51e84ed..cbde72167 100644 --- a/meta/techniques/workflow-engine/commit-and-persist.md +++ b/meta/techniques/workflow-engine/commit-and-persist.md @@ -25,9 +25,9 @@ Activity that just completed. 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:** 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. + > - 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. 7. Emit the run status in the shape [run-status-shape](./TECHNIQUE.md#run-status-shape) declares. This is the last phase, after the push is confirmed, so every link the emission publishes points at an artifact the remote already holds. diff --git a/meta/techniques/workflow-engine/dispatch-activity.md b/meta/techniques/workflow-engine/dispatch-activity.md index 68da36d8f..2cd77452a 100644 --- a/meta/techniques/workflow-engine/dispatch-activity.md +++ b/meta/techniques/workflow-engine/dispatch-activity.md @@ -46,20 +46,20 @@ Opaque HMAC-signed trace token from the `next_activity` response `_meta.trace_to ## Protocol 1. **Progress in-progress:** Apply [sync-progress-status](./sync-progress-status.md) with `{planning_folder_path}` for the dispatch moment in [Progress Status call sites](../../../meta/resources/planning-readme.md#progress-status-call-sites) (`activity_id={activity_id}`; `{target_status}` from that row / [Status vocabulary](../../../meta/resources/planning-readme.md#status-vocabulary)). Transitions follow [Status transition policy](../../../meta/resources/planning-readme.md#status-transition-policy). - > When `{planning_folder_path}` is unset, skip this phase. - > Publish the mark before the worker spawns, per [dispatch-mark-reaches-the-remote](#dispatch-mark-reaches-the-remote): apply [version-control::commit-regular-files](../version-control/commit-regular-files.md) with `paths` naming the planning folder `README.md` alone, a message stating which activity is entering progress, and `branch` = current. + > - When `{planning_folder_path}` is unset, skip this phase. + > - Publish the mark before the worker spawns, per [dispatch-mark-reaches-the-remote](#dispatch-mark-reaches-the-remote): apply [version-control::commit-regular-files](../version-control/commit-regular-files.md) with `paths` naming the planning folder `README.md` alone, a message stating which activity is entering progress, and `branch` = current. 2. Call `next_activity { session_index, activity_id, step_manifest }`; capture `_meta.trace_token`. - **`step_manifest`:** a dispatch whose activity ran steps carries one manifest entry per completed step — the server validates step completion against it, and reports a gap when it is absent. A first dispatch has no prior worker context to attribute it to, so `agent_id` is omitted here; a continuation names one ([continue-batch](./continue-batch.md)). - **Trace accumulate (required):** when `_meta.trace_token` is present, append it to `trace_tokens[]`. Tokens stay opaque — no routine per-activity `get_trace`. Live `_meta.validation` self-correct remains; do not resolve tokens mid-run (close-out resolve is [resolve-trace-at-close-out](#resolve-trace-at-close-out)). 3. Mint `{worker_agent_id}` for this dispatch per [delivery-keys-on-agent-context](#delivery-keys-on-agent-context), then apply [compose-prompt](./compose-prompt.md) with `{agent_technique}`, `holds_prior_deliveries: false` (a minted identity holds nothing), and `{state}` as substitutions (include `session_index`, `workflow_id`, `activity_id`, and `{worker_agent_id}` as `agent_id`). 4. Apply [harness-compat](../harness-compat/TECHNIQUE.md)::[spawn-agent](../harness-compat/spawn-agent.md) with the composed prompt; await the worker's envelope and return it unchanged as `{worker_result}`. - > When the harness reports the worker ended without returning an envelope, dispatch a fresh worker for the same `{activity_id}`, which mints its own identity. - > When the harness still reports the worker live and what came back is not an accepted result ([reject-partial-worker-result](#reject-partial-worker-result)), apply [harness-compat](../harness-compat/TECHNIQUE.md)::[continue-agent](../harness-compat/continue-agent.md) under `{worker_agent_id}` with explicit instructions to finish what the result left undone and return the envelope. + > - When the harness reports the worker ended without returning an envelope, dispatch a fresh worker for the same `{activity_id}`, which mints its own identity. + > - When the harness still reports the worker live and what came back is not an accepted result ([reject-partial-worker-result](#reject-partial-worker-result)), apply [harness-compat](../harness-compat/TECHNIQUE.md)::[continue-agent](../harness-compat/continue-agent.md) under `{worker_agent_id}` with explicit instructions to finish what the result left undone and return the envelope. 5. Account for this activity, and for any replacement worker dispatched for the same `{activity_id}`, per [account-every-activity](#account-every-activity). 6. Reconcile any critical routing or path variable an orchestrator decision depends on: compare the session record against the just-completed worker's `activity_complete` envelope, and against planning-folder evidence when the two still leave it uncertain ([distrust-then-reconcile](#distrust-then-reconcile)). 7. On `activity_complete`, read `{worker_result.next_activity_id}` and `{worker_result.activity_exit}` as the authoritative next-activity routing, and pass the exit to `next_activity` — the worker resolved both against the activity's exits and the workflow graph via [finalize-activity](./finalize-activity.md). - > On a **blocked** signal from the worker or the harness, apply [sync-progress-status](./sync-progress-status.md) for the blocked moment in [Progress Status call sites](../../../meta/resources/planning-readme.md#progress-status-call-sites) for `{activity_id}` before surfacing or retrying. - > When the path **skips / cancels** an activity without running it, apply [sync-progress-status](./sync-progress-status.md) for the path-skip / cancel moment in [Progress Status call sites](../../../meta/resources/planning-readme.md#progress-status-call-sites) for that activity's rows. + > - On a **blocked** signal from the worker or the harness, apply [sync-progress-status](./sync-progress-status.md) for the blocked moment in [Progress Status call sites](../../../meta/resources/planning-readme.md#progress-status-call-sites) for `{activity_id}` before surfacing or retrying. + > - When the path **skips / cancels** an activity without running it, apply [sync-progress-status](./sync-progress-status.md) for the path-skip / cancel moment in [Progress Status call sites](../../../meta/resources/planning-readme.md#progress-status-call-sites) for that activity's rows. ## Rules diff --git a/meta/techniques/workflow-engine/start-session.md b/meta/techniques/workflow-engine/start-session.md index 6259f6039..ea7ded015 100644 --- a/meta/techniques/workflow-engine/start-session.md +++ b/meta/techniques/workflow-engine/start-session.md @@ -54,8 +54,8 @@ Slug the session is keyed on — minted transitionally when no planning folder w ## Protocol 1. Call `start_session` with `{workflow_id}`, `{agent_id}`, `{repo}`, `{user_request}`, and optional `{planning_folder}`, per the [bootstrap protocol](../../../meta/resources/bootstrap-protocol.md). Omit `context_mode` (or pass `"fresh"`). - > `{repo}` is required on every call, including transient meta when `{planning_folder}` is omitted. - > Pass `{user_request}` verbatim — the server seeds it into the bag and children inherit it, so it reaches downstream agents as state rather than as prose in a spawn prompt. + > - `{repo}` is required on every call, including transient meta when `{planning_folder}` is omitted. + > - Pass `{user_request}` verbatim — the server seeds it into the bag and children inherit it, so it reaches downstream agents as state rather than as prose in a spawn prompt. 2. Save `{session_index}` and `{planning_folder_path}` from the response. Record `{repo}` as bag `{target_repo}` (response echo when present, otherwise the value passed). Do not compose or reconcile the planning path yourself. 3. Call `get_workflow { session_index }` and follow the returned operations bundle. After summarization, re-fetch with the escapes in `workflow-engine.force-full-after-summarization`. diff --git a/ponytail/techniques/apply-ladder.md b/ponytail/techniques/apply-ladder.md index 2f7550709..91e97ba5a 100644 --- a/ponytail/techniques/apply-ladder.md +++ b/ponytail/techniques/apply-ladder.md @@ -34,9 +34,9 @@ The minimal change that solves the problem at the highest reachable [rung](../re - When `{lean_brief}` is present, start from its traced flow, reachable rungs, and safety-floor obligations rather than re-deriving them. - Walk the [rungs](../resources/the-ladder.md#rungs) from the laziest down and take the highest one that solves the understood problem. - Let `{lazy_intensity}` govern how the code is built. - > At `lite`, build what was asked and record the lazier alternative in one line beside it. - > At `full`, hold the ladder as written: highest reachable rung, shortest working diff, shortest explanation. - > At `ultra`, build the minimal version and trim the over-built part of the requirement itself, recording what it trimmed as an open question rather than waiting on an answer that can be defaulted. + > - At `lite`, build what was asked and record the lazier alternative in one line beside it. + > - At `full`, hold the ladder as written: highest reachable rung, shortest working diff, shortest explanation. + > - At `ultra`, build the minimal version and trim the over-built part of the requirement itself, recording what it trimmed as an open question rather than waiting on an answer that can be defaulted. ### 2. Hold the safety floor diff --git a/prism-audit/techniques/audit-finalize/create-detailed-findings.md b/prism-audit/techniques/audit-finalize/create-detailed-findings.md index 631fc4d40..10810c14f 100644 --- a/prism-audit/techniques/audit-finalize/create-detailed-findings.md +++ b/prism-audit/techniques/audit-finalize/create-detailed-findings.md @@ -26,8 +26,8 @@ Filesystem path to the written DETAILED-FINDINGS.md (the detailed-findings docum ### 1. Consolidate Definitive Findings - Read each scope's DEFINITIVE-FINDINGS.md at the `definitive_findings_path` in `{completed_analyses}` into the working set. - > For a single-scope audit, that scope's findings are the working set as they stand. - > For a multi-scope audit, merge them: deduplicate findings reported in more than one scope, keeping the highest severity and citing every scope it appeared in, and surface patterns recurring across scopes as systemic findings. + > - For a single-scope audit, that scope's findings are the working set as they stand. + > - For a multi-scope audit, merge them: deduplicate findings reported in more than one scope, keeping the highest severity and citing every scope it appeared in, and surface patterns recurring across scopes as systemic findings. ### 2. Create Detailed Findings diff --git a/prism-audit/techniques/audit-finalize/split-report.md b/prism-audit/techniques/audit-finalize/split-report.md index 464056945..6c13d481e 100644 --- a/prism-audit/techniques/audit-finalize/split-report.md +++ b/prism-audit/techniques/audit-finalize/split-report.md @@ -26,6 +26,6 @@ Filesystem path to the written AUDIT-REPORT.md (the summary report). ### 1. Split Report - Locate the source reports from the `report_path` in `{completed_analyses}`. - > For a single-scope audit, that one report is the source. - > For a multi-scope audit, merge the per-scope executive summaries, domain tables and systemic patterns into one. + > - For a single-scope audit, that one report is the source. + > - For a multi-scope audit, merge the per-scope executive summaries, domain tables and systemic patterns into one. - Write the summary report to `{audit_report_path}` per [audit-report](../../resources/audit-report.md#template) and its [Rules](../../resources/audit-report.md#rules), which own the reference line that replaces the lifted section and the renumbering it forces. diff --git a/prism-audit/techniques/compose-audit-prompt/survey-structure.md b/prism-audit/techniques/compose-audit-prompt/survey-structure.md index 515068c57..c2c2e7ae8 100644 --- a/prism-audit/techniques/compose-audit-prompt/survey-structure.md +++ b/prism-audit/techniques/compose-audit-prompt/survey-structure.md @@ -31,5 +31,5 @@ Total lines of code across the surveyed modules, excluding tests, docs, and gene ### 2. Inventory the Modules - Record `{module_inventory}` from the layout the build configuration declares, with each module's line count excluding tests, docs and generated files, and `{total_loc}` as their sum. Note the test directories and the file patterns they follow. - > Where the codebase is indexed, apply `gitnexus-operations::query` for functional areas, execution flows and community clusters, which bound modules better than directory layout alone, and `gitnexus-operations::context` on the high-risk ones for a caller count. - > Where `{target_path}` holds no analysable source files, report the path as unsurveyable and whether submodules appear uninitialised, rather than an empty inventory. + > - Where the codebase is indexed, apply `gitnexus-operations::query` for functional areas, execution flows and community clusters, which bound modules better than directory layout alone, and `gitnexus-operations::context` on the high-risk ones for a caller count. + > - Where `{target_path}` holds no analysable source files, report the path as unsurveyable and whether submodules appear uninitialised, rather than an empty inventory. diff --git a/prism-evaluate/techniques/compose-evaluation-report/extract-findings.md b/prism-evaluate/techniques/compose-evaluation-report/extract-findings.md index f31e6202f..c586d680b 100644 --- a/prism-evaluate/techniques/compose-evaluation-report/extract-findings.md +++ b/prism-evaluate/techniques/compose-evaluation-report/extract-findings.md @@ -20,5 +20,5 @@ Draws each dimension's findings out of its analysis run and into the report's pe ### 3. Record the Per-Dimension Sections - Record `{evaluation_report.dimension_findings}`: per dimension, its name, finding count, count by severity, and the findings with their IDs. - > A run whose status is `partial` or `error` keeps its dimension in the report, noted as incomplete coverage. - > A dimension whose run found nothing keeps its section, noted as no significant findings. + > - A run whose status is `partial` or `error` keeps its dimension in the report, noted as incomplete coverage. + > - A dimension whose run found nothing keeps its section, noted as no significant findings. diff --git a/prism-evaluate/techniques/plan-evaluation/derive-dimensions.md b/prism-evaluate/techniques/plan-evaluation/derive-dimensions.md index 747d6c2a6..4e95a50e3 100644 --- a/prism-evaluate/techniques/plan-evaluation/derive-dimensions.md +++ b/prism-evaluate/techniques/plan-evaluation/derive-dimensions.md @@ -18,7 +18,7 @@ The evaluation dimensions the analysis is framed by, each `{ name, description, ### 1. Settle the Dimension Set - Resolve `{dimensions}` to a set whose entries each carry a name and a description, in the shape [Dimension Object Structure](../../resources/default-dimensions.md#dimension-object-structure) defines. - > Where the request supplied dimensions, validation is the whole of the work — each entry needs a name and a description. - > Where it supplied none, take the set matching `{evaluation_target_type}` from [Proposal / Strategy Document](../../resources/default-dimensions.md#proposal--strategy-document), [Codebase](../../resources/default-dimensions.md#codebase), or [Mixed Targets](../../resources/default-dimensions.md#mixed-targets). - > For a `{evaluation_target_type}` those sets do not cover, infer each dimension from `{evaluation_description}` per [Custom Targets](../../resources/default-dimensions.md#custom-targets), one independent analytical axis apiece. - > When neither `{evaluation_description}` nor `{target_path}` yields an independent axis, record `{dimensions}` as unresolved, so the scope summary carries the gap. + > - Where the request supplied dimensions, validation is the whole of the work — each entry needs a name and a description. + > - Where it supplied none, take the set matching `{evaluation_target_type}` from [Proposal / Strategy Document](../../resources/default-dimensions.md#proposal--strategy-document), [Codebase](../../resources/default-dimensions.md#codebase), or [Mixed Targets](../../resources/default-dimensions.md#mixed-targets). + > - For a `{evaluation_target_type}` those sets do not cover, infer each dimension from `{evaluation_description}` per [Custom Targets](../../resources/default-dimensions.md#custom-targets), one independent analytical axis apiece. + > - When neither `{evaluation_description}` nor `{target_path}` yields an independent axis, record `{dimensions}` as unresolved, so the scope summary carries the gap. diff --git a/prism-evaluate/techniques/plan-evaluation/group-for-execution.md b/prism-evaluate/techniques/plan-evaluation/group-for-execution.md index 0ba89c607..88af24f0c 100644 --- a/prism-evaluate/techniques/plan-evaluation/group-for-execution.md +++ b/prism-evaluate/techniques/plan-evaluation/group-for-execution.md @@ -18,8 +18,8 @@ An array of `{ pipeline_mode, lenses, dimensions, analysis_focus, output_subdir ### 1. Group by Pipeline Mode - Group the dimensions of `{dimension_plan}` that share a `pipeline_mode`. - > A `full-prism` dimension takes a group of its own — its three passes run over one target and admit no second dimension. - > `portfolio` dimensions combine into one group carrying the union of their lens indices, each lens writing its own artifact under the group's `output_subdir`. + > - A `full-prism` dimension takes a group of its own — its three passes run over one target and admit no second dimension. + > - `portfolio` dimensions combine into one group carrying the union of their lens indices, each lens writing its own artifact under the group's `output_subdir`. ### 2. Record the Groups diff --git a/prism-evaluate/techniques/plan-evaluation/map-dimensions-to-lenses.md b/prism-evaluate/techniques/plan-evaluation/map-dimensions-to-lenses.md index 66fe73a70..4a08f7b05 100644 --- a/prism-evaluate/techniques/plan-evaluation/map-dimensions-to-lenses.md +++ b/prism-evaluate/techniques/plan-evaluation/map-dimensions-to-lenses.md @@ -28,8 +28,8 @@ An array of `{ dimension, pipeline_mode, lenses, analysis_focus, output_subdir } ### 1. Match Each Dimension to a Lens Set - For each dimension, match against [Standard Mappings](../../resources/dimension-lens-mapping.md#standard-mappings); when no standard mapping matches, derive one per [Custom Dimension Mappings](../../resources/dimension-lens-mapping.md#custom-dimension-mappings), which names the lens catalog to match the dimension's goal against. - > Where `{lens_overrides}` holds an entry for a dimension name, the override values stand in place of the matched mapping. - > Where a dimension matches no goal the catalog names, record the closest lens set as a proposal and leave the dimension unmapped pending an override for it. + > - Where `{lens_overrides}` holds an entry for a dimension name, the override values stand in place of the matched mapping. + > - Where a dimension matches no goal the catalog names, record the closest lens set as a proposal and leave the dimension unmapped pending an override for it. ### 2. Compose Each Analysis Focus diff --git a/prism-evaluate/techniques/plan-evaluation/survey-target.md b/prism-evaluate/techniques/plan-evaluation/survey-target.md index 3672a7c5b..b92b7f39e 100644 --- a/prism-evaluate/techniques/plan-evaluation/survey-target.md +++ b/prism-evaluate/techniques/plan-evaluation/survey-target.md @@ -26,9 +26,9 @@ A summary of the target's scope, goals, and major content. ### 1. Inventory the Structure - Inventory the units at the top level of `{target_path}`, and record `{structure_inventory}` as the sections or modules found with their sizes. - > For a `codebase` target, and the code half of a `mixed` one, apply the structure survey `prism::plan-analysis` defines — build-system detection, module and package enumeration, per-module line counts, test-directory location, and the GitNexus functional-area and community-cluster survey through `gitnexus-operations::verify-index` then `::query` where the codebase is indexed. - > For a `document` or `document-set` target, and the document half of a `mixed` one, the units are the documents, their topics, structure and cross-references, with a total word or section count. - > When `{target_path}` holds no readable files, report the empty target rather than an empty inventory. + > - For a `codebase` target, and the code half of a `mixed` one, apply the structure survey `prism::plan-analysis` defines — build-system detection, module and package enumeration, per-module line counts, test-directory location, and the GitNexus functional-area and community-cluster survey through `gitnexus-operations::verify-index` then `::query` where the codebase is indexed. + > - For a `document` or `document-set` target, and the document half of a `mixed` one, the units are the documents, their topics, structure and cross-references, with a total word or section count. + > - When `{target_path}` holds no readable files, report the empty target rather than an empty inventory. ### 2. Read for Substance diff --git a/prism-evaluate/techniques/resolve-findings/apply-changes.md b/prism-evaluate/techniques/resolve-findings/apply-changes.md index 58622f0da..4c1ff7583 100644 --- a/prism-evaluate/techniques/resolve-findings/apply-changes.md +++ b/prism-evaluate/techniques/resolve-findings/apply-changes.md @@ -22,8 +22,8 @@ The target this application modified, together with the mitigation plan the chan ### 1. Apply Each Change - Work through `{mitigation_plan.implementation_priority}`, and for each change verify the target text at `{target_path}` matches what the plan expects before making it. - > Where an earlier change moved the text, search for the expected text elsewhere in the target and apply the change at that location. - > Where the expected text is nowhere in the target, record the conflict and leave that change unapplied. + > - Where an earlier change moved the text, search for the expected text elsewhere in the target and apply the change at that location. + > - Where the expected text is nowhere in the target, record the conflict and leave that change unapplied. ### 2. Verify Each Change Landed diff --git a/prism-evaluate/techniques/resolve-findings/record-finding-decision.md b/prism-evaluate/techniques/resolve-findings/record-finding-decision.md index 2ad7fe517..15d857795 100644 --- a/prism-evaluate/techniques/resolve-findings/record-finding-decision.md +++ b/prism-evaluate/techniques/resolve-findings/record-finding-decision.md @@ -28,5 +28,5 @@ One finding's recorded disposition: `{ finding_id, finding_severity, mitigation_ ### 1. Record the Disposition - Record `{finding_decision}` from `{current_finding}`, `{finding_disposition}`, and the text of `{proposed_mitigation}`. - > Under a `modify` disposition, the recorded text is the adjusted wording rather than the proposal's. - > Under `skip` or `discuss`, the record carries the finding and its severity with no mitigation text, and `discuss` records the dialogue as unsettled. + > - Under a `modify` disposition, the recorded text is the adjusted wording rather than the proposal's. + > - Under `skip` or `discuss`, the record carries the finding and its severity with no mitigation text, and `discuss` records the dialogue as unsettled. diff --git a/prism/techniques/generate-report.md b/prism/techniques/generate-report.md index c1648fac0..9fb78c25c 100644 --- a/prism/techniques/generate-report.md +++ b/prism/techniques/generate-report.md @@ -115,8 +115,8 @@ Full filesystem path to `DEFINITIVE-FINDINGS.md` - **A finding that arrived with a designator keeps it**, whatever series it belongs to. That designator is where its identity lives for the upstream artifacts, gates and citations that already cite it. - Mint identifiers only for findings this run raised, in a range disjoint from the carried ones. - > When `{analysis_focus}` provides dimension names or categories, mint dimension-based prefixes (e.g., CON-xx for consistency, VER-xx for veracity). - > Otherwise mint severity-ordered sequential numbering (e.g., F-01, F-02). + > - When `{analysis_focus}` provides dimension names or categories, mint dimension-based prefixes (e.g., CON-xx for consistency, VER-xx for veracity). + > - Otherwise mint severity-ordered sequential numbering (e.g., F-01, F-02). - For multi-unit analyses, prefix a minted identifier with a short unit identifier where needed to avoid collisions. - If two findings hold the same identifier, disambiguate the **minted** one — never the carried one — and report the collision. - Record, for every finding in the report, `report_id → { source_artifact_path, original_id, original_severity }`, so a carried identifier reads as carried and a minted one names what it was minted for. diff --git a/work-package/techniques/codebase-comprehension/survey.md b/work-package/techniques/codebase-comprehension/survey.md index f3fbe9241..6e4c9dea1 100644 --- a/work-package/techniques/codebase-comprehension/survey.md +++ b/work-package/techniques/codebase-comprehension/survey.md @@ -63,7 +63,7 @@ Mapping of domain-specific terms to the technical modules/constructs that implem - Identify module boundaries and their responsibilities from directory layout, module declarations, and public APIs - Map dependency relationships between modules (imports, trait implementations, cross-module calls) - Identify overarching patterns: layered architecture, event-driven, actor model, plugin system, etc. - - If the codebase uses patterns or frameworks you are unfamiliar with, use web research to understand the framework conventions, then document the findings + > If the codebase uses patterns or frameworks you are unfamiliar with, use web research to understand the framework conventions, then document the findings - Form architecture hypotheses and verify by sampling implementation files - If the codebase is too large for exhaustive analysis, focus on areas relevant to the problem statement and note the unexplored areas for future passes diff --git a/work-package/techniques/manage-git/create-worktree.md b/work-package/techniques/manage-git/create-worktree.md index f2942263d..783b0ab88 100644 --- a/work-package/techniques/manage-git/create-worktree.md +++ b/work-package/techniques/manage-git/create-worktree.md @@ -28,7 +28,7 @@ Boolean — true when the worktree exists at `{target_path}` on `{branch_name}` ### 2. Create Worktree - Idempotency check: if `{target_path}` already exists, run `git -C {component_git_dir} worktree list --porcelain` and verify the path is registered as a worktree pointing at `{branch_name}`. If yes, reuse and set `{worktree_created}` = true. If `{target_path}` already exists but is not a registered worktree of the component repo (or points elsewhere), surface the conflict to the user and do NOT delete the path — offer to choose a different wp-slug or to inspect the existing directory. -- Materialise path and branch position in one step by `{create_branch}`: - - When `{create_branch}` is true: `git -C {component_git_dir} worktree add -b {branch_name} {target_path} origin/{default_branch}`. If `{branch_name}` already exists on the component repo, ask the user whether to use the existing branch or pick a new name. - - When `{create_branch}` is false: `git -C {component_git_dir} worktree add {target_path} {branch_name}` — check out the existing branch without `-b`. +- Materialise path and branch position in one step, choosing the form by `{create_branch}`. + > - When `{create_branch}` is true: `git -C {component_git_dir} worktree add -b {branch_name} {target_path} origin/{default_branch}`. If `{branch_name}` already exists on the component repo, ask the user whether to use the existing branch or pick a new name. + > - When `{create_branch}` is false: `git -C {component_git_dir} worktree add {target_path} {branch_name}`, which checks out the existing branch without `-b`. - On success, set `{worktree_created}` = true and emit a one-line message: `Worktree created at {target_path} on branch {branch_name}.` diff --git a/work-package/techniques/manage-git/restore-paths-from-ref.md b/work-package/techniques/manage-git/restore-paths-from-ref.md index 1540705d5..35c908586 100644 --- a/work-package/techniques/manage-git/restore-paths-from-ref.md +++ b/work-package/techniques/manage-git/restore-paths-from-ref.md @@ -38,9 +38,9 @@ Paths successfully restored from `{base_ref}` and staged in `{target_path}`. Emp ### 2. Restore -- For each path in `{paths}`: - - When `{interactive_restore}` is true: `git -C {target_path} checkout -p {base_ref} -- {path}` (agent/user selects hunks). - - Otherwise: `git -C {target_path} checkout {base_ref} -- {path}`. +- For each path in `{paths}`, check it out from `{base_ref}` in the form `{interactive_restore}` selects. + > - When `{interactive_restore}` is true: `git -C {target_path} checkout -p {base_ref} -- {path}`, where the agent or user selects hunks. + > - Otherwise: `git -C {target_path} checkout {base_ref} -- {path}`. - Skip paths that do not exist at `{base_ref}` (record and continue); do not invent content. ### 3. Stage diff --git a/work-package/techniques/respond-to-pr-review.md b/work-package/techniques/respond-to-pr-review.md index 1cb1126ec..e695ce013 100644 --- a/work-package/techniques/respond-to-pr-review.md +++ b/work-package/techniques/respond-to-pr-review.md @@ -35,7 +35,7 @@ Whether the changes are significant enough to require substantial rework - Take the response shape from [Response Format Template](../resources/pr-review-response.md#response-format-template) and the document shape from [Review Document Template](../resources/pr-review-response.md#review-document-template); the rules below govern response content - Apply [list-pr-review-comments](../../meta/techniques/github-cli-protocol/list-pr-review-comments.md)(*repo_path*=`{component_git_dir}`); set `{review_comments}` from `{pr_review_comments}`. - - If no review comments are found, verify the PR has been reviewed and check comment visibility before proceeding. + > If no review comments are found, verify the PR has been reviewed and check comment visibility before proceeding. - Apply [list-pr-reviews](../../meta/techniques/github-cli-protocol/list-pr-reviews.md)(*repo_path*=`{component_git_dir}`). Filter to unresolved comments from the latest review round (avoid re-answering resolved threads): derive `{$latest_review_date}` from `{pr_reviews}`, then keep only comments from reviewers (not the PR author) whose `` `updated_at` `` is at or after `{$latest_review_date}`. Project each surviving comment to its `.id`, `.body`, `` `html_url` `` (as `url`), `.path`, and `.line`. - Identify question-type comments from the filtered set (bodies matching what/how/why/which). - Before proceeding: total comment count confirmed; unresolved comments filtered to the latest review round; question-type comments identified; comments saved for analysis diff --git a/work-package/techniques/review-code.md b/work-package/techniques/review-code.md index 01f0d5054..aa023ff35 100644 --- a/work-package/techniques/review-code.md +++ b/work-package/techniques/review-code.md @@ -53,7 +53,7 @@ Method [record](../resources/rust-substrate-code-review.md#method-record-templat - Review against the attached [Review Criteria](../resources/rust-substrate-code-review.md#review-criteria) ([resource-loading-via-tool](../../meta/techniques/workflow-engine/TECHNIQUE.md#resource-loading-via-tool) — never read workflow resources from disk). - Consume the canonical `{changed_files}` authored surface when it is established (review mode, produced by `review-baseline-state`). In create mode (no PR baseline), derive it from the local working-tree diff against the base branch. - - If `{changed_files}` is empty, verify the correct branch and commit range. + > If `{changed_files}` is empty, verify the correct branch and commit range. ### 2. Bound Review Scope diff --git a/work-package/techniques/strategic-findings-analysis.md b/work-package/techniques/strategic-findings-analysis.md index bbf28db22..4cc510fc1 100644 --- a/work-package/techniques/strategic-findings-analysis.md +++ b/work-package/techniques/strategic-findings-analysis.md @@ -46,8 +46,8 @@ A concise multi-line summary of the strategic-review findings — one line per f - Set `{recommended_strategic_option}` to `acceptable` when findings are minor or absent. - With one or more significant findings present, set it to the action the run can take on them. - > When `{is_review_mode}` is true, that action is `raise-findings` — the change belongs to its author, and what this run decides is which findings the posted review carries. - > Otherwise it is `fix-findings` — the run owns the change and can alter it. + > - When `{is_review_mode}` is true, that action is `raise-findings` — the change belongs to its author, and what this run decides is which findings the posted review carries. + > - Otherwise it is `fix-findings` — the run owns the change and can alter it. ### 3. Summarize Findings diff --git a/workflow-design/resources/anti-patterns.md b/workflow-design/resources/anti-patterns.md index 5facf7e6e..a1f7ef559 100644 --- a/workflow-design/resources/anti-patterns.md +++ b/workflow-design/resources/anti-patterns.md @@ -805,7 +805,7 @@ A caveat is a protocol sub-bullet instead of a blockquote note. **Do not flag:** Genuine enumerations or sequential sub-steps (per-harness branch tables, ordered sub-actions). Global/cross-step constraints belong in `## Rules` (`structure-backed-constraints`, `no-rule-protocol-restatement`). Single-block Rules misfiled as global — see `local-rule-as-note`. Distinct from `no-one-step-rules`. -**Fix:** Convert to a `>` note under the primary instruction (two trailing spaces on the primary bullet, then `> ` on the next line). A `>` line is not a step — it folds into the parent. See [Isolate Conditional Branches as Notes](./design-principles.md#31-isolate-conditional-branches-as-notes). +**Fix:** Move the caveat into a `>` note under the primary instruction. A lone caveat is the note's prose (` > If the PR has not merged, wait`); two or more items each take a bullet within the note (` > - When …`). A line opening with `>` is not a step — it folds into the parent. See [Isolate Conditional Branches as Notes](./design-principles.md#31-isolate-conditional-branches-as-notes). ### AP-60. local-rule-as-note diff --git a/workflow-design/resources/design-principles.md b/workflow-design/resources/design-principles.md index 177d10934..420428edd 100644 --- a/workflow-design/resources/design-principles.md +++ b/workflow-design/resources/design-principles.md @@ -138,7 +138,7 @@ Split a multi-part resource into per-category sections, each carrying the fragme ## 31. Isolate Conditional Branches as Notes -Prose that applies on one path only is set apart from prose that always applies. Within a Protocol step, the unconditional instruction is the bullet and each *when* / *if* / *otherwise* branch is its own `>` note beneath it — one note per branch. A reader scanning the step then sees the shape of the work without evaluating every clause to learn which parts apply to their run, and the branch stays visually attached to the instruction it qualifies instead of reading as another thing to do. +Prose that applies on one path only is set apart from prose that always applies. Within a Protocol step, the unconditional instruction is the bullet and each *when* / *if* / *otherwise* branch is a `>` note beneath it. A note carrying two or more items gives each one a bullet, written ` > - When …`, so they read as the list they are; a lone caveat is the note's own prose, with no list to express. Either shape keeps the block out of the step sequence, because the protocol parser's step regex matches a bullet at any indent and a line opening with `>` fails that match and folds into the instruction above. A reader scanning the step then sees the shape of the work without evaluating every clause to learn which parts apply to their run, and the branch stays visually attached to the instruction it qualifies rather than reading as another thing to do. Reach for structure first: a condition selecting a step, an activity, or a whole path is a `when`, a `condition`, or a declared decision, and belongs in the YAML. This stance governs only what legitimately remains in prose — a branch qualifying a single instruction, with no structural home. Prefer the note over a sibling bullet, and over an inline "if X then Y, otherwise Z" clause that buries the branch mid-sentence. Avoids `constraint-as-blockquote`; the structural alternatives are `checkpoint-not-prose`, `loop-not-prose`, and `decision-not-prose`.