Skip to content

Latest commit

 

History

History
897 lines (554 loc) · 66 KB

SPEC.md

File metadata and controls

897 lines (554 loc) · 66 KB

Agent Engineering Workflow and Harness Specification

This document has two parts:

  1. Agent Engineering Workflow Specification — the portable engineering policy.
  2. Minimum Harness Contract — the minimum guarantees required to implement the workflow consistently.

The default profile mapping (GitHub, CI, Agent Redline) lives in DEFAULT_PROFILE.md.


Part I: Agent Engineering Workflow Specification

1. Purpose and Scope

This specification defines how engineers, AI agents, reviewers, and engineering systems deliver software changes from an already-defined product requirement.

Product discovery, prioritization, feature ownership, environment provisioning, runtime security operations, and operational release management are outside its scope.

The workflow begins with an approved epic, story, or equivalent requirement and ends with a reviewed engineering change that has the required pre-merge evidence and approvals.

Standalone read-only analysis — such as review, explanation, diagnosis, comparison, or inspection — is outside this workflow when the request as a whole asks for neither an implementation plan nor a repository change. If the request later expands to either, the workflow begins before that work. An explicit request to use the workflow remains in scope, as does starting, advancing, pausing, or resuming a workflow task.

The workflow is:

Establish Task Context → Discover → Assess Risk and Complexity → Plan and Review → Implement Within Approved Scope → Verify → Review

Every change to which the workflow applies MUST satisfy the purpose and gate of each checkpoint. This does not require a separate document or ceremony for every checkpoint.

Routine work SHOULD use a compact fast path. Higher-risk or more complex work requires stronger planning, review, verification, and recovery state.

When validation can occur only after merge or deployment, the engineering task MUST identify a responsible owner and linked follow-up. The operational validation lifecycle remains outside this workflow.

2. Normative Language

  • MUST / MUST NOT: mandatory
  • SHOULD / SHOULD NOT: expected unless a justified exception exists
  • MAY: optional

3. Roles

Human Engineer

Owns technical intent, resolves material ambiguity, makes or approves important technical decisions, accepts exceptions, and remains accountable for the result.

AI Agent

Investigates the current system, proposes an approach, implements the change, runs verification, and maintains durable work state.

The agent role may be fulfilled by one agent or by a coordinated set of agents. The workflow does not prescribe the orchestration model.

Reviewer

Evaluates a proposed plan or completed result.

A clean-context agent review is performed without the implementation conversation. It reduces anchoring, but does not guarantee independent assurance or remove shared-model blind spots.

A separate human review provides independent judgment. Specialist review may be required for high-risk changes.

An AI review MUST NOT replace human review required by repository, organizational, security, or compliance policy.

Harness

Guides the workflow, maintains the Work Record, applies effective rules, surfaces risk and policy findings, invokes deterministic checks, and prevents invalid transitions where technical enforcement exists.

4. Core Principles

Engineering Starts from Product Intent

Engineering MUST escalate requirements that are contradictory, infeasible, unsafe, or materially ambiguous rather than silently reinterpret product intent.

Human Accountability

Agents may investigate, propose, implement, and verify. Human engineers remain accountable for material decisions, accepted risk, and the delivered result.

Durable State Over Chat

Work MUST remain understandable and resumable outside the current agent session. Chat history is temporary context, not an authoritative record.

Evidence Over Confidence

Completion claims MUST be supported by evidence appropriate to the claim.

Risk-Adaptive Control

Routine work SHOULD remain lightweight. Stronger controls MUST be applied when justified by risk or complexity.

Keep It Simple

The workflow SHOULD reuse existing engineering systems and artifacts. New process, configuration, or tooling SHOULD be added only when it solves a demonstrated problem.

Artifact Proportionality

A task MUST update durable product, architecture, contract, decision, or operational documentation when the change materially affects what that documentation describes.

It MUST NOT create or update artifacts merely to satisfy a uniform document sequence.

Existing authoritative artifacts SHOULD be referenced rather than restated.

5. Control Model

Judgment Boundary

The harness does not decide whether the work is correct; it enforces objective workflow gates and surfaces judgment-heavy risks for review.

It does not validate plan quality, discovery sufficiency, implementation correctness, or evidence adequacy. It surfaces those for reviewer judgment. What the harness can enforce is that the structural artifacts the workflow requires — context, classification, plan, approvals, verification-method references, recovery state — are present, well-formed, and consistent with each other.

Passing CI does not by itself prove that the selected checks are sufficient. The Verification Record (§13.3) is a structured claim that reviewers can challenge, not proof in itself. Adequacy of the chosen verification method remains a review judgment unless the repository defines a deterministic evaluator for the criterion.

Gates

Workflow gates define the conditions for advancing between checkpoints.

The workflow skill SHOULD prevent the agent from advancing when required information is missing. Human review validates judgment-based gates. Automated tools detect objective risks and violations. CI and repository policy enforce deterministic requirements where technical enforcement is available.

A normative requirement does not imply that every violation can be mechanically blocked.

The implementation MUST distinguish between:

  • Guidance: behavior requested from the agent
  • Detection: risks or violations reported
  • Enforcement: actions technically prevented

A requirement MUST NOT be described as enforced unless a technical control blocks its violation.

Workflow Applicability

The workflow applies by default. A repository MAY define a deterministic documentation-only applicability policy that identifies repository-relative documentation, roadmap, and root README paths approved by a human during bootstrap.

An exemption applies only when every path in the complete intended or actual change set is approved and no path is risky, protected, ambiguous, or outside the repository. Any non-exempt path makes the whole change subject to the workflow. Applicability MUST be reassessed when scope changes and against the authoritative diff in CI.

Configuration, policy, schema, CI, agent-instruction, installed harness, configured Work Record, and repository-defined governance surfaces MUST NOT exempt themselves. Missing or invalid policy, incomplete path or risk evidence, and unavailable checks MUST NOT produce an exemption. Independent tests, security checks, architectural boundaries, and repository controls remain applicable.

Permission to work directly on the default branch is separate and lower priority than workflow exemption. It requires explicit human approval, an all-path documentation-only exemption, low-risk classification, and a fresh determination that the actual default branch has no protection or applicable ruleset. Protected, unsupported, stale, or unavailable status denies direct-default-branch work. This permission does not authorize commit or push, bypass branch protection, or replace repository access controls.

6. Work Record

Every engineering task to which the workflow applies MUST have one canonical Work Record.

