fix(meta,work-package): the artifacts checkout is the git target for planning artifacts (#343 corpus) - #360
Merged
Conversation
…planning artifacts The engineering planning folder is a checkout of its own in this repo, so a commit aimed at the host repo puts the artifacts nowhere a published link resolves. Five surfaces stated the single-layout model; each now states the layout it resolves, or cites the one op that owns the choice. commit-and-persist picks the primitive from the layout — commit-submodule when .engineering is its own checkout, commit-regular-files when the artifacts are ordinary files of the host checkout — and states that the parent's pointer bump lands in a PR where that branch takes changes only through one. agent-conduct and manage-artifacts cite the resolving op instead of restating a location; committed-to-parent and push-before-linking were one rule written twice, so the surviving rule is push-before-linking. The Engineering link row and the review-mode Reports base URL carry the planning root as a slot, so a renderer cannot copy either as if one layout were the only one. Publishing is two steps, not a technique that calls another: the technique resolves the ref and the file set, the activity binds manage-git::artifact-commits to put them on the branch. Activity 13 and 14 both bind the pair, and the activity-13 diagram draws the review arm the definition actually walks. verify-outcomes and generate-summary read the session themselves, so the state and trace they read are protocol locals rather than inputs a caller supplies, and meta drops the two variables nothing produced. gitnexus-operations states what the graph answers: code symbols and file paths, not which prose states a claim; keyword-shaped queries; and a freshness check before any operation whose answer turns on the tree. Refs #319, #338, #320, #310
… text The canon audit over the change surface found eight defects in prose this branch authored. Each is fixed here. resolve-before-linking named an activity step from inside a technique rule, scoped to one protocol phase, and restated push-before-linking's invariant; the step order and that rule already carry it, so it goes. The graph's markdown limit folds into query-not-grep rather than sitting beside it: a second rule about when to reach for the graph left the pair intersecting on markdown with opposite consequences and no ordering. The Cypher fragment goes with it, since raw queries live in the operations. infrastructure-submodule-paths is a rule, so it is cited by dotted address rather than the :: form that invokes a technique. The blockquote notes under step 5 gain the trailing spaces that fold them into their parent bullet. target_workflow_outcomes states what the value is, without the reader tail. The engineering planning root is enumerated once, in review-mode; pr-description glosses the slot without restating the arms or naming the step that resolves it.
A rule that points into a Protocol by position rots on the next renumber, and the invariant it carries does not need the position: commit-after-activity constrains which scopes must be committed and pushed before transitions, and which primitive each scope takes is what the Protocol phases are for. The parentheticals naming the primitives come out with the positional reference. agent-conduct and engineering-link-mandatory cite the technique that owns each resolution, without the phase number. sync-progress-status gains the hyperlink that resolves in place of the phase it sat in.
A rule pointing at a Protocol phase by its number sits in a seam four entries leave open. no-rule-protocol-restatement tests whether the sentence could stand as a phase unaltered, and a pointer to a phase cannot. dotted-rule-address governs how a rule is addressed, not how a phase is. anchored-protocol-references asks whether a reference resolves, and an ordinal does resolve — to whichever phase now holds that index. stale-restatement-after-change catches it only once a renumber has already made the claim false. So the entry keys on the ordinal itself, with the insert-a-phase test, and carves out the numbering's own Protocol, heading anchors that fail a guard instead of drifting, and rules addressed by name. The workflow-design version stays where it is: the deprecated tree prints a mismatch warning to every session still running against it (#339).
Reading the live session had no owner. verify-outcomes and generate-summary each named inspect_session and each enumerated the views it accepts, and two work-package techniques cited those two as their home — a citation pointing sideways at fellow callers, which is what an author writes when no operation owns the capability. workflow-engine::read-session owns it now, declaring the variable bag and the execution trace as its products and naming the tool once. The activities bind it ahead of its consumers, so verify-outcomes, generate-summary, retrospective and select-next declare what they read and take it by name. That also repairs #320 C-2 properly. The unproduced state and trace bindings were not contract fiction to delete: the inputs were right and the producer was missing. session_state replaces the bare state id on the way through.
Three entries assume the wrapping operation already exists. canonical-technique-reference fires when a raw tool is named where a wrapper exists; duplicate-shared-capability carves out the case where no shared capability exists yet; and no-duplicated-guidance says to keep one home and reference it, which is satisfied by referencing a fellow consumer — the state this catalogue entry was written from, where two techniques cited two others that also called the tool. So the entry keys on the absence: one tool named for one capability at two or more sites with no operation declaring that capability's product. Its test asks the reader to name the operation a caller would bind, and the sideways citation is the written tell.
…ng body is pr-body-conformance held seven criteria describing the shape of a rendered PR body, inside a technique's Rules. One of them restated a form the guide already carried: the Issue-skipped placeholder, rationale and all, was written out in both files. The criteria are fill rules for a generated document, and that document already has a creation guide, so the guide is where they live — one `###` per criterion, each citable by anchor. The technique keeps the rule name its walker and its two variables reference, now stating the obligation and citing the home. verify-body stops re-authoring the mandated-sections check and cites it instead, which is the split it already had for the templates. render cites the placeholder form rather than a rule that described it. Nothing about the verdict changes: verify-body still emits body_conforms and body_findings, and activity 13 still loops on them.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The corpus PR #343 routes: the artifacts-checkout defect class, closed at every site it lives at, plus the three ride-alongs that share no files with it.
Definition changes only. The paired
maincommit — submodule pointer bump plusnpm run baseline:stamp— is not here; sequence it after this merges.The class
The engineering planning folder is a checkout of its own in this repo. A commit aimed at the host repo therefore puts the artifacts nowhere a published link resolves — which is why a posted review's report links went stale twice in the #346 run, and why
commit-and-persisthas been prescribing the wrong git primitive on every walk.Five surfaces stated the single-layout model. #319 item 6 named four; #338 W2 named the fifth and is the general case the review path's own fix did not cover. Fixing any subset leaves the class live, so they land together.
meta/techniques/workflow-engine/commit-and-persist.mdstep 5 +commit-after-activitycommit-regular-filesfor everything under.engineering/artifacts/infrastructure-submodule-paths—commit-submodulewhen.engineeringis its own checkout,commit-regular-fileswhen the artifacts are ordinary files of the host checkoutmeta/techniques/agent-conduct.mdorchestrator-component-path-scopecommit-and-persiststep 5 for which checkout and which primitive; keeps its own unique duty (no new branch)work-package/techniques/manage-artifacts/TECHNIQUE.mdcommitted-to-parentpush-before-linkingwere one rule written twice —overlapping-rule-scopes, and its single citer cited both in one sentence. The surviving rule namesmanage-git::artifact-commitsas the home for which checkout the commit lands inwork-package/techniques/update-pr/TECHNIQUE.mdengineering-link-mandatorygit remote get-url origin"renderstep 3, which already carried the two-arm resolution the rule contradictedwork-package/resources/pr-description.mdlink-row form/.engineering/artifacts/planning/{ENG_PLANNING_PATH}, defined as relative to the root of the checkout the ref belongs toThe rule this closes is the one a verifier greps, which is what made it the likeliest re-introduction vector.
review-mode's two Lows (#319 items 3–5).engineering/and 404'd — the same defect this PR closes, inside the resource that defines the fix. The segment is now{ENG_PLANNING_PATH}, so the fence cannot be read as single-arm.workflow.yaml, both techniques andartifact-commitsalready use.The third Low —
io-agnostic-contractonreview-summary.md's Input naming its producer — is already fixed onworkflows; the entry now states the meaning without the caller name. Verified, no change here.Publishing is two steps (#319 AP-114)
publish-review-artifacts's Protocol appliedmanage-git::artifact-commitsfor work —pass-orchestration-in-technique, whose Fix directs each sibling operation to its own activity step.Split by what each half produces:
resolve-artifact-publish(renamed frompublish-review-artifacts, since a technique named publish that does not publish is the next reader's trap) resolves the engineering checkout, emits{artifact_publish_ref}and{publishable_files}. One produce path, no::work invoke.manage-git::artifact-commitsas the following step, withfilesandbranchbound from those two outputs.Supplying
filesfrom a declared output is what makes this conversion clean rather than a trade: bindingartifact-commitsdirectly without it would have added anundeclared-seedfinding, the class #336 tracks and which is sequenced behind #342.resolve-before-linkingrecords why the order is not incidental: the link is written only after the step that pushed its target ran.D-6 — the activity-13 diagram (#319)
cpSummaryApproval --> postReviewomitted four steps the definition walks, and #274 made it staler still. The review arm now reads the definition's order, grouping straight runs into one block per the conventionf39c1f52established for the other diagrams. Activity 14's publish node is redrawn for the same split.#320 C-2 — the end-workflow bindings, and the operation that was missing
The first pass read this as a contract defect:
verify-outcomesandgenerate-summaryboth read the session throughinspect_sessionin their own Protocols, sostateandexecution_tracelooked like inputs no caller supplies, and the fix was to delete them.Review found the better reading. The inputs were right; the producer was missing. Reading the live session had no owner anywhere in the tree, and the evidence is a citation pointing sideways:
conduct-retrospective/retrospective.md— "capture session history viainspect_session(same stance as generate-summary / verify-outcomes — not by readingsession.json)"conduct-retrospective/select-next.md— "useinspect_sessionper generate-summary / verify-outcomes"Two
work-packagetechniques reached across a workflow boundary to cite two homes for one fact, using the exact bridge phrasingsingle-rule-authoritynames as the tell. And the tool's permittedviewvalues were enumerated at two sites, which istool-contract-restated-in-protocol.workflow-engine::read-sessionowns it now — one Protocol phase naminginspect_session, declaringsession_stateandexecution_traceas its products, withsession-file-is-not-a-sourceand the reconcile stance cited rather than restated.meta/04-end-workflowandwork-package/14-completebind it ahead of its consumers, so all four former callers declare what they read and take it by name. Composition is an activitysteps[]bind, not a ProtocolApplyfrom each consumer — otherwise it would be thepass-orchestration-in-techniquedefect this same PR removes frompublish-review-artifacts.session_statealso retires the barestateid on the way through, whichio-id-shapelists among the single-word generics.meta/workflow.yamlstill dropsclient_stateandclient_trace— those named the same two values a second time, and the producer now carries them. The third binding stands and was never a defect:target_workflow_outcomesis produced, seeded by the client (work-package/workflow.yaml:133).pr-body-conformance— the guide owns what a conforming body isRaised in review, and two defects were stacked in one rule block.
issue-link-or-explicit-placeholderrestated a formpr-description.mdalready carried — the Issue-skipped placeholder, italicised, no link, "so reviewers can tell the omission was intentional", written out in both files. That isno-technique-resource-dual-home.Underneath it, the block as a whole was seven criteria describing the shape of a generated document, living in a technique's
## Ruleswith no resource home —operative-criteria-need-a-home, whose Fix homes a positive checklist in a resource and leaves the technique a walker. The document already has a creation guide, so the guide is the home.pr-description.mdgains## Ruleswith one###per criterion, each citable by anchor. The technique's rule keeps the name its walker and its two variables reference, now stating the obligation and citing the home.verify-bodystops re-authoring the mandated-sections check — the split it already had for the templates — andrendercites the placeholder form instead of a rule that described it.The model was already inside the block:
all-mandated-sections-presentcited the templates rather than restating them. Its six siblings now read the same way.Nothing about the verdict changes:
verify-bodystill emitsbody_conformsandbody_findings, and activity 13 still loops on them.rule_idkeeps its name insidebody_findings— renaming the field is churn this change does not need.One nuance, since a literal reading of
operative-criteria-need-a-homewould send three of these elsewhere:no-commit-headings-in-changes,no-files-changed-listandno-code-in-changesare prohibitions, and that entry prefers a catalogue entry for a prohibited pattern. But the catalogue governs authored workflow content, not the artifacts workflows produce. A PR body is an output, so the guide is right.#310 Part 2 — what the graph can answer
Three empirical caveats, none of them stated anywhere an agent reads, now in
gitnexus-operations:graph-answers-code-not-prose— forworkflows/,docs/,.engineering/the graph locates a file by path but cannot answer which text states a claim, andqueryreturns unrelated matches rather than nothing, so a miss does not read as a miss.keyword-shaped-queries— the semantic half of the ranking contributes only where the index carries embeddings, which the query cannot assert; keyword-shaped input works either way.index-freshness-firstextended rather than duplicated — a freshness check before any operation whose answer turns on the current tree, because a stale index answers in the same shape as a fresh one.Part 1 stays out per #343: its target is deprecated, and the gap reproduces in
workflow-authoringagainst four activities, not the three #310 names. That is an enhancement with its own scope.Verification
npx tsx scripts/check-all.ts --root <this tree>— 17/17 pass, no baseline or triage file modified.Two things the guards caught in this change, both fixed here rather than triaged:
state/execution_tracebindings surfaced them asorphan-input. Triaging would have recorded the contract fiction as debt; the fix was to stop declaring inputs the technique resolves itself.engineering-link-mandatoryread{eng_git_dir}in a group-inherited rule, where the local is declared inrender.mdand cannot resolve. Threeread-resolutionfindings. The rule now cites the resolution instead of reading its local.binding-fidelityreads 177 triaged, 0 live, 0 untriaged, 0 stale.Deliberately out of scope
work-package/techniques/, the files this PR edits semantically. A mechanical sweep over the same files makes the diff unreviewable, and each cleared seam needs a paired prune ofscripts/binding-fidelity-triage.jsoninmain. Its own PR, after this one, and after #342 repairs the meter.render-token-usageruns on both paths andtoken-usage.mdis cost's only home.scripts/check-binding-fidelity.ts. #343 sequences them before this PR, because #342's masking defect is currently dropping real entries out of the ledger. Read this PR'sbinding-fidelitydelta with that caveat.Issue dispositions
workflow-design), D-3 is environmental, and the "~23 Med/Low" the issue estimated is 4 findings in the actual register: 3 distinct principle defects and 1 anti-pattern Low, all addressed above. Outstanding and deferred items from the review-mode friction continuation session #319 can close.workflow-authoring.usagehalf by feat(tools): per-activity usage accounting and user_request seeding (#324) #329;_meta.trace_tokenremains, and Groups A/B die withworkflow-design. Group D (nine F-items inrequirements-refinement) is untouched.🤖 Generated with Claude Code
Canon audit
Run against the change surface per the workflow-canon Audit path, after the first commit. The second commit is its remediation.
Surface
git diff --name-only origin/workflows. A finding in one of those arrived with this change; anything else pre-existed it.metaandwork-package, each resolved to the file it names.publish-review-artifactshad three (two in activity 13, one in activity 14, all updated);committed-to-parenthad one (update-pr/create-pr.md:35, repointed);workflow-engine::verify-outcomesand::generate-summaryare bound only atmeta/activities/04-end-workflow.yaml—prism-audit/activities/03-audit-finalize.yaml:22has a step namedverify-outcomes, but it is akind: action, not a bind of the meta op, so the contract change reaches no second consumer.origin/workflowsat6bc46faf.meta/techniques/version-control/for the primitive pair,work-package/techniques/manage-git/for the engineering-checkout resolution.Mechanical guards
npx tsx scripts/check-all.ts --root <this tree>— 18 guards, 17 pass, 1 fail.check:deltais blocked for a corpus-only change: it materialises a merge-base in the server repo, and there is none between that repo's HEAD andorigin/workflows. Attribution is by the diff above instead.The one failure is an obligation on the paired
mainPRbinding-fidelity: 161 violations — 73 harmless, 88 fix-later, 0 live, 0 untriaged, 4 stale triage entries.The four are
activity_name,branch,filesandissue_keyonwork-package :: manage-git::artifact-commits(scripts/binding-fidelity-triage.json:963-990, allharmless/shared-op-caller-argument). They are stale because the AP-114 conversion gave that op real producers for all four inputs — it was previously reached by a ProtocolApplywith nothing bound, so the guard saw four unproduced inputs and the triage file absorbed them as accepted debt.That is a result rather than a side effect: the conversion pays down four ledger entries. It also means this PR cannot land alone. The triage file lives in the server tree, so the paired
mainPR must delete those four entries alongside the pointer bump and re-baseline — the same coupling #352 carried for #351: the binds without the prune report four stale entries, the prune without the binds four untriaged findings.Coverage ledger
Nothing is
blockedexceptcheck:delta, recorded above.Findings — eight, all in text this branch authored, all fixed
technique-stage-agnosticresolve-artifact-publish.md—resolve-before-linkingnamed an activity step from inside a technique ruleoverlapping-rule-scopesgraph-answers-code-not-prosesat besidequery-not-grep; both triggers hold for a markdown tree, the prescribed handling differed, and nothing ordered themquery-not-grepdotted-rule-addresscommit-and-persist.mdstep 5 cited a rule with the::form, which invokes a techniqueno-duplicated-guidance{ENG_PLANNING_PATH}two-arm enumeration landed in bothpr-description.mdandreview-mode.mdreview-mode, glossed inpr-descriptionmust-use-operations(the group's own rule)variable-description-one-linetarget_workflow_outcomescarried a "read by…" consumer tailno-resource-caller-backlinkpr-description.mdnamed the host caller ("The rendering step resolves which")constraint-as-blockquote>notes lacked the two trailing spaces that fold them into the parent bulletphase-cited-by-ordinal(new — AP-136)commit-after-activity("the primitive step 5 resolves"),orchestrator-component-path-scope("commit-and-persist step 5"),engineering-link-mandatory("render step 3")No Highs, so the adversarial pass re-derived each Medium from the cited file and construct alone. The one that did not survive re-derivation is marked PLAUSIBLE.
The positional-reference finding came from review, not from my walk, and it is now catalogued as AP-136
phase-cited-by-ordinalbecause it sat in a seam four entries leave open:no-rule-protocol-restatementtests whether the sentence could stand as a Protocol phase unaltered, and a pointer to a phase cannot;dotted-rule-addressgoverns how a rule is addressed, not how a phase is;anchored-protocol-referencesasks whether a reference resolves, and an ordinal does resolve — to whichever phase now holds that index; andstale-restatement-after-changefires only once a renumber has already made the claim false. A correct walk of all four passes over it, which is why the entry keys on the ordinal itself and carries an insert-a-phase test.workflow-design's own version stays where it is: the deprecated tree prints a mismatch warning to every session still running against it (#339), and adding a resource entry is not a reason to pay that.A second entry, from the same route
Review also found that the session read had no owner (see #320 C-2 above). That gap was invisible to three entries, each for a different reason:
canonical-technique-referencefires when a raw tool is named where a wrapping op exists. None existed, so every site was individually correct.duplicate-shared-capabilityexplicitly carves out "adding a new shared op when no shared capability exists yet".no-duplicated-guidancesays keep one home and reference it — and referencing a fellow consumer satisfies that literally. Following its Fix is how the two-home state was reached.So AP-137
unowned-harness-capabilitykeys on the absence rather than the misuse: one tool named for one capability at two or more sites with no operation declaring that capability's product. Its test asks the reader to name the operation a caller would bind; the sideways citation is the written tell. Both new entries are checked against this change, which is where each was found. A phase number in a rule rots on the next renumber, and the invariant does not need it:commit-after-activityconstrains which scopes must be committed and pushed before transitions, and which primitive each scope takes is what the Protocol phases are for. The parentheticals naming the primitives came out with it. One pre-existing instance in the same sentence —Apply sync-progress-status (step 1)— is fixed in passing rather than left beside its own remedy; it now carries the hyperlink that resolves.Worth naming: three of these are defects this PR deletes elsewhere — a rule duplicating another rule's invariant, one fact with two homes, and a rule reaching into a Protocol.
Evidenced negatives
stale-restatement-after-change— the retired claim (parent repo as the artifacts git target) was swept tree-wide, not only across the change's file list. 0 surviving occurrences. The four remainingparent repohits are each accurate:version-control/TECHNIQUE.md:8describes the group's scope,commit-regular-files.md:8,29is the op that genuinely is parent-repo scoped, theanti-patterns.mdhit is exemplar text, and06-plan-prepare.yaml:14concerns the workflows worktree. This is the sweep Outstanding and deferred items from the review-mode friction continuation session #319 F-3 found missing last time, when it had been run for the retired symbol and not the retired claim.preserve-readme-content— the activity-13 review arm went from five nodes to three, so the preservation audit: every step name previously drawn (Consolidate review findings,Generate review summary,review-summary-approval,Post PR review) survives, and four the diagram had omitted are now named. Content increased; only node count fell.no-invented-naming— three new names, each reusing an established convention:{ENG_PLANNING_PATH}beside{ENG_REPO_OWNER}/{ENG_REPO_NAME}/{ENG_BRANCH}; the technique idresolve-artifact-publishbesideresolve-host-repo/resolve-target; kebab-case rule slugs.work-packagesessions exist, five running —plan-prepare×2,start-work-package×2,post-impl-review×1 (scripts/count-workflow-sessions.ts --workflow work-package --list). None sits atsubmit-for-revieworcomplete, so no in-flight worker fetches the retired technique id.checkpoint-entrypasses — the guard that matters for a change reordering steps in activities 13, 14 and meta 04.