From 2fcc8c299c8cd48a4a1a23f618b01233cbe3a390 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 3 Sep 2026 15:41:23 +0100 Subject: [PATCH 1/3] detect a caveat in both the spellings that carry it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A constraint qualifying one instruction sits outside its `>` note in two spellings: an indented sub-bullet, which the step regex turns into a peer step; and a `when` / `if` / `otherwise` clause inside the step's own sentence, where the outcome and a branch off it read as one instruction. Two clauses restating one predicate in different words read as two branches over one condition. Do-not-flag names the selection ladder explicitly — `If` / `Else if` / `Otherwise` arms over one choice are a branch table, whichever way indented — alongside the ordered sub-actions and precedence ladders already kept. Co-Authored-By: Claude Opus 5 (1M context) --- workflow-design/resources/anti-patterns.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/workflow-design/resources/anti-patterns.md b/workflow-design/resources/anti-patterns.md index dcbf172f..153d0fef 100644 --- a/workflow-design/resources/anti-patterns.md +++ b/workflow-design/resources/anti-patterns.md @@ -797,15 +797,18 @@ Symbol ids use the wrong case convention. ### AP-59. constraint-as-blockquote -"` - If the PR has not merged, wait`" +"` - If the PR has not merged, wait`" / "`Compose {status} = {…}. When passed is false, surface the offending entries.`" -A caveat is a protocol sub-bullet instead of a blockquote note. +A caveat qualifying one instruction sits outside the blockquote note that carries it. -**Detect:** A constraint that qualifies a SINGLE primary instruction — conditional caveat, fallback, error-path, or prohibition — is an indented sub-bullet (` - …`). The protocol parser's step regex strips leading whitespace, so that line becomes a disconnected *peer* step. +**Detect:** A constraint that qualifies a SINGLE primary instruction — conditional caveat, fallback, error-path, or prohibition — sits anywhere other than a `>` note beneath that instruction. Two spellings carry it: -**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`. +- **As an indented sub-bullet** (` - …`). The protocol parser's step regex strips leading whitespace, so the line becomes a disconnected *peer* step. +- **As a `when` / `if` / `otherwise` clause inside the step's own sentence.** The step's outcome and a branch off it read as one instruction, so a reader evaluates every clause to learn which part applies to their run. Two clauses restating one predicate in different words (`when {passed} is false` beside `if the run emitted warnings`) read as two branches over one condition. -**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). +**Do not flag:** Genuine enumerations or sequential sub-steps (ordered sub-actions, precedence ladders). A complete selection ladder — `If` / `Else if` / `Otherwise` arms over one choice — is a branch table, and stands whichever way it is indented. 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:** Move the caveat into a `>` note under the primary instruction, and leave the step stating its outcome alone. 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 …`). Where two clauses name one predicate, the note states it once. 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 From c580284abd1c300b7c61fe946d05d492a39dce77 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 3 Sep 2026 15:41:28 +0100 Subject: [PATCH 2/3] carry a step's caveat in a note beneath it Each protocol step states its outcome, and the conditional caveat, fallback or error path qualifying it sits in a `>` note beneath. A lone caveat is the note's prose; two take a bullet each. A line opening with `>` folds into the instruction above rather than reading as another step to perform. The clippy and fmt-check compose steps state their status value alone, with the failure path in the note. Clippy's note names its predicate once, where the surfacing and the addressing had been two clauses over the same condition. Twenty-two techniques across atlassian-operations, cargo-operations, gitnexus-operations, knowledge-base-search, dco-provenance and validate-build. Co-Authored-By: Claude Opus 5 (1M context) --- meta/techniques/atlassian-operations/create-jira-issue.md | 2 +- meta/techniques/atlassian-operations/transition-jira-issue.md | 2 +- meta/techniques/cargo-operations/build-dev.md | 2 +- meta/techniques/cargo-operations/build-release.md | 2 +- meta/techniques/cargo-operations/check.md | 4 ++-- meta/techniques/cargo-operations/clippy.md | 3 ++- meta/techniques/cargo-operations/doc.md | 2 +- meta/techniques/cargo-operations/fmt-check.md | 3 ++- meta/techniques/cargo-operations/test.md | 2 +- meta/techniques/gitnexus-operations/complexity-signal.md | 4 ++-- meta/techniques/gitnexus-operations/context.md | 4 ++-- meta/techniques/gitnexus-operations/cypher.md | 4 ++-- meta/techniques/gitnexus-operations/public-api-enum.md | 2 +- meta/techniques/gitnexus-operations/query.md | 4 ++-- meta/techniques/gitnexus-operations/reversibility-signal.md | 4 ++-- meta/techniques/gitnexus-operations/verify-index.md | 2 +- meta/techniques/knowledge-base-search/broad-chunks-search.md | 2 +- meta/techniques/knowledge-base-search/chunks-search.md | 2 +- meta/techniques/knowledge-base-search/load-domain-index.md | 2 +- work-package/techniques/dco-provenance/record-attestation.md | 4 ++-- work-package/techniques/validate-build/analyze-failure.md | 2 +- work-package/techniques/validate-build/apply-fix.md | 2 +- 22 files changed, 31 insertions(+), 29 deletions(-) diff --git a/meta/techniques/atlassian-operations/create-jira-issue.md b/meta/techniques/atlassian-operations/create-jira-issue.md index 6312d73f..d74cc68d 100644 --- a/meta/techniques/atlassian-operations/create-jira-issue.md +++ b/meta/techniques/atlassian-operations/create-jira-issue.md @@ -34,4 +34,4 @@ Created issue key (e.g., `ENG-123`). ## Protocol 1. Call `createJiraIssue { cloudId, projectKey, issueTypeName, summary, description?, additional_fields? }` and return the `{issueKey}` of the created issue. - - If the call fails because `{issueTypeName}` does not exist for the project, apply [list-jira-issue-types](./list-jira-issue-types.md) to discover valid types, then retry. + > If the call fails because `{issueTypeName}` does not exist for the project, apply [list-jira-issue-types](./list-jira-issue-types.md) to discover valid types, then retry. diff --git a/meta/techniques/atlassian-operations/transition-jira-issue.md b/meta/techniques/atlassian-operations/transition-jira-issue.md index f0829850..70bff487 100644 --- a/meta/techniques/atlassian-operations/transition-jira-issue.md +++ b/meta/techniques/atlassian-operations/transition-jira-issue.md @@ -20,4 +20,4 @@ Transition object with an `id` identifying a status transition available for the ## Protocol 1. Call `transitionJiraIssue { cloudId, issueIdOrKey, transition: status_transition }`. - - If the `{status_transition}` id is not available for the current issue state, apply [list-jira-transitions](./list-jira-transitions.md) to get the available transitions and retry with one of those ids. + > If the `{status_transition}` id is not available for the current issue state, apply [list-jira-transitions](./list-jira-transitions.md) to get the available transitions and retry with one of those ids. diff --git a/meta/techniques/cargo-operations/build-dev.md b/meta/techniques/cargo-operations/build-dev.md index 9a096e5e..dd7db5df 100644 --- a/meta/techniques/cargo-operations/build-dev.md +++ b/meta/techniques/cargo-operations/build-dev.md @@ -16,4 +16,4 @@ The compiled dev binaries/libraries for `{build_scope}` under the cargo target d ## Protocol 1. `{generated_product_skip} {build_budget} cargo build {build_scope} {features}` - - If the link or codegen step exceeds available RAM, halve `CARGO_BUILD_JOBS` and retry. + > If the link or codegen step exceeds available RAM, halve `CARGO_BUILD_JOBS` and retry. diff --git a/meta/techniques/cargo-operations/build-release.md b/meta/techniques/cargo-operations/build-release.md index 3d5ed8e2..ca2a577e 100644 --- a/meta/techniques/cargo-operations/build-release.md +++ b/meta/techniques/cargo-operations/build-release.md @@ -16,7 +16,7 @@ The optimized release binary for `{build_scope}` AND the runtime wasm artifact, ## Protocol 1. `{build_budget} cargo build --release {build_scope} {features}` - - If the build runs out of memory (release link/LTO plus the nested wasm build together exceed available RAM), halve `CARGO_BUILD_JOBS`; on tight hosts, run `-p ` for the binary first, then a separate workspace pass for the runtime. + > If the build runs out of memory (release link/LTO plus the nested wasm build together exceed available RAM), halve `CARGO_BUILD_JOBS`; on tight hosts, run `-p ` for the binary first, then a separate workspace pass for the runtime. ## Rules diff --git a/meta/techniques/cargo-operations/check.md b/meta/techniques/cargo-operations/check.md index c9997530..49265112 100644 --- a/meta/techniques/cargo-operations/check.md +++ b/meta/techniques/cargo-operations/check.md @@ -16,5 +16,5 @@ Type-check without producing binaries; the cheapest validation pass. ## Protocol 1. `{generated_product_skip} {build_budget} cargo check {build_scope} {features}`; compose `{check_status}` = `{ check_id: 'check', passed: , diagnostics: }`. - - If the compile peaks above available RAM even with the job budget, halve `CARGO_BUILD_JOBS` (`export CARGO_BUILD_JOBS=2`) and retry; if it still fails, narrow scope to `-p `. - - If the type-check fails in the source, address the rustc errors and retry. + > - If the compile peaks above available RAM even with the job budget, halve `CARGO_BUILD_JOBS` (`export CARGO_BUILD_JOBS=2`) and retry; if it still fails, narrow scope to `-p `. + > - If the type-check fails in the source, address the rustc errors and retry. diff --git a/meta/techniques/cargo-operations/clippy.md b/meta/techniques/cargo-operations/clippy.md index eed907ef..bd323c46 100644 --- a/meta/techniques/cargo-operations/clippy.md +++ b/meta/techniques/cargo-operations/clippy.md @@ -20,4 +20,5 @@ Captured stdout/stderr from the linter run. ## Protocol 1. Run `{generated_product_skip} {build_budget} cargo clippy {build_scope} --all-targets {features} -- -D warnings`, capturing its combined stdout/stderr as `{lint_diagnostics}`. -2. Compose `{clippy_status}` = `{ check_id: 'clippy', passed: , diagnostics: {lint_diagnostics} }`. When `passed` is false, surface the offending entries from `{lint_diagnostics}`. If clippy emitted denied warnings, address the diagnostics; do not blanket-allow without justification. +2. Compose `{clippy_status}` = `{ check_id: 'clippy', passed: , diagnostics: {lint_diagnostics} }`. + > When `passed` is false, surface the offending entries from `{lint_diagnostics}` and address them. A blanket allow carries a stated justification. diff --git a/meta/techniques/cargo-operations/doc.md b/meta/techniques/cargo-operations/doc.md index 1f996f80..4bde52b0 100644 --- a/meta/techniques/cargo-operations/doc.md +++ b/meta/techniques/cargo-operations/doc.md @@ -16,4 +16,4 @@ The generated rustdoc HTML for `{build_scope}` under the cargo target directory; ## Protocol 1. `{generated_product_skip} {build_budget} cargo doc {build_scope}` - - If rustdoc reports a broken intra-doc link, fix the link target or remove the broken reference. + > If rustdoc reports a broken intra-doc link, fix the link target or remove the broken reference. diff --git a/meta/techniques/cargo-operations/fmt-check.md b/meta/techniques/cargo-operations/fmt-check.md index ae7c4c87..222bca42 100644 --- a/meta/techniques/cargo-operations/fmt-check.md +++ b/meta/techniques/cargo-operations/fmt-check.md @@ -20,4 +20,5 @@ Concise summary of files needing formatting (when not passed). ## Protocol 1. `nice -n 19 cargo fmt {build_scope} -- --check` -2. Compose `{fmt_status}` = `{ check_id: 'fmt-check', passed: , diagnostics: {fmt_diff_summary} }`. When it fails, capture the listed files as `{fmt_diff_summary}`. A failure means source files do not match the rustfmt configuration; to recover, apply [fmt-fix](./fmt-fix.md) to apply formatting, then commit the result. +2. Compose `{fmt_status}` = `{ check_id: 'fmt-check', passed: , diagnostics: {fmt_diff_summary} }`. + > When `passed` is false, the listed files do not match the rustfmt configuration. Capture them as `{fmt_diff_summary}`, apply [fmt-fix](./fmt-fix.md), then commit the result. diff --git a/meta/techniques/cargo-operations/test.md b/meta/techniques/cargo-operations/test.md index c27ecd6c..ec3a96a2 100644 --- a/meta/techniques/cargo-operations/test.md +++ b/meta/techniques/cargo-operations/test.md @@ -29,5 +29,5 @@ Per-test failure detail when any failed 1. If cargo nextest is configured (`.config/nextest.toml` present in the project): `{generated_product_skip} RUST_TEST_THREADS=${RUST_TEST_THREADS:-4} {build_budget} cargo nextest run {build_scope} {features} --test-threads=${RUST_TEST_THREADS:-4} {test_filter}` > When cargo nextest is configured (`.config/nextest.toml` present), this operation MUST use the nextest branch — it isolates failures into separate processes, giving lower peak RAM and clearer reporting. The procedure's conditional encodes this: do not skip the nextest branch when it applies. 2. Otherwise: `{generated_product_skip} RUST_TEST_THREADS=${RUST_TEST_THREADS:-4} {build_budget} cargo test {build_scope} {features} {test_filter} -- --test-threads=${RUST_TEST_THREADS:-4}` - - If test compilation or runtime peaks above available RAM, halve `CARGO_BUILD_JOBS` and `RUST_TEST_THREADS` and retry; consider the nextest branch for lower per-test peak. + > If test compilation or runtime peaks above available RAM, halve `CARGO_BUILD_JOBS` and `RUST_TEST_THREADS` and retry; consider the nextest branch for lower per-test peak. 3. Report the run's pass/fail summary as `{test_status}`; when any test failed, capture the per-test detail as `{failures}`. If one or more tests failed, investigate the reported failure; do not mask it via `--no-fail-fast`. diff --git a/meta/techniques/gitnexus-operations/complexity-signal.md b/meta/techniques/gitnexus-operations/complexity-signal.md index 65f33035..6ebf3c23 100644 --- a/meta/techniques/gitnexus-operations/complexity-signal.md +++ b/meta/techniques/gitnexus-operations/complexity-signal.md @@ -26,6 +26,6 @@ fan-out and affected-process count as an objective complexity indicator ## Protocol 1. Apply [impact](./impact.md) with `{target, maxDepth: 2, repo_name}`. - - If no `{target}` symbol can be inferred from the issue, the signal is unavailable — fall back to an issue-text complexity estimate. - - If the index is out of date, run `npx gitnexus analyze`, then retry. + > - If no `{target}` symbol can be inferred from the issue, the signal is unavailable — fall back to an issue-text complexity estimate. + > - If the index is out of date, run `npx gitnexus analyze`, then retry. 2. Read the fan-out and affected-process count as the `{complexity_signal}`: high fan-out or many affected processes indicate higher complexity than the issue text alone might suggest. diff --git a/meta/techniques/gitnexus-operations/context.md b/meta/techniques/gitnexus-operations/context.md index e86dc119..d47e115e 100644 --- a/meta/techniques/gitnexus-operations/context.md +++ b/meta/techniques/gitnexus-operations/context.md @@ -26,6 +26,6 @@ incoming calls (callers), outgoing calls (callees), process membership with step ## Protocol 1. Call `gitnexus_context {name, repo_name}` to assemble the `{context_report}` — incoming calls, outgoing calls, and process membership. - - If the index is out of date, run `npx gitnexus analyze`, then retry. - - If `{name}` does not resolve, verify the symbol name; fall back to grep when the symbol is unindexed. + > - If the index is out of date, run `npx gitnexus analyze`, then retry. + > - If `{name}` does not resolve, verify the symbol name; fall back to grep when the symbol is unindexed. 2. Read the `{context_report}`'s caller fan-out as a blast-radius signal: many callers and broad process participation → the symbol is path-committing; an isolated symbol is low-risk to touch. diff --git a/meta/techniques/gitnexus-operations/cypher.md b/meta/techniques/gitnexus-operations/cypher.md index 9f073f4d..e31c391e 100644 --- a/meta/techniques/gitnexus-operations/cypher.md +++ b/meta/techniques/gitnexus-operations/cypher.md @@ -27,6 +27,6 @@ the query result rows 1. Read `gitnexus://repo/{repo_name}/schema` first to confirm node labels and `CodeRelation.type` edge values. 2. Call `gitnexus_cypher {cypher_query, repo_name}`; the matching `{result_rows}` come back as the result set. - - If the index is out of date, run `npx gitnexus analyze`, then retry. - - If the query references labels or edges not present in the schema, re-read `gitnexus://repo/{repo_name}/schema` and correct the query. + > - If the index is out of date, run `npx gitnexus analyze`, then retry. + > - If the query references labels or edges not present in the schema, re-read `gitnexus://repo/{repo_name}/schema` and correct the query. 3. Reserve this for custom call-chain traces, ordering/error-path assertions, and visibility filters; prefer [impact](./impact.md) / [context](./context.md) / [query](./query.md) when they suffice. diff --git a/meta/techniques/gitnexus-operations/public-api-enum.md b/meta/techniques/gitnexus-operations/public-api-enum.md index b2b5ac97..65151f74 100644 --- a/meta/techniques/gitnexus-operations/public-api-enum.md +++ b/meta/techniques/gitnexus-operations/public-api-enum.md @@ -26,6 +26,6 @@ the exported symbols present in the diff that require documentation ## Protocol 1. Apply [detect-changes](./detect-changes.md) against `{repo_name}` to obtain the changed-symbol set. - - If the index is out of date, run `npx gitnexus analyze` and then retry. + > If the index is out of date, run `npx gitnexus analyze` and then retry. 2. Apply [cypher](./cypher.md) against `{repo_name}` with a visibility filter to keep only public/exported symbols from that set. 3. Return the filtered set as `{public_api_symbols}` — the doc-comment work list. diff --git a/meta/techniques/gitnexus-operations/query.md b/meta/techniques/gitnexus-operations/query.md index 81226f38..e1eab2ff 100644 --- a/meta/techniques/gitnexus-operations/query.md +++ b/meta/techniques/gitnexus-operations/query.md @@ -26,6 +26,6 @@ execution flows (processes) grouped, with member symbols and file locations ## Protocol 1. Call `gitnexus_query {search_query, repo_name}` to produce the `{query_report}` of grouped execution flows. - - If the index is out of date, run `npx gitnexus analyze`, then retry. - - If the concept did not match any indexed flows, broaden the query terms; fall back to grep for pure text patterns. + > - If the index is out of date, run `npx gitnexus analyze`, then retry. + > - If the concept did not match any indexed flows, broaden the query terms; fall back to grep for pure text patterns. 2. Use the processes in the `{query_report}` to orient before deep-diving with [context](./context.md) on specific symbols. diff --git a/meta/techniques/gitnexus-operations/reversibility-signal.md b/meta/techniques/gitnexus-operations/reversibility-signal.md index 9b9a101f..54931d15 100644 --- a/meta/techniques/gitnexus-operations/reversibility-signal.md +++ b/meta/techniques/gitnexus-operations/reversibility-signal.md @@ -26,6 +26,6 @@ the symbol the assumption touches ## Protocol 1. Apply [context](./context.md) against `{repo_name}` for the `{name}` symbol the assumption touches. - - If the index is out of date, run `npx gitnexus analyze`, then retry. - - If the symbol does not resolve, gauge reversibility from the diff and surrounding code instead. + > - If the index is out of date, run `npx gitnexus analyze`, then retry. + > - If the symbol does not resolve, gauge reversibility from the diff and surrounding code instead. 2. Set `{reversibility_class}` from its connectivity: high caller fan-out and broad process participation → `path-committing`; an isolated symbol → `easily-reversible`. diff --git a/meta/techniques/gitnexus-operations/verify-index.md b/meta/techniques/gitnexus-operations/verify-index.md index e505a629..9d73cccd 100644 --- a/meta/techniques/gitnexus-operations/verify-index.md +++ b/meta/techniques/gitnexus-operations/verify-index.md @@ -26,5 +26,5 @@ Boolean — true if the index is out of date ## Protocol 1. Read the MCP resource `gitnexus://repo/{repo_name}/context` and record the reported `{stats}` (symbol / relationship / process counts). - - If no GitNexus index exists for the target repository, apply [analyze](./analyze.md) from the project root, then retry [verify-index](./verify-index.md). + > If no GitNexus index exists for the target repository, apply [analyze](./analyze.md) from the project root, then retry [verify-index](./verify-index.md). 2. If `{index_stale}`, apply [analyze](./analyze.md) before proceeding. When the index is out of date relative to recent code changes, apply [analyze](./analyze.md) to refresh, or apply [analyze](./analyze.md) with `force_rebuild=true` for a full rebuild. diff --git a/meta/techniques/knowledge-base-search/broad-chunks-search.md b/meta/techniques/knowledge-base-search/broad-chunks-search.md index 39365e52..c0da307d 100644 --- a/meta/techniques/knowledge-base-search/broad-chunks-search.md +++ b/meta/techniques/knowledge-base-search/broad-chunks-search.md @@ -16,4 +16,4 @@ Mapped concept from the index. ## Protocol 1. Call `broad_chunks_search { concept: concept_term }`. - - If the local index has no mapping for the search term, retry broad-chunks-search with the natural term and note the gap for future index updates. + > If the local index has no mapping for the search term, retry broad-chunks-search with the natural term and note the gap for future index updates. diff --git a/meta/techniques/knowledge-base-search/chunks-search.md b/meta/techniques/knowledge-base-search/chunks-search.md index 95842998..ff535787 100644 --- a/meta/techniques/knowledge-base-search/chunks-search.md +++ b/meta/techniques/knowledge-base-search/chunks-search.md @@ -20,4 +20,4 @@ Search query ## Protocol 1. Call `chunks_search { source_path, query }`. - - If this returns no results for an indexed path, the local index may be stale (the knowledge base was updated since it was created); fall back to [catalog-search](./catalog-search.md) to rediscover. + > If this returns no results for an indexed path, the local index may be stale (the knowledge base was updated since it was created); fall back to [catalog-search](./catalog-search.md) to rediscover. diff --git a/meta/techniques/knowledge-base-search/load-domain-index.md b/meta/techniques/knowledge-base-search/load-domain-index.md index 573bd155..8c1b1f05 100644 --- a/meta/techniques/knowledge-base-search/load-domain-index.md +++ b/meta/techniques/knowledge-base-search/load-domain-index.md @@ -22,5 +22,5 @@ Parsed source registry, concept lookup table, and topic clusters ## Protocol 1. Locate `{domain_name}-knowledge-index.md` under `.engineering/resources/`. - - If no knowledge-index file is found there for the requested `{domain_name}`, fall back to standard concept-rag search: apply [catalog-search](./catalog-search.md) then [chunks-search](./chunks-search.md). + > If no knowledge-index file is found there for the requested `{domain_name}`, fall back to standard concept-rag search: apply [catalog-search](./catalog-search.md) then [chunks-search](./chunks-search.md). 2. Read the file and parse its source registry, concept table, and topic clusters into the `{domain_index}`. diff --git a/work-package/techniques/dco-provenance/record-attestation.md b/work-package/techniques/dco-provenance/record-attestation.md index aeef29dd..d0d674dc 100644 --- a/work-package/techniques/dco-provenance/record-attestation.md +++ b/work-package/techniques/dco-provenance/record-attestation.md @@ -33,6 +33,6 @@ The updated provenance log, with the attestation section appended 1. Read the certifier identity from `git config user.name` and `git config user.email` at the moment of attestation, so the record carries the identity that will author the commits rather than a value captured earlier in the run. 2. Append an `## Attestation` section to the `{provenance_log}` containing: ISO 8601 timestamp, the certifier identity as `name `, and the selected option. > Record the attestation only after the human has explicitly selected `certify` or `flag-legal`. The attestation is a record of a human decision; it must never be synthesised ahead of that decision. - - If attestation is requested before the human has made an explicit `certify` or `flag-legal` selection, do not append — wait for the selection first. - - If `provenance-log.md` does not exist at this point — meaning no task rows were appended during the work package — surface this to the user: a missing log means something went wrong during task work, so investigate the missing rows before retrying. + > - If attestation is requested before the human has made an explicit `certify` or `flag-legal` selection, do not append — wait for the selection first. + > - If `provenance-log.md` does not exist at this point — meaning no task rows were appended during the work package — surface this to the user: a missing log means something went wrong during task work, so investigate the missing rows before retrying. 3. If `attestation_option = flag-legal`, include a `Legal Review Note` field with the provided `{legal_review_note}` text. diff --git a/work-package/techniques/validate-build/analyze-failure.md b/work-package/techniques/validate-build/analyze-failure.md index 285f7108..7f76b3d8 100644 --- a/work-package/techniques/validate-build/analyze-failure.md +++ b/work-package/techniques/validate-build/analyze-failure.md @@ -30,6 +30,6 @@ Concrete fix approach (file edit, `fmt-fix` invocation, dependency install, etc. ## Protocol 1. Parse the `{failure_diagnostics}` for the failed `{check_id}` and classify into `{$failure_class}`. Compile and test failures cite a `file:line` — resolve that location against `{target_path}` and read it via the harness Read tool. - - If the `{failure_diagnostics}` do not pinpoint a file or symbol, surface the raw `{failure_diagnostics}` to the user rather than guessing. + > If the `{failure_diagnostics}` do not pinpoint a file or symbol, surface the raw `{failure_diagnostics}` to the user rather than guessing. 2. Distinguish flaky from real failures by inspecting the diagnostic surface (e.g., timing-related panics, network errors); mark flaky only when there is a clear signal. Settle on the `{root_cause}` — a one-line statement of why the check failed. 3. Map `{failure_class}` to `{fix_strategy}`: `compile-error` / `test-assertion` → source edit; `formatting-diff` → [cargo-operations](../../../meta/techniques/cargo-operations/TECHNIQUE.md)::[fmt-fix](../../../meta/techniques/cargo-operations/fmt-fix.md); `lint-violation` → either source edit or an explicit allow with justification; `environment` → surface to the user (do not auto-install). When the `{failure_diagnostics}` indicate a missing toolchain, dependency, or external service, refer the user to the project's setup instructions; do not attempt to install or configure the toolchain. diff --git a/work-package/techniques/validate-build/apply-fix.md b/work-package/techniques/validate-build/apply-fix.md index 28cac76a..69ba6405 100644 --- a/work-package/techniques/validate-build/apply-fix.md +++ b/work-package/techniques/validate-build/apply-fix.md @@ -25,4 +25,4 @@ One-line statement of the root cause the fix strategy addresses, so the edit tar 1. Execute the fix per `{fix_strategy}` for the `{root_cause}` behind the check identified by `{check_id}`: source edits go through harness Edit/Write; formatting fixes go through [cargo-operations](../../../meta/techniques/cargo-operations/TECHNIQUE.md)::[fmt-fix](../../../meta/techniques/cargo-operations/fmt-fix.md); dependency or environment fixes are surfaced to the user. - A fix that requires user input or external action is left unapplied; the suite re-run that follows is what reports whether the check now passes. - - If a check keeps failing across successive analyze/fix iterations, surface the latest analysis to the user rather than looping indefinitely. + > If a check keeps failing across successive analyze/fix iterations, surface the latest analysis to the user rather than looping indefinitely. From 4345e590c204188f5185ec7687966920d1285045 Mon Sep 17 00:00:00 2001 From: Mike Clay Date: Thu, 3 Sep 2026 15:41:31 +0100 Subject: [PATCH 3/3] name the schema table rather than count its rows The aggregate URI points at the schemas the table above lists, so the sentence survives the table gaining a schema. Co-Authored-By: Claude Opus 5 (1M context) --- workflow-design/resources/schema-construct-inventory.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workflow-design/resources/schema-construct-inventory.md b/workflow-design/resources/schema-construct-inventory.md index 99372aea..d19b69dd 100644 --- a/workflow-design/resources/schema-construct-inventory.md +++ b/workflow-design/resources/schema-construct-inventory.md @@ -22,7 +22,7 @@ Maps informal patterns (what agents tend to write as prose) to their formal sche | Condition | `schemas/condition.schema.json` | `schemas/README.md — Condition Schema` | | State | `schemas/state.schema.json` | `schemas/README.md — State Schema` | -URI `workflow-server://schemas` aggregates the five schemas. Full ontology, field tables, examples, and validation guidance: `schemas/README.md`. +URI `workflow-server://schemas` aggregates the schemas listed above. Full ontology, field tables, examples, and validation guidance: `schemas/README.md`. ---