Each task MUST have one accountable owner and one authoritative workflow at a time. Parallel contributions may share its Work Record when integrated and reviewed as one task. Independently progressing delivery tasks with their own implementation and review MUST use distinct Work Records, linked to the same existing feature or parent when available. Multiple branches, checkouts, or contributors alone do not require separate records. For shared work, the owner controls requirements, approvals, workflow state, integration, and final acceptance; contributors record attributable changes and evidence. Handoffs, replacement checkouts, and ordinary Git copies preserve identity. If supplied identity conflicts with the assignment for an independent delivery, resolve it with the assigner before work; never invent a competing record or fall back to the branch. Section 10 defines optional parent and delivery-task decomposition.

The Work Record is an index and decision log. It stores workflow state and material decisions and links to authoritative evidence in Jira, source control, CI, or other engineering systems.

When a task arrives with an authoritative source item or persisted Work Record identity, the agent MUST preserve and use that identity. It MUST NOT create a competing record from the current branch or duplicate the source item as a local specification. The Work Record may link to the source item and record only task-local decisions and evidence.

The Work Record MUST NOT manually duplicate information that can be resolved reliably from an authoritative system.

Chat history MUST NOT be the only source of required task state.

The Work Record MUST expose, as applicable:

  • Task Context
  • Requirement baseline and Behavior changes, when applicable
  • risk and complexity decision
  • material discoveries, assumptions, and decisions
  • plan and Verification Plan
  • required approvals and review results
  • implementation reference
  • verification evidence
  • blockers, next action, and exceptions
  • linked external follow-up, when required

When an agent stops before completing a task, the Work Record MUST identify:

  • last completed step
  • current branch, workspace, or revision
  • unfinished work
  • known failures or blockers
  • next required action

For Moderate and Large tasks, the Work Record MUST be updated at checkpoint transitions, after material decisions or deviations, and before session end or handoff.

A handoff MUST carry the exact source-item identity, Work Record identity, and resolved repository-relative location when known. Ready for review describes workflow readiness only; it MUST NOT be represented as merged, released, or otherwise delivered without evidence from the system that owns that state.

For an in-scope task with an applicable canonical roadmap item, the agent MUST carry its exact reference and reconcile or report task progress at pickup, pause, resume, handoff, and completion under that roadmap's rules. If a designated owner controls the roadmap checkout, report to that owner without editing, committing, or cleaning it. Task completion MUST NOT imply completion of a broader item with remaining scope. No applicable item requires no roadmap action.

A new engineer or agent MUST be able to resume the work from the Work Record and linked artifacts.

There MUST NOT be multiple competing sources of truth.

7. Routine Fast Path

Routine, simple work MAY use one compact record rather than separate artifacts for each checkpoint.

The compact record MUST contain:

  • outcome and scope
  • risk classification and reason
  • proposed approach
  • verification method
  • current readiness state or blocker

For routine work, an issue-tracker task or equivalent MAY serve as the complete Work Record. No separate Markdown file is required. The Requirement baseline and an exceptional Behavior changes record MUST NOT by themselves force migration from the compact shape.

The minimum readiness states are:

  • Ready to implement
  • Blocked or returned to planning
  • Ready for review

Git and GitHub remain authoritative for implementation, pull-request, CI, approval, and merge state.

Example:

Outcome and scope:
Fix retry handling in WalletService. No public API changes.

Risk:
Routine. Localized and reversible; no sensitive surfaces detected.

Approach:
Reuse the existing retry utility and add a regression test.

Verification:
New regression test plus existing wallet-service CI.

State:
Ready to implement.

8. Risk and Complexity Model

Risk and complexity are assessed separately.

Risk determines required approvals, reviews, verification, and workflow restrictions.

Complexity determines planning depth, task decomposition, and recovery-state requirements.

8.1 Risk Levels

Routine

A localized and reversible change that does not touch known sensitive surfaces.

Typical controls:

  • compact plan
  • agent self-review may be sufficient
  • standard verification
  • normal pull-request review

Elevated

A change with meaningful behavioral impact, uncertainty, or sensitive surfaces.

Typical controls:

  • explicit discovery and Verification Plan
  • non-implementer clean-context agent plan and result reviews
  • additional risk-specific checks

High

A change where failure could materially affect security, tenant isolation, financial integrity, public compatibility, irreversible state, production operation, or regulatory obligations.

Typical controls:

  • non-implementer clean-context agent plan and result reviews
  • human-reviewed and approved plan
  • separate human result review, additive to agent review
  • specialist expertise where required
  • explicit assumptions, invalidation conditions, and stop conditions

Boundary Violation

A prohibited, unauthorized, or policy-violating change.

A boundary violation MUST stop the workflow.

A boundary-violation finding MUST NOT be waived in place. If the underlying action should become permitted, the governing policy must be changed through its own reviewed change, after which the original change is reassessed.

An unclassified path is not proof of intrinsic danger. An effective policy MAY apply a provisional Elevated floor to such a path until it is classified; that floor and any stronger contract, security, persistence, financial, operational, checkpoint, or boundary control MUST remain effective for the current task. An agent MUST NOT demote a red path to gray because a policy seems stale, or treat a proposed relaxation as an approved current-task classification. Explicitly authorized task exceptions under §11 are separate from unilateral reclassification.

8.2 Complexity Levels

Simple

One coherent change, normally in one repository, likely to complete in one working session.

Moderate

Several affected components, meaningful uncertainty, or likely work across multiple sessions.

The Work Record and recovery state MUST be explicit.

Large

Multiple repositories, services, delivery units, agents, or independently verifiable outcomes.

The work SHOULD be decomposed into linked delivery tasks under a parent engineering record.

Each delivery task SHOULD be independently verifiable — it delivers a working slice of the outcome rather than a layer of the implementation. Decomposition by layer (all persistence tasks first, then all service layer, then all API) produces tasks that cannot be verified until other layers exist, defeating the purpose of decomposition for review and recovery.

8.3 Reassessment

Risk and complexity MUST be reassessed:

  • when scope materially changes
  • when an important assumption fails
  • when new affected surfaces are discovered
  • before merge, using the actual final diff

Newly detected risk MUST trigger the required checks, approvals, and reviews.

Automated findings SHOULD contribute where reliable rules exist, but MUST NOT replace engineering judgment about impact, uncertainty, or task coherence.

Classification policy SHOULD learn from ordinary work: when evidence shows a precise path or narrow set is over- or under-classified, the agent SHOULD present the observed paths, evidence, proposed red/blue change, and consequences for human approval. Only an approved, separately reviewed governance change may persist a relaxation. A newly discovered danger raises the current task risk immediately; a proposed relaxation cannot bypass its existing gates. Batch nonurgent suggestions, do not repeat a rejected proposal without new evidence, and do not block otherwise-ready work on an optional future-policy proposal.

