vanillagreencom/kendex/dev

Dev Workflows

orch is the caller and runtime: it owns delegation format, round acceptance, and every shell-shape rule.

Review and QA-review belong to the reviewer skill's workflows/review.md and workflows/qa-review.md. Command shapes are orch's `../orch/SKILL.md` § Harness-Safe Shell; literal format tags and round mechanics are its `../orch/references/skill-rules.md` § Format Tags Are Literal and § Round Closure.

Implementer selection

An agent:X label selects X. With no agent label, use the item's Location paths and required work:

For an item spanning domains, split the delegation by domain. If the selected agent is not installed, report the missing agent to the caller. Never substitute maintainer for runtime or UI implementation.

Engineering Rules

• Scope is the issue's Done-when. A behavioral surface that does not trace to it stays out of this change, and a committed render of a source file you changed traces to whatever its source traces to. Two exceptions:
• the mechanical enablers of landing it ride without tracing to it: locks, changelog, baselines, dismissal renewals, that list and nothing else, never code that runs at runtime;
• a defect the change introduces or arms is in scope by definition, unless Step 0 of `../reviewer/references/finding-disposition.md` excludes it.
• A behavior change ships with the test code-quality admits; the pull request body names an omitted test and the judgement. A workflow sentence ships no test. A test that drives a second implementation or stubs the function under test does not count. Message assertions follow code-quality § Tests.
• A review finding adds a case only when it names a behaviour no existing case reaches. Otherwise it tightens the existing case's assertion, and the item reasoning names that case.
• A second fix round on the same function's guard is recurrence: redesign the rule under test so the class is unrepresentable, and fold the family of cases into one table. Fix an item with an Owner: line at that owner, with one table whose rows cover every state the owner can be in.
• A test whose premise died is deleted whole in the commit that kills the premise, and the PR body names the deletion.
• Test shape is code-quality § Tests and § Prove Your Guards.
• A refusal, a validator, a lock, a retry, or a test exists only for an input a real producer emits, this project's code or anything it calls or serves; name that producer beside it, or do not write it.
• When a change deletes a call, apply code-quality § Cleanup to its callee. Its deletion maps to the call removal's Done-when item; no internal caller is not proof that a supported external API is unused.
• A field, setting, or view member added by the change has a real producer and consumer. A named and documented external producer or consumer is valid when the change adds its in-repository counterpart; otherwise, add both sides in the change.
• Follow the project's declared release compatibility standard for changes to project-owned formats.
• Before adding a function, parser, stub or loop, grep the repo for the verb it performs; before stating a rule, grep for the rule.
• A second copy of that verb, in any language, is a twin and never delegation, and so is a second statement of a rule another file owns, in prose, config or a table.
• Call or cite the one that exists, or escalate in your return. An issue that orders a twin is escalated, not implemented.
• A doc claim the change makes false is updated in the same change; a code change alone owes no doc change. The docs-writing skill states what each document holds.
• Once a commit has been reported to the orchestrator, in a return artifact or in a message naming it, later work adds a commit and never amends, whatever the branch push state. The one exception is a head the orchestrator states is unread: there the orch fix cycle may amend, only to refresh a required check that cannot be rerun.
• A push that prints rebase-map: lines has rewritten the shas the PR's Fixed in <sha> replies name: before holding, re-reply each such thread with the new sha, or post the map as one PR comment naming old and new per line; a sha the map reports as dropped gets a reply that the fix commit no longer exists on the branch.

Code standards are `../code-quality/SKILL.md`: correctness, comments, over-engineering, cleanup.

Round Contract

Execute workflow sections in order; a "Skip if" condition is the workflow's decision, never your own scope assessment. Never push and never open a PR. The orchestrator owns publication order through orch's pr-order resolver. A finding on a mechanism this diff introduces or arms is a fix whatever the round, unless Step 0 of the disposition flow excludes it; a Declined: there takes one of the reason forms `../reviewer/references/finding-disposition.md` § Decision flow sets out, never a label or a test count.