Bootstrap SHOULD inspect the actual repository layout and evidence before proposing narrow low-risk zones. Protected, mixed, or genuinely uncertain paths remain conservative. Missing history alone is not a safety finding when inspected code and layout supply sufficient evidence.

9. Workflow Checkpoints

9.1 Establish Task Context

Why: Agents fill gaps confidently. Clear context prevents them from inventing the intended outcome, scope, or definition of done.

Before planning or implementation, engineering MUST record:

  • Outcome: what should be true when complete
  • Target: affected system, service, or repository
  • Scope: what may change
  • Constraints: what must not change or must remain true
  • Completion criteria: observable outcomes that demonstrate success

Task Context SHOULD normally fit in 5 to 10 lines and MUST NOT prescribe the implementation approach.

Bad completion criterion:

Add an idempotency table.

Good completion criterion:

Concurrent retries create only one wallet.

The initial context MUST be sufficient to begin focused discovery.

Requirement baseline and behavior changes

Agents MUST preserve authoritative user requirements and established core product behavior. Before implementing or accepting a material departure, the agent MUST present its exact before/after behavior, impact and alternatives for explicit human review and approval by the applicable authority, even if the Work Record, baseline or configured contracts are unchanged. General task approval, agent review and passing tests MUST NOT substitute for that approval. Existing approval MUST be reused only for the exact departure it covers. Unaffected work SHOULD continue; routine behavior-preserving work requires no additional approval under this rule.

Before discovery or planning, the Work Record MUST capture an immutable Requirement baseline containing the authoritative source reference when one exists and the exact initial Outcome, Scope, Constraints, and Completion criteria. Target is structural identity and is not part of the baseline. New records capture this without human interaction. A legacy record remains parseable but MUST NOT advance until its owner establishes a baseline from an authoritative source; the agent MUST NOT guess one.

Later refinements update current Task Context and MUST NOT rewrite the baseline. On a PR, a branch-created Work Record MUST contain a valid baseline in its first committed version. A legacy record already present on the PR base without a baseline MAY establish one from an authoritative source; a malformed historical baseline is not absence. Once committed, the parsed baseline, including its source, MUST remain unchanged except for an explicitly approved privacy migration below; JSON formatting alone is immaterial. Functional baseline values remain immutable outside the exact paired version-2 redaction. Each behavioral difference from the baseline or a prior approved change MUST appear in an ordered Behavior changes record with exact before and after values. Entries use one of:

  • equivalent — wording or mechanics change without changing required behavior;
  • coverage-only — verification covers more of the same obligation without creating a new product obligation;
  • requirement-change — required behavior is removed, weakened, narrowed, deferred, made manual or best-effort, otherwise redefined, or broadened into a materially new obligation.

A stricter or broader product guarantee is a requirement change, not coverage-only. Scope narrowing is a requirement change even when other Task Context fields do not change.

A requirement-change entry MUST record the reason, impact, alternatives, authority scope, and approval bound to the exact before and after values. Before approval, the task MUST be Blocked and implementation MUST NOT continue under the replacement behavior. After approval, the current Task Context may change, but the baseline and complete ordered chain remain. Approval of one entry does not authorize later or wider changes.

Task-local authority is the human who owns the current requirement. Repository-wide contract authority comes from repository governance. Repository-protected behavior contracts use canonical authority tokens from the last matching CODEOWNERS rule on the PR base revision; required Code Owner review in the hosting platform authenticates user and team approval. A PR cannot authorize itself by changing CODEOWNERS. A Redline checkpoint routes review but is not itself authority. Workflow-protected behavior contracts deliberately have no authenticated repository authority: their exact task-owner / user approval is task-scoped evidence only. The harness MUST disclose that limitation and MUST NOT claim the evidence authenticates repository authority or prevents a manual merge. Clean-context review, plan approval, and risk classification MUST NOT substitute for either repository authority or task-owner approval.

The harness validates structure, exact chain continuity, current-context equality, approval-shaped evidence, and baseline identity against available PR Git history. Reviewers validate the accuracy of the initial baseline, semantic classification, and approval authorship. Git history comparison does not authenticate the original requirement or detect a rewritten branch history; the harness MUST NOT claim otherwise.

Gate: Planning and implementation MUST NOT begin while Task Context is materially unclear, the baseline is missing, a change chain is inconsistent, or a requirement change lacks the required approval.

Baseline privacy migration

Both Work Record shapes MAY carry one optional Baseline privacy migration JSON object containing exactly schema_version, record_path, anchor_commit, replacements, reason, and approval. Version 1 remains source-only: replacements MUST contain exactly one nonempty string, source. Version 2 MUST contain exactly three nonempty strings: source, constraints and completion_criteria. No subsets or other functional fields are supported. record_path is the exact resolved repository-relative Work Record path. anchor_commit is its full checker-selected authoritative Git commit, not a user-chosen convenient ancestor. approval MUST contain exactly by: "user", a nonempty privacy-safe reference, and truthful verbatim evidence of human approval bound to this exact path, anchor and all replacement values. Unsupported keys/versions, duplicate keys and null/no-op replacements MUST fail. Older checkers reject version 2 until explicitly adopted.

The old source MUST be non-null. Original values MUST be read internally from trusted Git history, not repeated or hashed into the public receipt. The receipt and all exact replacements MUST first be committed together in one unambiguous transition. Version 1 MUST preserve all four baseline functional values and compare current Task Context and the existing parsed Behavior changes chain with the immediate pre-redaction record, not merely with an older initial baseline. A missing or malformed historical baseline, deleted/renamed record, ambiguous migration parent or invalid history MUST NOT be repaired by a receipt.

Version 2 MUST replace both baseline/current Constraints and both baseline/current Completion criteria atomically with the source. Before introduction, each current value MUST equal its baseline, and the existing Behavior changes chain MUST NOT target either field. The transition MUST preserve the exact raw existing chain and every other marker field, including Outcome, Scope, Target, classifications, approvals and State; parsed dataclass equality alone is insufficient. Raw comparison uses the history reader's existing newline normalization and MUST NOT impose today's full-record schema on historical snapshots. All three replacements MUST differ from their old values. A receipt grants no authority to change an obligation, transfer a designated role to its current holder, release a hold or reinterpret existing acceptance wording. Human review MUST establish privacy-only equivalence and the same historical owners, reviewers, holds and obligations at the bound revision; existing dynamic obligations remain dynamic.

The receipt and migrated baseline MUST remain unchanged after introduction, including intermediate committed versions; removal, alteration/restoration, a second migration or an in-place version upgrade MUST fail. A receipt already present on the trusted PR base MUST be retained without rebinding its original anchor to each later base revision. Ordinary later Task Context changes remain governed by the existing Behavior changes rules, starting from the migrated baseline; the receipt grants no later functional-change authority.

Migration validation MUST use valid supplied base/head refs and shared history, even for local checks. With no receipt, ordinary local no-ref behavior is unchanged and does not prove that a receipt was never removed. Without a valid receipt the exact whole-baseline comparison remains mandatory. This is not a task exception: baseline and change-chain predicates remain non-waivable.

Reviewers MUST establish that the recorded human approval covers the exact migration and that its public replacement and evidence references are privacy-safe while preserving authority. The checker validates structure, Git bindings, exact atomic replacements and preservation outside the allowed transition; it MUST NOT claim to authenticate approval authorship, determine privacy or semantic equivalence, or detect rewritten supplied history. Other functional-text migrations and redacting existing chain/approval evidence remain unsupported.

9.2 Discover Current State

Why: Plans based on assumptions or stale knowledge often solve the wrong problem or break existing behavior.

Before planning, the agent MUST inspect the relevant current system.

Focused discovery normally includes:

  • affected code and tests
  • repository guidance
  • interfaces and schemas
  • recent related changes
  • relevant design decisions
  • existing verification commands and CI checks
  • logs, incidents, or other evidence when relevant

The agent MUST record only material findings:

  • current behavior and relevant components
  • constraints and dependencies
  • verification capabilities and gaps
  • unanswered questions or assumptions
  • references to inspected evidence

Discovery MUST NOT become an open-ended documentation exercise.