A session keeps the rule text it loaded, and a push, worktree create --reuse or a restack can rebase the branch onto a base that changed that text. A session that already ran a round on this branch runs this diff before the round's first step, [PREVIOUS_ROUND_COMMIT] being the commit its last round reported: git diff --no-renames --name-only [PREVIOUS_ROUND_COMMIT] HEAD -- <each loaded file's repo path>. Before that first step, it reads again each listed file. A listed path it loaded that no longer exists voids the text loaded from it; it reads again the skill's current SKILL.md, or the file that replaced it, in its place.

The completion artifact is the round. dev-return-write writes it after the commit; never hand-author the JSON (schema: orch `schemas/dev-return.md`).

• --issue is the delegation's Artifact Key: line, the workflow-state key where one exists, or the local- key workflow-state new-local-key mints, per `dev-return.md` § Identity: the round id; never the tracker-native OWNER/REPO#N or a bare number. --round-id is its Round ID: line.
• --kind always matches what was delegated. --validate matches your commit message and return. --validate-note carries the test-only validation-ceiling report when that route applies. Flag constraints and value shapes: dev-return-write --help.

Acceptance is that artifact plus git state, never your message. Write the artifact, then return exactly once over the harness's agent-to-agent channel; a disk write is not a return. Send the **Return exactly** body once and go idle. Once the artifact is written, start no validation, test, lint or build run except the admitted stopped-round recovery in dev-implement.md § 5; otherwise the orchestrator validates there next.

Under push-first, queue-only work can close its local round before a pull request exists when dev-validate-run proves that the resolved base requires the merge queue and the configured validation context. Its CI record names ci-event=merge_group and remains pending. The orchestrator's existing queue route proves that required run.

The Codex caller follows orch codex-runtime.md § Delegated round wait while this agent works.

• The channel is Claude Code SendMessage, Codex send_input, OpenCode a resume on the stored task_id, Pi background the final assistant message. Copilot CLI's channel is not yet measured, so this contract names none for it.
• In a Pi persistent pane, follow the return with complete_subagent; background agents must not call it.
• On Codex the send_input MESSAGE is the durable return, and the runtime's FINAL_ANSWER echo of it is expected, not a separate return to author or expand.

Validation

The validation gate and role ownership are complete in dev-implement.md § 5. Validate. For that gate, run no proof, rerun, receipt, isolation step, or approval step that section does not name. That section also owns the one proposed-rule route and verification of the controls code-quality § Tests requires.

A test or sandbox run outside that gate, such as a nested-session smoke run or one test file run alone while investigating, is an investigation run and names its question first. Before it starts, append Run N: question: <what this run decides>; expect: <the result that answers yes or no> to the round notes, [WORKTREE_PATH]/tmp/run-notes-[ARTIFACT_KEY]-[DEV_ROUND_ID].md; after it, append Run N: answer: <yes|no|inconclusive> <one line>. A run with no question line is not started. A second inconclusive in a row on one question sends the agent back to the code and logs, never to a third run. Every run the gate lists is exempt, its must-fail controls included.

Long-Running Validation

Invariant, every harness: the completion tail (commit → QA labels → summary → artifact → return) is never dropped, and an interrupted run is never success. Re-check its real outcome and resume the tail.

On a host whose agent warden reaps orphan scopes, a foreground project entry-point run or an --attached run does not survive its agent's scope. A context handoff with either run in flight holds the stop until the verdict. If the session must stop first, its handoff traps record the interruption, the runner identity, the log and exit-receipt paths, and one recovery route. The successor confirms the old run has stopped, preserves its log and any exit receipt, and reruns only those interrupted checks once. Use the orch job runner or dev-validate-run according to this section's command routes, with a runner that survives the successor's agent scope. Never wait on an orphan queued run whose parent is gone.