A repository MAY designate one compatible set of authoritative behavior contracts in agent-redline-policy.yaml using one or more unique slash-normalized exact paths or boundary-safe directory patterns ending in /**, a verification identifier for a check that runs on pull requests, and an optional protection of repository or workflow. Other glob syntax is unsupported. Omitted protection means repository for compatibility. Configured paths are red governance surfaces and override excludes and broader blue-zone matches; they MUST NOT qualify for a documentation-only exemption.

Repository protection MUST name a dedicated checkpoint satisfied only by CODEOWNER approval, use a branch-required verification check, resolve every path to the same non-empty canonical CODEOWNERS authority set under last-matching-rule semantics, and rely on required Code Owner review. Workflow protection MUST NOT define a behavior-contract checkpoint or require CODEOWNERS, branch-required status, or required Code Owner review. It still requires both the named verification and the combined Redline/Agent Workflow harness to run on pull requests. Agent Workflow blocks readiness when its behavior predicates fail, but the hosting platform may still permit a manual merge.

For a relevant task, inspect only affected configured contracts. Planning and verification MUST identify whether each affected contract is preserved, coverage-only, or a proposed requirement change, and reference the configured verification surface. Mutation integrity and regression enforcement are separate: protecting contract edits does not prove the configured suite ran or passed. Bootstrap MUST explain both protection choices, require explicit selection, and never downgrade repository protection automatically. It MUST verify live pull-request execution of the named verification and combined harness before persisting either mode. Repository protection additionally requires live evidence for branch-required status, compatible CODEOWNERS coverage, and required Code Owner review. Missing, conflicting, proposal-only, or deferred CI evidence leaves the candidate unconfigured.

When repository guidance, durable documentation, requirements, and observed system behavior disagree on a material point, the agent MUST identify which source is authoritative for that kind of question and resolve the disagreement, or record it as an explicit assumption with a validation condition, before planning proceeds. A disagreement is material when it would change scope, approach, completion criteria, or risk classification.

Gate: Planning MUST NOT proceed while a material uncertainty is neither verified nor recorded as an assumption with a validation or invalidation condition.

9.3 Assess Risk and Complexity

Why: Risk determines required control and validation. Complexity determines planning, decomposition, and recovery needs.

Before detailed planning or implementation, the task MUST receive an initial Risk and Complexity Decision using the shared model and effective group or repository rules.

A mechanical pre-edit classification MAY use the effective deterministic policy and ordinary engineering judgment without a separate classification-only agent. Invoke an independent classifier when uncertainty is material. Planned-path classification is provisional; the final diff and CI checks remain authoritative.

The decision MUST record:

  • risk level and reasons
  • complexity level and reasons
  • triggered rules
  • required approvals and reviews
  • required verification
  • required workflow restrictions
  • whether decomposition is required

Gate: Detailed planning or implementation MUST NOT proceed until the workflow path and task structure are known.

9.4 Plan and Review the Change

Why: Reviewing the approach before coding exposes hidden assumptions, missing failure cases, and unsafe decisions while they remain cheap to change.

For routine work, the plan MAY be a short description of:

  • proposed approach
  • affected surfaces
  • required verification

The plan MUST compare proposed behavior directly with authoritative user requirements and established core behavior under §9.1, not only its Work Record or tests. It MUST identify any durable product, architecture, contract, decision, or operational documentation that requires updating. No documentation update is required when the existing authoritative artifacts remain accurate.

For elevated, high-risk, or complex work, the plan MUST also include:

  • material assumptions
  • unresolved decisions
  • implementation sequence or delivery-task breakdown
  • deviations from existing architecture or conventions
  • stop conditions

For elevated and high-risk work, each material assumption MUST state:

  • what evidence would disprove it
  • what action follows if it is disproved

Example:

Assumption:
The existing request identifier is stable across retries.

Disproving evidence:
Retry requests receive different identifiers.

Action:
Stop implementation and return to planning.

Verification Plan

The plan MUST connect each completion criterion and significant risk to a verification method.

For routine work, the Verification Plan MAY be one sentence or a short checklist.

Existing CI checks are sufficient only when they directly verify the completion criteria and relevant risks.

Verification evidence and result review MUST identify the revision evaluated. Changes made after verification or review MUST cause the affected evidence and findings to be re-evaluated before acceptance.

Example:

Completion criterion:
Concurrent retries create one wallet.

Verification method:
Concurrency integration test.

Authoritative result:
wallet-service CI job for the final revision.

The Verification Plan MAY evolve during implementation. Removing or weakening required verification MUST receive the required approval.

Plan review or approval MUST be repeated only when scope, assumptions, approach, or risk materially change.

Delegation and review SHOULD use the least costly capable reviewer for the actual consequence and uncertainty, while preserving required non-implementer, human, and specialist reviews and user-selected model settings. Reuse still-valid review and verification evidence; do not repeat broad reviews for unchanged material.

When applying an already-reviewed unchanged change, including local installation, completed technical plan and result reviews SHOULD be reused after confirming the applied change's identity and revision match the reviewed material and the destination preserves the reviewed assumptions and risk. The Work Record MUST cite the source review and reviewed revision rather than claim a new review. Only materially uncovered behavior, scope, assumptions, approach, or risk requires further technical review; unchanged covered material MUST NOT restart a broad planning/review cycle. Reuse does not waive applicability, Work Records, destination verification, required human review/approval, or runtime trust.

Plan Review

  • Routine: agent self-review may be sufficient
  • Elevated: a non-implementer clean-context agent MUST technically review the plan
  • High: a non-implementer clean-context agent MUST technically review the plan; a human reviewer MUST also review it, and material decisions MUST receive human approval

The agent reviewer MUST assess risk and planned verification adequacy with appropriate expertise, identify the reviewed plan revision and source evidence, and record findings and disposition. A human review or approval is additive, not a substitute for this agent review. Required approvals MUST be recorded in the Work Record before implementation begins.

Gate: Implementation MUST NOT begin until required reviews are complete, approvals are recorded, and blocking findings are resolved.

9.5 Implement Within Approved Scope

Why: Implementation may drift beyond approved scope, invalidate the plan, or become difficult to resume safely.

The agent MUST implement the approved plan in a dedicated version-controlled branch or equivalent task workspace based on a known revision.

During implementation, the agent MUST:

  • remain within approved scope
  • avoid unrelated refactoring
  • create or update planned tests and checks
  • record material decisions and deviations
  • keep recovery state current
  • pause when an assumption fails or material scope expansion is required
  • stop when a boundary violation is detected

Material scope expansion MUST return the task to context, risk, and planning review before the expanded work continues.

The harness SHOULD detect prohibited or out-of-scope changes where technically possible.

Gate: Work MUST return to planning or human review when it materially diverges from the approved plan or scope.

9.6 Verify the Change

Why: Passing available tests does not prove correctness unless the evidence covers the intended outcome and relevant risks.

The agent MUST run the applicable pre-merge Verification Plan.

Evidence MUST identify:

  • completion criterion or risk being verified
  • check or observation
  • result
  • code revision tested
  • authoritative result reference
  • failures, skipped checks, or approved exceptions

A failed or unavailable required check MUST NOT be presented as success.

Bug fixes SHOULD include a regression test that fails before the fix when practical.

Local verification provides fast feedback. CI is authoritative for automated merge requirements.

Gate: Review may begin while verification is still in progress. The result MUST NOT be approved or accepted until every required pre-merge criterion has sufficient evidence or an explicitly approved exception.

9.7 Review the Result

Why: The implementing agent is biased toward its own solution and MUST NOT be the sole authority that declares the work complete.

The reviewer MUST evaluate:

  • Task Context
  • approved plan
  • Risk and Complexity Decision
  • Verification Plan
  • final diff
  • verification evidence

The review MUST check:

  • whether delivered behavior matches authoritative user requirements and established core behavior, or the exact departures approved under §9.1, rather than only records, implementation or tests
  • whether completion criteria are satisfied
  • whether the recorded verification methods are adequate to the criterion they cover (the harness cannot judge this; it falls to the reviewer)
  • whether tests would detect the relevant failure, exercise its triggering path, and use fakes that reflect the real interface rather than repeat implementation assumptions
  • whether evidence is sufficient
  • whether scope expanded unintentionally
  • whether assumptions remain unresolved
  • whether important security, compatibility, architecture, or operational risks were missed
  • whether the final diff changes the risk classification
  • when the repository already uses a roadmap and this work affects a tracked item's progress or scope, whether its status, shipped scope, remaining scope, next-step claims, placement, and directly affected prerequisites match the result

Review depth depends on risk:

  • Routine: normal pull-request review may be sufficient; reviewer judges verification adequacy as part of normal review.
  • Elevated: a non-implementer clean-context agent MUST technically review the result and independently assess whether the recorded Verification Record is adequate to each criterion. Human review remains mandatory where required by policy or by the affected risk surface.
  • High: a non-implementer clean-context agent MUST technically review the result and independently assess verification adequacy. A separate human reviewer MUST also review the result, with specialist expertise where necessary; this review adds to, and cannot replace, the agent review.

The agent reviewer MUST identify the final revision, inspected source and verification evidence, expertise limits, findings, and disposition. An absent or inadequate agent review MUST NOT be treated as satisfied by human review, approval, or a checkpoint label.

When adequacy is uncertain, the reviewer SHOULD run or request the smallest targeted behavioral check that resolves it, not automatically repeat a passing suite or add another review stage. Unavailable required evidence leaves the gate unsatisfied.

Gate: The change MUST NOT be accepted while blocking findings remain unresolved or unapproved.

10. Parent Features and Delivery Tasks

Large work MAY use a parent engineering record linked to the product epic or story.

Delivery tasks inherit shared context, constraints, decisions, and risk rules from the parent by reference.

Each delivery task MUST record only:

  • its own scope and completion criteria
  • additional discoveries or assumptions
  • risk differences
  • implementation plan
  • verification evidence
  • review result

A child task MUST NOT silently contradict inherited decisions. A required deviation MUST be recorded and approved at the appropriate level.

A small, coherent feature SHOULD NOT create a separate parent record.

11. Extension and Exception Model

The portable workflow defines minimum guarantees.

Groups and repositories MAY define:

  • Work Record location
  • repository guidance
  • risk and complexity triggers
  • required verification
  • reviewers and approvals
  • workflow restrictions

Extensions MAY strengthen requirements. They MUST NOT silently weaken them.

Rule composition works as follows:

  • Additive requirements: apply their union
  • Ordered requirements: apply the stricter value
  • Contradictory requirements: block until resolved

Applicability is decided before task workflow begins and is not a task exception. For work to which the workflow applies, a task exception MUST record:

  • rule being waived
  • reason and scope
  • approver
  • expiry, where relevant
  • compensating validation

Boundary-violation findings are not waivable through task exceptions.


Part II: Minimum Harness Contract

12. Purpose

This contract defines the minimum guarantees required to implement Part I consistently.

A conforming harness does not need a custom workflow engine, dedicated database, or fixed storage schema. It may use existing Jira, source-control, CI, and repository-policy systems.

13. Required Guarantees

A conforming harness MUST provide the following guarantees.

13.1 Canonical Work Record

For work to which the workflow applies, the harness MUST maintain or update one canonical Work Record that exposes:

  • current readiness state
  • Task Context
  • Requirement baseline and Behavior changes, when applicable
  • risk and complexity decision
  • material assumptions and decisions
  • required approvals and review results
  • completion-criterion-to-verification mappings
  • implementation reference
  • blockers, next action, and exceptions
  • linked external follow-up and responsible owner, when required

The record may link to distributed authoritative artifacts.

The harness MUST expose the effective rules and their core, group, repository, or exception source.

A local-file harness MUST provide this read-only lookup command:

python <trusted-install>/scripts/agent-workflow-check.py --repo-root <checkout> --resolve-work-record [--work-record-ref agent-workflow:<slug>]

The executable MUST come from a trusted harness installation, not from the repository being inspected. A valid lookup invocation MUST emit exactly one single-line UTF-8 JSON object followed by a newline, emit no stderr, and use exit 0 for found or absent and exit 2 for error. The complete output, including the newline, MUST NOT exceed 8192 bytes. Its fields are:

{"schema_version":1,"status":"found|absent|error","reason":"<stable code>","work_record_ref":"agent-workflow:<slug>|null","slug":"<slug>|null","record_path":"<slash-normalized repo-relative path>|null","record_state":"Ready to implement|Blocked|Blocked or returned to planning|Ready for review|null","message":"<diagnostic>|null"}

The field combinations are normative:

Status Reason Required non-null fields Required null fields Exit
found record_found work_record_ref, slug, record_path, record_state message 0
absent record_not_found work_record_ref, slug, record_path record_state, message 0
absent workflow_not_configured, current_record_unavailable none work_record_ref, slug, record_path, record_state, message 0
error error reason below message work_record_ref, slug, record_path, record_state 2

Error reasons are limited to invalid_config, unsupported_backend, invalid_work_record_ref, git_unavailable, unsafe_record_path, unreadable_record, malformed_record, and invalid_record_state. message MUST NOT exceed 512 Unicode scalar values. Invalid CLI flag combinations may remain command-line parser errors outside this result contract.

A supplied reference is authoritative. It MUST use the literal prefix agent-workflow: followed by a non-empty slug of at most 255 UTF-8 bytes. The harness MUST preserve its spelling and MUST NOT inspect, compare, or fall back to the current branch. The slug MUST NOT contain control or whitespace characters, /, \, Windows-invalid filename characters (< > : " | ? *), a leading dot, or a trailing dot or space; it MUST NOT be . or .. or a Windows device basename. A valid missing supplied record returns absent/record_not_found; a malformed supplied record returns error without fallback.

Without a supplied reference, the harness derives the slug from git branch --show-current: strip the first matching prefix among slice/, feat/, feature/, fix/, bug/, chore/, and demo/, then replace remaining / characters with -. A detached checkout returns absent/current_record_unavailable; a failed Git invocation returns error/git_unavailable.

A local taskPath MUST contain exactly one {slug}, be repository-relative, and be at most 4096 UTF-8 bytes. Control characters, drive, UNC, absolute, .-component, and ..-component paths are invalid. Before every read and write, the backend MUST resolve links and reparse points against the explicit checkout root and reject a result outside it. Returned record_path values MUST be slash-normalized repository-relative paths no longer than 4096 UTF-8 bytes. Resolution MUST NOT use the common Git directory, another worktree, or a newest/only-record scan.

The lookup only selects and parses a Work Record. It MUST NOT decide readiness, Redline, applicability, consumer scope, merge or release state; create, update, or scan records; or change stored identity. Missing configuration and detached HEAD are absence, not workflow exemption. Automatic consumers MUST NOT execute a repository-provided resolver; without a trusted provider-owned locator they remain degraded or require explicit agent invocation.

Optional source relationships

Both local Work Record shapes MAY carry one Relationships field inside the marker block. Its value is strict JSON, at most 65536 UTF-8 bytes excluding surrounding JSON whitespace (space, tab, CR, LF only) and template hint comments. Native Unicode trimming MUST NOT consume other characters before validation:

{"schema_version":1,"sources":[{"provider":"minimap","scope_ref":"<exact provider scope>","local_ref":"<exact provider item>"}],"pull_requests":["https://github.com/rore/agent-workflow/pull/53"]}

The object MUST contain exactly schema_version, sources, and pull_requests. Version is integer 1, not boolean. sources is null for unverified input, [] only for established no-source, or an array of source objects containing exactly nonempty string provider, scope_ref, and local_ref, with optional safe HTTPS navigation url. Strings MUST NOT contain controls. Identity is the exact three-string tuple; case-folding, Unicode normalization, title matching, reconstructed references, and duplicate tuples are invalid. Navigation URLs are never identity. A missing field is legacy/unknown, not an empty source set.

Optional source navigation uses a shared lexical ASCII authority profile, not native IDNA mapping: HTTPS, ASCII hostname labels of 1–63 characters from letters/digits/underscore/hyphen, at most 253 characters excluding one optional final dot, canonical four-component decimal IPv4, or bracketed IPv6. Punycode labels remain literal ASCII data; acceptance promises neither valid IDNA decoding nor DNS resolution. Numeric/hexadecimal-terminal hostname forms are invalid unless the complete host is canonical IPv4 without a final dot. An explicit port contains only ASCII decimal digits with numeric value 0–65535; leading zeroes are permitted. Userinfo, percent-encoded authorities, whitespace, controls, backslashes, empty/malformed authorities, bracket suffix junk and IPvFuture are invalid, never repaired. Native parsing MAY validate only an isolated bracketed IPv6 address. Otherwise structurally safe literal Unicode hostnames are unsupported, with reason unsupported_source_url; Python retains raw/core data and Node returns its reason-only failure as below. Validation MUST NOT rewrite stored URLs. This approved limitation applies only to optional source navigation: source tuple identity and the GitHub PR profile are unchanged.

pull_requests is an array of recorded PR URL strings, not proof that no other PR exists or that a PR merged. The initial supported profile is https://github.com/<owner>/<repository>/pull/<positive-decimal-number> with ordinary ASCII owner/repository name characters and no credentials, port, query, fragment, encoded/unsafe path or leading-zero number. GitHub host/owner/repository case is ignored for deduplication, not source identity. Stored URLs MUST NOT be silently rewritten. Non-HTTPS URLs, credentials, controls, backslashes or missing host are invalid; otherwise safe unsupported PR hosts/profiles are unsupported. Duplicate PR identities are invalid. No remote status lookup is required.

At creation/pickup, agents MUST copy authoritative supplied sources or resolve an identified feature/issue through its owning tool when exact references are absent. They MUST NOT guess tuples or match by title. Unavailable or ambiguous resolution stays null/unverified: report the missing reference and continue safe independent work; [] is only established no-source. Agents MUST write exact returned sources in the same normal record edit, preserve/correct them during resume/handoff, and append the owning PR tool's URL in the same PR/transition edit. They MUST read back and compare exact expected references. This first slice is agent-performed discovery/edit/check, not automatic incoming capture or proof no reference was missed. It introduces no human backlink task, capture service or evidence sidecar.

The Python parser/renderer MUST retain the exact optional field and readable core record, including unsupported metadata. Relationship validation is separate: malformed JSON/known structure, duplicate decoded keys (including escaped-equivalent keys), duplicate identities, unsafe URLs, overflow and parser/stack failures are invalid; future schema, literal Unicode source hostname or safe unsupported PR profile is unsupported. Identical bytes have identical outcomes regardless of age. Invalid declarations block the relationship predicate; unsupported metadata is a nonblocking diagnostic and MUST NOT turn the whole record into malformed_record. Neither permits guessed or salvaged relationship data. Preserve comment-like JSON string bytes; ignore only surrounding template hints, never comments between JSON tokens. Resolver-v1 meanings, fields and output bounds above MUST remain unchanged.

Trusted passive metadata decoder

Workflow owns a data-only Node ESM decoder bundled with its pinned maintained YAML dependency and license in the trusted distribution. Consumers MUST NOT execute inspected-repository code, require Python solely for display, or add a consumer installation step. There is no second CLI, locator, export file, registry or capture API. Public functions accept raw UTF-8 bytes and lexical paths as data:

decodeConfig(configBytes) -> {status: "ok", task_path}
                         | {status: "invalid"|"unsupported", reason}
decodeRecord(recordBytes, {task_path, record_path})
  -> {status: "declared"|"legacy", work_record_ref, title, recorded_state, relationships}
   | {status: "invalid"|"unsupported", reason}

Both functions MUST reject malformed UTF-8 without replacement. Successful legacy results use relationships: null; declared results return the validated v1 object unchanged. Record decoding enforces one marker block, unique fields, supported core shape/state, exact slug/template mapping and the relationship grammar. Title is the first Markdown H1 when present, otherwise Outcome. This profile does not decide readiness. Failure results contain only status and a stable reason, never invented decoded core/source fields.

Config decoding validates a metadata profile, not whole-Workflow validity: version 1, mappings workRecord/workRecord.local, backend local, and string taskPath under existing lexical rules are required. After rejecting unsafe paths, collapse empty/trailing template components consistently with the backend's returned repository-relative path; do not reject a valid configured layout merely because the filesystem normalized separators. No missing-field defaults; other versions/backends are unsupported. Config input is bounded at 65536 bytes independently of Relationships; there is no whole-record cap. Consumer file/scan caps must surface incomplete coverage, not empty relationships.

YAML supports one mapping document, block/flow mappings, quoted/plain strings, JSON-like scalars and bounded aliases/merge with fixture-defined YAML 1.1-compatible scalar behavior. Explicit keys override merged keys. Duplicate explicit keys, cycles and custom tags are invalid; unsupported constructed standard-tag containers (Set, Date, binary) are unsupported. Library limits bound collection depth to 100, aliases to 100 and merge-key work to 10000. A bounded active/visited traversal rejects unsupported container types before descending, rejects cycles, visits shared objects once and caps unique containers at 10000; it MUST NOT serialize/expand aliases. Parser/stack failures are invalid. This bounded profile does not claim general PyYAML parity or alter the ordinary Python loader.

Consumers own filesystem reads/containment/reparse points, selected checkout/source, configured discovery, Git/content provenance, reverse indexing, snapshots, paging and UI. Unsupported results retain original input/context for partial/error display and record navigation, not verified decoded source indexing or authoritative empty lists. Other valid records/sources remain usable. Recorded state/checkout versions do not prove delivery/merge. One source may have many canonical records/PRs; distinguish canonical identities from checkout versions and unique PR counts from relationship counts without silently truncating completeness.

Shared fixtures owned here MUST prove Python/Node and actual packaged-import conformance: both shapes, legacy/null/none/many, exact Unicode, comment-like strings, escaped duplicate keys, malformed UTF-8/deep JSON, two configured layouts/unsafe paths, URLs/versions, YAML scalar/duplicate/merge behavior and every resource bound. Consumers reuse them and add filesystem/provenance/partial-result/navigation checks. The ordinary resolver remains a separate compatibility contract.

13.2 Readiness Validation

In this contract, readiness means the objective state of the Work Record, evidence, approvals, policy signals, and findings — not correctness or quality. A task is ready when the structural artifacts the workflow requires are present, well-formed, and consistent with each other; whether those artifacts describe a sound plan or sufficient evidence is a reviewer judgment outside the harness's scope (see §5 Judgment Boundary).

The harness MUST validate readiness for:

  • implementation
  • review

Readiness for review MUST include reassessment of risk and complexity against the actual implementation diff. Newly triggered controls MUST be applied before the task is considered ready for review.

For routine work, the Work Record may expose only:

  • Ready to implement
  • Blocked
  • Ready for review

The harness MUST block a missing or malformed Requirement baseline, an inconsistent exact Task Context change chain, and an unapproved requirement change. On PRs with supplied base/head refs, it MUST also block a baseline differing from its first committed authoritative version unless the exact difference satisfies every version-specific privacy-migration guarantee in §9.1. Both refs and shared history are required: a single, missing, invalid, or unrelated supplied ref MUST NOT silently skip the history check. Local runs with neither ref may skip it only when no current privacy receipt requires history validation. A new Work Record must have a valid baseline in its first branch commit; a base-existing legacy record may establish one once. Historical malformed baselines block. Changed Work Record paths remain in scope when deleted or renamed, so missing old paths cannot disappear from the gate. These predicates are non-waivable. The baseline, optional Behavior changes and optional Baseline privacy migration fields remain compatible with both compact and expanded records.

When Redline reports affected behavior contracts, the PR-time checker MUST use the same complete trusted NUL-delimited changed-path evidence used for applicability. The contract gate is global to the change and runs whether zero, one, or multiple Work Records resolve. Missing, incomplete, legacy newline, malformed, unsafe, non-UTF-8, duplicated, non-red, or out-of-diff evidence MUST NOT pass the gate. Rename detection is disabled so both old and new paths are evaluated; deletion, untracked files, Unicode, spaces, and repository containment follow the common changed-path contract. The checker MUST reject unsupported or malformed structured Redline behavior-contract detail. Repository protection uses the existing version-1 detail with per-path owners, verification, and checkpoint. Workflow protection uses version 2 containing explicit protection: workflow, exact path strings, and verification, with no repository-owner or behavior-checkpoint fields. The checker cross-checks version, protection, exact affected paths, verification, and applicable controls against the canonical agent-redline-policy.yaml block to detect missing, stale, or cross-mode detail; this validation is not a second configuration surface.

Every affected contract path MUST have exactly one structured classification in a changed Work Record. Under repository protection, requirement changes MUST name one canonical CODEOWNERS authority token reported for that path and carry approval by the same authority bound to the exact proposed change; task-local user approval cannot substitute. The reported checkpoint MUST remain present as a distinct review-routing control. Under workflow protection, requirement changes MUST instead carry exact task-scoped evidence with authority.scope: task, authority.name: task-owner, and approval.by: user, bound to the proposed before and after values. The checker does not authenticate that user and the hosting platform does not enforce this approval. In both modes, at least one affected Work Record MUST reference the reported verification identifier. Contract classifications, applicable authority or task-owner evidence, approvals, and verification linkage are non-waivable; repository checkpoint satisfaction follows Redline mode plus hosting-platform governance.

The harness may deterministically validate baseline/change JSON, committed baseline identity from supplied PR history, exact Task Context chain continuity, structured Redline payload version and shape, agreement with the current canonical Redline policy, changed-path coverage, canonical owner-token equality where applicable, checkpoint presence where applicable, approval-shaped evidence, and verification-name linkage. It MUST NOT claim to decide semantic equivalence, authenticate a human or team membership, authenticate an external check setting, prove regression execution, prevent a hosting-platform merge, or discover every affected behavior. The legacy agent-workflow.yaml behavior-contract block is invalid; repository behavior contracts have one canonical definition in Redline.

GitHub or equivalent linked systems may provide implementation and completion state.

13.3 Verification Record

Every completion criterion and significant risk MUST identify a verification method. The Work Record MUST reference the resulting check, observation, or approval as a Verification Record carrying:

  • the criterion or risk
  • the verification method
  • the current status
  • an authoritative result reference
  • the revision tested
  • optional rationale

The harness validates the presence and structural well-formedness of the Verification Record's mapping — that each completion criterion is paired with a named method, that the field's grammar parses, that fields aren't empty. It does not validate the content of the evidence: whether the named check actually proves the criterion, whether a referenced result is fresh against the PR head, or whether a recorded status reflects a passing run, are all reviewer judgment outside the harness's scope per §5. A repository MAY define a deterministic evaluator for a specific criterion if it wants to move some of that judgment back inside the harness for that one criterion; absent such an evaluator, adequacy assessment stays with the reviewer.

A generic “CI passed” statement is insufficient unless the referenced CI checks directly cover the criterion or risk. Passing CI does not by itself prove that the selected checks are sufficient.

For Elevated and High work, the required agent result reviewer MUST independently assess whether the Verification Record is adequate to the criterion. Any additionally required human reviewer also assesses it. This is a review obligation, not a harness judgment of adequacy.

13.4 Findings, Checkpoints, and Approvals

The harness MUST preserve:

  • finding or rule identity
  • advisory or blocking disposition
  • explanation and affected scope
  • checkpoint evidence
  • required approvals
  • exception references

Checkpoint satisfaction, plan approval, task-local behavioral authority, and repository contract authority MUST remain distinct.

A clean-context agent review MUST NOT satisfy a human-approval requirement. Human review, approval, or a checkpoint label MUST NOT satisfy a required agent technical review; approval alone is not evidence that either review occurred. Behavioral approvals MUST be scoped to the exact recorded before and after behavior and authority domain.

13.5 Missing Evidence, Unavailable Systems, and Resumability

When required evidence, approval, or policy evaluation is unavailable, the affected gate remains unsatisfied.

A fallback may be used only when the implementation profile explicitly defines it.

The harness MUST NOT convert unavailable evidence into a passing result.

When work stops before it is ready for review, the harness MUST preserve the current implementation reference, unfinished work, known blockers or failures, and next required action.

13.6 Runtime Engagement Parity

A harness that declares support for multiple local agent runtimes MUST define one observable engagement contract for every supported runtime:

  • native skill discovery
  • repository instruction discovery
  • the same applicability-first task seed
  • the same allow, deny, or degraded decision before supported structured file mutations

"Supported" is evidence-scoped. Installation, trust, and direct shared-evaluator success do not prove native interception. Activation evidence MUST identify the runtime version, execution surface, and mutation tool, and MUST show that a denied native operation left its target unchanged. Without that evidence, the runtime/path MUST be reported as degraded, including permission modes or specialized tool paths that bypass or ignore the hook decision.

The mutation decision MUST use one shared evaluator. Its complete path set includes the prospective mutation plus committed branch changes, dirty changes, and untracked files. Creating or repairing only the configured Work Record may proceed so a blocked task can recover; a mixed Work Record-and-code operation does not receive that exception.

On a non-default branch, a mutation may proceed when the complete change is explicitly exempt or the configured Work Record is structurally ready for implementation. On the actual default branch, a ready Work Record is insufficient: the complete change MUST be exempt, direct-default permission MUST be separately recorded, and a fresh protection check MUST report the branch unprotected.

Missing, invalid, or stale workflow evidence MUST NOT be reported as ready or exempt. Pre-invocation runtime-adapter unavailability MAY fail open only as an explicitly reported degraded integration state. Once the shared evaluator starts, failure to complete MUST return a deny decision. The runtime/path is verified only when its native operation honors that decision under the evidence rule above. CI remains authoritative for final workflow artifacts and applicability.

The runtime guard need not parse arbitrary shell commands. When shell mutation is outside the declared supported-tool set, the harness MUST say so: PR CI validates the resulting artifacts but cannot prove pre-edit ordering or prevent direct pushes.

14. Rule and Finding Semantics

Automated tools may produce their own native output formats. The harness only requires equivalent access to:

  • rule or finding ID
  • category
  • advisory or blocking disposition
  • explanation
  • affected paths or evidence
  • required response, when applicable

Blocking findings MUST prevent the affected transition until resolved.

Advisory findings MUST remain visible to the agent and reviewer.

A boundary-violation finding MUST block until the structure is fixed or the governing policy is changed through its own reviewed change.

15. Conformance

A harness conforms when an authorized reviewer can determine from the Work Record and linked systems:

  • whether the task is ready for implementation or review
  • which effective rules apply
  • which findings are unresolved
  • which approvals are required and recorded
  • how completion criteria map to verification methods
  • whether the task may advance

A conforming harness SHOULD:

  • keep routine records compact
  • derive references from authoritative systems where possible
  • avoid copying evidence
  • automate deterministic checks

The harness MUST NOT require a complex state machine when these guarantees can be provided through existing systems and a small workflow skill.