project-tiny-context-harness 0.8.0 → 0.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +40 -32
- package/assets/README.md +141 -60
- package/assets/README.zh-CN.md +48 -40
- package/assets/agents/AGENTS_CORE.md +16 -12
- package/assets/context_templates/architecture.md +5 -5
- package/assets/context_templates/area.md +5 -5
- package/assets/context_templates/global.md +6 -6
- package/assets/context_templates/screen-contract.md +18 -18
- package/assets/github/harness.yml +2 -2
- package/assets/skills/context_development_engineer/SKILL.md +7 -5
- package/assets/skills/context_full_project_export/SKILL.md +42 -42
- package/assets/skills/context_uiux_design/SKILL.md +27 -13
- package/assets/skills/design-resource-authoring/SKILL.md +7 -7
- package/assets/skills/design-resource-authoring/references/downstream-handoff.md +12 -12
- package/assets/skills/design-resource-authoring/references/open-design-provider.md +21 -21
- package/assets/skills/design-resource-authoring/references/resource-selection.md +3 -3
- package/assets/skills/long-task-workflow/SKILL.md +17 -17
- package/assets/skills/long-task-workflow/agents/openai.yaml +4 -4
- package/assets/skills/long-task-workflow/references/authority-lifecycle.md +11 -9
- package/assets/skills/long-task-workflow/references/contract-authoring.md +19 -15
- package/assets/skills/long-task-workflow/references/evidence-design.md +18 -17
- package/assets/skills/long-task-workflow/references/source-authoring.md +15 -12
- package/assets/skills/normal-long-task/SKILL.md +12 -12
- package/dist/commands/design-resource.js +2 -2
- package/dist/commands/index.js +26 -26
- package/dist/commands/long-task-authoring.js +83 -9
- package/dist/commands/long-task.js +15 -15
- package/dist/lib/context-graph-snapshot.js +7 -0
- package/dist/lib/design-md.js +5 -4
- package/dist/lib/design-resource-handoff-shape-evidence.js +3 -0
- package/dist/lib/design-resource-handoff-shape-primitives.js +1 -3
- package/dist/lib/design-resource-handoff-types.d.ts +2 -0
- package/dist/lib/design-resource-handoff-validation-coverage.js +1 -0
- package/dist/lib/design-resource-handoff-validation-structure.js +2 -0
- package/dist/lib/doctor.js +2 -2
- package/dist/lib/execution-target-capabilities.d.ts +2 -0
- package/dist/lib/execution-target-capabilities.js +31 -0
- package/dist/lib/long-task-acceptance-shape.js +81 -20
- package/dist/lib/long-task-applicability-shape.d.ts +4 -0
- package/dist/lib/long-task-applicability-shape.js +54 -0
- package/dist/lib/long-task-assertions-v2.js +8 -0
- package/dist/lib/long-task-authoring-preflight-diagnostics.js +5 -0
- package/dist/lib/long-task-authoring-preflight-repair-order.js +3 -0
- package/dist/lib/long-task-authoring-preflight.js +12 -8
- package/dist/lib/long-task-authority-materials.js +46 -4
- package/dist/lib/long-task-authority-policy.d.ts +54 -0
- package/dist/lib/long-task-authority-policy.js +61 -0
- package/dist/lib/long-task-authority-types.d.ts +12 -2
- package/dist/lib/long-task-authority.js +9 -2
- package/dist/lib/long-task-check-shape.js +6 -1
- package/dist/lib/long-task-claim-definitions.js +27 -42
- package/dist/lib/long-task-claims.js +275 -146
- package/dist/lib/long-task-contract-types.d.ts +42 -8
- package/dist/lib/long-task-control-fields.d.ts +12 -0
- package/dist/lib/long-task-control-fields.js +66 -0
- package/dist/lib/long-task-control-types.d.ts +1 -0
- package/dist/lib/long-task-control-types.js +1 -0
- package/dist/lib/long-task-counterfactual-claim-policy.js +7 -0
- package/dist/lib/long-task-counterfactual-sandbox.js +1 -2
- package/dist/lib/long-task-counterfactual-types.d.ts +12 -0
- package/dist/lib/long-task-delivery-compiler.js +1 -0
- package/dist/lib/long-task-delivery-preflight.js +24 -0
- package/dist/lib/long-task-delivery-shape.d.ts +1 -0
- package/dist/lib/long-task-delivery-shape.js +1 -0
- package/dist/lib/long-task-delivery-types.d.ts +1 -0
- package/dist/lib/long-task-delivery-types.js +1 -0
- package/dist/lib/long-task-delivery-validation.js +46 -0
- package/dist/lib/long-task-design-resource-handoff.js +48 -7
- package/dist/lib/long-task-evidence-capability-codec.js +37 -0
- package/dist/lib/long-task-evidence-capability-policy.js +80 -38
- package/dist/lib/long-task-evidence-capability-runtime.js +36 -0
- package/dist/lib/long-task-evidence-capability-types.d.ts +13 -1
- package/dist/lib/long-task-evidence-findings.js +3 -0
- package/dist/lib/long-task-evidence-sensitivity-policy.js +38 -0
- package/dist/lib/long-task-evidence-v2.js +7 -1
- package/dist/lib/long-task-final-integrity.d.ts +16 -0
- package/dist/lib/long-task-final-integrity.js +98 -0
- package/dist/lib/long-task-final-v2.js +17 -34
- package/dist/lib/long-task-outcome-parser.js +22 -4
- package/dist/lib/long-task-playwright-case-evidence.d.ts +2 -0
- package/dist/lib/long-task-playwright-case-evidence.js +10 -2
- package/dist/lib/long-task-playwright-evidence.d.ts +1 -0
- package/dist/lib/long-task-playwright-evidence.js +32 -0
- package/dist/lib/long-task-product-shape.d.ts +3 -1
- package/dist/lib/long-task-product-shape.js +100 -4
- package/dist/lib/long-task-requirement-shape.js +3 -0
- package/dist/lib/long-task-root-shape.js +12 -6
- package/dist/lib/long-task-runner-freeze.js +16 -0
- package/dist/lib/long-task-runtime-types.d.ts +11 -2
- package/dist/lib/long-task-semantic-assurance-policy.d.ts +4 -0
- package/dist/lib/long-task-semantic-assurance-policy.js +52 -0
- package/dist/lib/long-task-semantic-contract-types.d.ts +18 -1
- package/dist/lib/long-task-semantic-drift-migration.js +33 -2
- package/dist/lib/long-task-semantic-mutation.d.ts +7 -0
- package/dist/lib/long-task-semantic-mutation.js +81 -0
- package/dist/lib/long-task-shape-primitives.d.ts +1 -1
- package/dist/lib/long-task-shape-primitives.js +1 -0
- package/dist/lib/long-task-source-authority-types.d.ts +2 -0
- package/dist/lib/long-task-source-item-parser.d.ts +1 -1
- package/dist/lib/long-task-source-item-parser.js +150 -104
- package/dist/lib/long-task-source-markers.d.ts +12 -0
- package/dist/lib/long-task-source-markers.js +146 -0
- package/dist/lib/long-task-source-target-continuity.d.ts +1 -1
- package/dist/lib/long-task-source-target-continuity.js +80 -55
- package/dist/lib/long-task-source-target-index.js +7 -29
- package/dist/lib/long-task-status-v2.d.ts +1 -0
- package/dist/lib/long-task-status-v2.js +2 -2
- package/dist/lib/long-task-target-policy.js +20 -0
- package/dist/lib/long-task-ui-design-policy.js +27 -1
- package/dist/lib/long-task-ui-surface-shape.js +21 -1
- package/dist/lib/long-task-ui-surface-types.d.ts +7 -0
- package/dist/lib/long-task-verification-preview.d.ts +10 -0
- package/dist/lib/long-task-verifier-dependency-closure.d.ts +3 -0
- package/dist/lib/long-task-verifier-dependency-closure.js +179 -0
- package/dist/lib/long-task-verifier-v2.js +12 -2
- package/dist/lib/long-task-workspace.js +5 -1
- package/dist/schemas/long-task-delivery-v2/long-task-delivery-v2.schema.json +99 -25
- package/migrations/README.md +8 -8
- package/package.json +84 -84
|
@@ -7,21 +7,21 @@ description: Author, preflight, execute, resume, verify, or close one complete S
|
|
|
7
7
|
|
|
8
8
|
## Boundaries
|
|
9
9
|
|
|
10
|
-
Use one current native Goal, one repository, one selected workspace, one complete Contract and one Final Gate.
|
|
10
|
+
Use one current native Goal, one repository, one selected verification workspace, one complete Contract and one Final Gate. This workflow never creates or manages a scheduler, model worker, agent runtime, App Server, branch/worktree fan-out, merge, push, PR, deployment, Campaign/SFC/Packet/Wave chain, matrix, verdict or second Contract plan. The current Goal may optionally use one or multiple platform-native agents/subagents or user-authorized Git parallelism as implementation means. Harness never allocates, schedules, retries or recovers them; their reports are not Progress or proof, and every result must converge into the selected verification workspace before verification counts. Never activate from task size alone.
|
|
11
11
|
|
|
12
|
-
The host and user own model selection and native-Goal lifecycle. The workflow has exactly one user-choice checkpoint after the first Authority Lock and before implementation; Harness neither switches the model nor persists model-routing/checkpoint state. No checkpoint file, acknowledgement state, model route, model-tier scheduler, automatic model switch, `authority_revision_in_progress` state or native-Goal completion state is created. Outside that boundary, do not pause a healthy Goal solely to change or downgrade the model. Do not create a separate approval checkpoint for a defensible recommended plan choice. A targeted pre-Authority clarification is still required when a missing user preference could materially change research or selection; genuine Source conflicts or choices the user explicitly reserves may likewise require a decision before Authority Lock. Capability-related drift is handled by targeted repair plus the Final Gate.
|
|
12
|
+
The host and user own model selection and native-Goal lifecycle. The workflow has exactly one user-choice checkpoint after the first Authority Lock and before implementation; Harness neither switches the model nor persists model-routing/checkpoint state. No checkpoint file, acknowledgement state, model route, model-tier scheduler, automatic model switch, `authority_revision_in_progress` state or native-Goal completion state is created. Outside that boundary, do not pause a healthy Goal solely to change or downgrade the model. Do not create a separate approval checkpoint for a defensible recommended plan choice. A targeted pre-Authority clarification is still required when a missing user preference could materially change research or selection; genuine Source conflicts or choices the user explicitly reserves may likewise require a decision before Authority Lock. Capability-related drift is handled by targeted repair plus the Final Gate. The current Goal may choose platform-native internal delegation, but Harness owns no subagent dispatch/retry/recovery state, delegated reports are not Progress or proof, and all outputs must converge into the selected verification workspace before verification can count.
|
|
13
13
|
|
|
14
14
|
`long-task-delivery-v2` is the only active Contract schema. `delivery-contract.yaml` is the root authoring file. New authoring uses inline Outcomes; existing `outcome_files` are physical compatibility only. `delivery-set` is retired and non-executing.
|
|
15
15
|
|
|
16
16
|
## Controlling Objective
|
|
17
17
|
|
|
18
|
-
Prevent false completion inside declared authority. Implementation may drift, fail or require rework, but every declared non-Result requirement and AC must remain traceable and every unsatisfied, unverifiable, insufficiently evidenced or
|
|
18
|
+
Prevent false completion inside declared authority. Given complete and accurate Source at the declared observable granularity, a meaning-preserving Source-to-Contract projection, complete applicability expansion and a sound named verifier/runner trust boundary, `AcceptedDeliveryTerminal` must imply that no declared observable drift remains. Implementation may drift, fail or require rework, but every declared non-Result requirement, exact applicability cell and AC must remain traceable and every unsatisfied, unverifiable, insufficiently evidenced, stale or externally pending item must block or explicitly qualify complete delivery. In particular, unclassified Source, an omitted architecture obligation, Control field/relation, population-universe member, wrong target/condition/input/state/journey, proxy target, presence text, degradation path, fixed input, self-reported boundary effect, weak semantic oracle or internal entrypoint must never substitute for declared behavior. Findings should localize repair through Source Item, Stage, Outcome, Claim, applicability, Assertion, Check, Evidence Capability, execution target, Binding and owner boundary.
|
|
19
19
|
|
|
20
|
-
For selected design resources, one design-specific objective is that Agent implementation, acceptance and testing fully conform to every material UI/UX fact explicitly expressed within declared scope and conditions. Open Design can produce source-rich, implementation-readable resources, but capability alone is not a guarantee: resource authoring must require a canonical entry, complete dependency acquisition and stable machine-resolvable facts. The validated `design-resource-handoff-v1` remains the residual scope/applicability/semantic adapter rather than a copy of CSS values. Preserve each fact through immutable inputs, typed locators, complete subject × target × condition × dimension cells, Context-reachable targets, Source/Control/Claim authority, one independent Assertion per verification method and current-snapshot project Checks to Final Gate. Never invent an unexpressed fact: refine the resource, retain `decision_required`/`unavailable`, or block fidelity work. Neither provider success, file hashes nor handoff integrity proves production conformance.
|
|
20
|
+
For selected design resources, one design-specific objective is that Agent implementation, acceptance and testing fully conform to every material UI/UX fact explicitly expressed within declared scope and conditions. Open Design can produce source-rich, implementation-readable resources, but capability alone is not a guarantee: resource authoring must require a canonical entry, complete dependency acquisition and stable machine-resolvable facts. The validated `design-resource-handoff-v1` remains the residual scope/applicability/semantic adapter rather than a copy of CSS values. Preserve each fact through immutable inputs, typed locators, complete subject × target × condition × dimension cells, Context-reachable targets, Source/Control/Claim authority, one independent Assertion per verification method and current-snapshot project Checks to Final Gate. Never invent an unexpressed fact: refine the resource, retain `decision_required`/`unavailable`, or block fidelity work. Neither provider success, file hashes nor handoff integrity proves production conformance.
|
|
21
21
|
|
|
22
|
-
Only fresh evidence from the complete current final snapshot may create machine acceptance. Otherwise report the task as unfinished or qualified. `machine_accepted_external_pending` means machine-verifiable authority passed while named external confirmation remains; it is not full delivery completion. Machine acceptance
|
|
22
|
+
Only fresh evidence from the complete current final snapshot may create machine acceptance. Exactly fresh `machine_accepted` with no pending External Confirmation is `AcceptedDeliveryTerminal` and may support the full declared-observable no-drift conclusion. Otherwise report the task as unfinished or qualified. `machine_accepted_external_pending` means machine-verifiable authority passed while named external confirmation remains; it proves only the declared machine scope and is not full delivery completion. Machine acceptance has no direct native-Goal effect. Never substitute prose, progress, historical tests, Receipts, one exit code or Agent judgment for the Final Gate.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
Anti-Degradation Assurance requires current-implementation Context to match the indexed code/runtime and protects the controlling purpose, enabling key logic, two jointly necessary implementation responsibilities, theorem boundary and adjacent `F = Implementation Freedom Boundary` from implicit weakening. `F` is an efficiency/anti-process-bloat invariant, not a third responsibility or no-drift theorem premise: within declared Source/Contract, architecture, security, forbidden-shortcut, irreversible-effect and external-action boundaries, the current Goal owns implementation order, methods, local feedback cadence and optional one-agent or multi-agent/subagent execution. Harness must not add a development phase/method permission Gate, per-edit verification mandate, agent allocator/scheduler, delegation proof or persistent delegation state. Replacing any protected invariant requires an explicit project-owner design-purpose decision and replacement proof; a new development-stage constraint must additionally identify a distinct path that final proof or a lighter project-owned check cannot cover and have positive net ROI. Agent inference, coordinated edits or cost alone do not authorize it. Mechanism changes use a two-stage hard gate. First prove `Coverage_new ⊇ Coverage_old`, `FalseNegative_new ⊆ FalseNegative_old`, and that Authority, fail-closed behavior and complete-current-final-snapshot proof cannot be bypassed. If non-degradation cannot be proved, preserve the current formal acceptance path. Only after that gate passes may positive net ROI compare incremental anti-degradation or purpose benefit with every incremental Authoring, Runtime, State, Recovery, maintenance, test, process, introduction and migration cost. No cost reduction compensates for weaker drift interception; positive net ROI permits consideration but never overrides the first gate. This creates no second Authority, Gate or state.
|
|
25
25
|
|
|
26
26
|
## Progressive Reference Loading
|
|
27
27
|
|
|
@@ -38,41 +38,41 @@ Do not copy reference detail into another plan or state file. The same `delivery
|
|
|
38
38
|
|
|
39
39
|
Every input enters the same non-authoritative `delivery-contract.yaml` Draft immediately. Before the first successful formal Compile, continuously revise that Source-bound Draft while real Source inventory, provenance, refinement, markers, repository binding and mapping converge. It need not be completed in one response; keep reading Source, repository and relevant Context and feed Preflight findings back into that same Draft. Draft authoring, Preflight, Compile, rolling execution, targeted verification and Final Gate are one `long-task-workflow` lifecycle. Do not create a Source-authoring phase, standalone Contract Draft Skill, Draft Receipt, Authoring State, draft schema/CLI/runtime state or second plan.
|
|
40
40
|
|
|
41
|
-
A Draft Outcome is an Outcome in that pre-Authority-Lock Draft, not a new schema field or runtime entity. Decompose only vertical, independently observable, decidable and target-verifiable results whose dependencies and owner boundary can be stated; one Outcome belongs to one declared Stage and does not span materially different success paths. Declare the ordered Stage DAG and one gate Outcome per Stage in the same Contract. Use those boundaries to
|
|
41
|
+
A Draft Outcome is an Outcome in that pre-Authority-Lock Draft, not a new schema field or runtime entity. Decompose only vertical, independently observable, decidable and target-verifiable results whose dependencies and owner boundary can be stated; one Outcome belongs to one declared Stage and does not span materially different success paths. Declare the ordered Stage DAG and one gate Outcome per Stage in the same Contract. Use those boundaries to project an acceptance/verification-ready working set, bind target verification, localize failures, resume findings/next actions and stale local results precisely; never use them to restrict which in-scope implementation edit may happen next.
|
|
42
42
|
|
|
43
|
-
`depends_on` means acceptance readiness. The gate Outcome transitively depends on the rest of its Stage, later Stage Outcomes depend on prerequisite gate Outcomes, and every multi-Outcome gate proves cross-surface consistency. The current Goal derives a temporary Rolling Frontier from Stage and Outcome status, but
|
|
43
|
+
`depends_on` means acceptance and intermediate-proof readiness, not implementation permission. The gate Outcome transitively depends on the rest of its Stage, later Stage Outcomes depend on prerequisite gate Outcomes, and every multi-Outcome gate proves cross-surface consistency. The current Goal derives a temporary advisory Rolling Frontier from Stage and Outcome status, but may implement, inspect or repair any in-scope Outcome in the order current code reality favors. Do not persist a Stage Receipt, scheduler, Worker queue, mandatory implementation DAG, model route or process tree. Never split for response/YAML/file length, implementation layer, module/file count, Agent capacity, Worker assignment or desired parallelism.
|
|
44
44
|
|
|
45
45
|
> Outcome decomposes execution and diagnosis, not completion authority.
|
|
46
46
|
|
|
47
47
|
## Entry And Authoring Loop
|
|
48
48
|
|
|
49
49
|
1. Read the user request or external initial proposal, selected design resources and minimum controlling Context. Collect the architecture owners, extension points and boundaries needed for the shared deliberation before deciding `Context Delta`.
|
|
50
|
-
- For material production UI, read the Contract-authoring visual guidance before Compile. When selected resources arrive as an implementation handoff, require one marked `design-resource-handoff-v1` in `task.source_paths` and run `ty-context design-resource preflight <handoff.md>`; incomplete applicable cells, unsupported evidence, unresolvable locators, partial implementation-source acquisition, unresolved meaning or stale resource identity is blocking. Traverse affected surface/control/target keys from owning Context through `DESIGN.md`, then open every affected selected `exact-target` or `constraint` as Context-reachable ordinary Source. Confirm selection basis, readable immutable identity/digest, declared surface/viewport/mode/state coverage and editable upstream owner/locator/update route. A registry or handoff index mention is not consumption. Missing, stale, unreadable, truncated or conflicting resources remain `decision_required`; if only the editable upstream is unavailable, the immutable target may guide implementation but requested resource edits remain a manual/external boundary. An unconfigured starter, candidate, style-only rule or inspiration-only reference is incomplete design authority unless Source explicitly scopes the result as prototype/non-fidelity or supplies a selected target before implementation. When Controls exist, bind them through Product `surface_bindings` to the required production target, existing route/component Bindings and a root-entry journey; each selected target's identity/conditions/files, covered Source Claims/root Assertion, per-method independent Assertions and blocker lineage must match the handoff before typed evidence can prove it.
|
|
50
|
+
- For material production UI, read the Contract-authoring visual guidance before Compile. When selected resources arrive as an implementation handoff, require one marked `design-resource-handoff-v1` in `task.source_paths` and run `ty-context design-resource preflight <handoff.md>`; incomplete applicable cells, unsupported evidence, unresolvable locators, partial implementation-source acquisition, unresolved meaning or stale resource identity is blocking. Traverse affected surface/control/target keys from owning Context through `DESIGN.md`, then open every affected selected `exact-target` or `constraint` as Context-reachable ordinary Source. Confirm selection basis, readable immutable identity/digest, declared surface/viewport/mode/state coverage and editable upstream owner/locator/update route. A registry or handoff index mention is not consumption. Missing, stale, unreadable, truncated or conflicting resources remain `decision_required`; if only the editable upstream is unavailable, the immutable target may guide implementation but requested resource edits remain a manual/external boundary. An unconfigured starter, candidate, style-only rule or inspiration-only reference is incomplete design authority unless Source explicitly scopes the result as prototype/non-fidelity or supplies a selected target before implementation. When Controls exist, bind them through Product `surface_bindings` to the required production target, existing route/component Bindings and a root-entry journey; each selected target's identity/conditions/files, covered Source Claims/root Assertion, per-method independent Assertions and blocker lineage must match the handoff before typed evidence can prove it.
|
|
51
51
|
- If the user is asking to generate or iterate standalone design resources before Contract authoring rather than execute this delivery, use `design-resource-authoring` instead. Its result may later return as ordinary Source; it creates no Contract Draft or Authority.
|
|
52
52
|
2. If a valid active binding exists, run `ty-context long-task resume <workdir>` and read the lifecycle reference.
|
|
53
53
|
3. Start one complete Delivery Contract Draft for the whole selected delivery immediately. If inputs are not self-contained, apply the Source-authoring reference inside this same Draft loop: inventory every proposal/resource/attachment, refine the writable real Source, preserve traceable provenance and resolve or retain genuine decisions while mapping target profile, Stages, Outcomes and repository evidence. Conversation-only material becomes exactly one project-native Markdown Source. Source completeness is a Preflight/Compile convergence requirement, not an earlier internal stage.
|
|
54
|
-
4. Preserve at least one real `source_path`. Wrap every material Source item in its original Markdown with non-rendering `ty-source-item:start/end` markers without rewriting direct text; marked Source Item keys and `source_claim` keys are exactly equal. Newly delegated meaning must first be written into
|
|
55
|
-
5. An ordinary prose proposal, legacy Source Plan or externally authored design resource remains valid Source and does not need to match a recommended structure. Preserve stable semantic keys and Markdown anchors where practical. Selected resources retain their stable resource/surface/control/state/target keys, declared applicability, source profile/entry/dependency set, provider/project/run provenance, typed locators, immutable digest/snapshot and editable upstream owner/locator/update route. Candidates authorize no fidelity Claim. Changing an adopted resource produces a new immutable version and updates the owning reference rather than overwriting the locked baseline.
|
|
54
|
+
4. Preserve at least one real `source_path`. Wrap every material Source item in its original Markdown with non-rendering `ty-source-item:start/end` markers without rewriting direct text; marked Source Item keys and `source_claim` keys are exactly equal. Every delivery declares at least one `technical_obligation` Source Item with `aspect=architecture` and maps it to an independently provable architecture obligation. `ty-source-background:start/end` is restricted to text-free Markdown anchors/horizontal rules (`reason=markdown-structure`) or fixed-field `ty-source-provenance` comments (`reason=provenance`); text-bearing headings, free-form provenance and arbitrary explanatory prose are material or unclassified, never background. Leave the single strict design-resource handoff block to its formal parser. Every other non-empty line is unclassified and blocking. Never label requirement, acceptance, technical, risk or decision meaning as background. Newly delegated meaning must first be written into real Material Source with provenance before its corresponding Draft meaning can pass Preflight/Compile.
|
|
55
|
+
5. An ordinary prose proposal, legacy Source Plan or externally authored design resource remains valid Source and does not need to match a recommended structure. Preserve stable semantic keys and Markdown anchors where practical. Selected resources retain their stable resource/surface/control/state/target keys, declared applicability, source profile/entry/dependency set, provider/project/run provenance, typed locators, immutable digest/snapshot and editable upstream owner/locator/update route. Candidates authorize no fidelity Claim. Changing an adopted resource produces a new immutable version and updates the owning reference rather than overwriting the locked baseline.
|
|
56
56
|
6. Continue reading repository, Source and Context and revise the same Draft. A request to synthesize, refine, complete, implement or use judgment delegates plan-level authoring, but it does not invent the user's tradeoff priorities. Before comparative research or a material product, technical, architecture or provider selection, identify the criteria that could change the research scope, candidate set or recommendation. Infer them only from the user's words, Source, Context or controlling constraints. If quality versus cost, speed, reliability, privacy, lock-in, operational burden or another material priority is unknown or ambiguous, stop before that research or selection and ask one concise targeted clarification. Do not impose a questionnaire, re-ask known preferences or interrupt minor reversible choices whose recommendation would not change.
|
|
57
57
|
7. Once the material preference envelope is clear, decide what research is needed. Use current authoritative or primary evidence for external capability, pricing, quota, license, compatibility, region, security posture or support claims. When one recommendation is then defensible, record it in real Source with the authoring instruction, preference/evidence basis and exact added meaning instead of pausing for approval. Append the delegated item without rewriting the user's original text when ordinary prose is the Source. Return only when authoritative requirements conflict, the user explicitly reserves the choice, a material preference remains unknown, critical semantics have no defensible recommendation or no falsifiable acceptance standard can be formed.
|
|
58
58
|
8. Contract expansion remains limited to meaning-preserving structural decomposition, evidence-backed repository binding and choices first recorded as delegated real Source. Never place a new product rule, default, threshold, recovery behavior, permission or platform/data scope only in Contract YAML. Default plan delegation authorizes meaning, not action: payment, contracting, production deployment or publication, destructive production mutation, real permission grants, sensitive-data transmission and required legal/security/human approval remain named external confirmations. Any conflicting, user-reserved, missing-preference or unsupported semantic remains `decision_required`.
|
|
59
59
|
9. Before formal Compile and the first implementation edit, complete the shared `Architecture Deliberation` once and surface concise repository-bound conclusions rather than private reasoning. Cover the current owner/extension point/source of truth, dependencies and lifecycle, selected and rejected alternatives, a plausible future-change challenge, touched debt and its disposition, forbidden shortcuts and project-owned Checks. Even a preservation result names concrete owners and why no new or worsened debt is introduced. Put durable conclusions in owning Context and material falsifiable delivery conclusions in real marked Source plus existing Contract fields, then decide `Context Delta: none|required`. A material scope, owner, Context or design change before implementation stales and refreshes the deliberation.
|
|
60
|
-
10.
|
|
60
|
+
10. Close every real Control's 22 canonical fields through `field_coverage` and its Outcome's cross-Control meaning through `control_relation_closure`; use `specified`, explicit `not_applicable` or blocking `unresolved`, and give the closure exact applicability refs even when no Controls apply. Declare only actual applicability profiles, each with an atomic, duplicate-free dimension assignment plus exact target, journey, Given condition/input/state refs and ordered When refs. Every Claim lists all applicable profiles; every Claim-bearing Assertion proves one Claim in one matching profile and all required proof surfaces. Declare each execution target's runtime capabilities and require the production family, cold-start and production-root capabilities where applicable. Give every Assertion the minimum all-of Evidence Capabilities that can actually prove its Claim. Every behavioral Claim-bearing Assertion also needs a same-Check claim-local `replace_json_value` or `replace_text` wrong-semantic witness and a claimless target-runtime liveness Assertion that remains passing; whole-file replacement is compatibility-only and cannot prove semantic binding. Population declares a universe Binding whose carriers are Check inputs and proves exact universe = eligible = observed plus valid exclusions. Separate required success and degradation Checks. Type every external confirmation with impacted Claim refs and target-blocking effect. For selected design targets, keep resource-integrity Checks distinct from root-bound implementation conformance, freeze the validated handoff and target resources, preserve exact condition equality, map every covered handoff Source Item into separate attributable Assertions, bind each verification method to its own `design_method` evidence with distinct record and primary-observation paths plus a unique current primary digest for every condition, and declare current actual/comparison artifacts. Preserve every blocker's required target capabilities; use a machine Claim only on the exact capability-qualified target, otherwise keep a target-blocking External Confirmation. Playwright must attach both declared cell artifacts in every project instance. Use `context_snapshot_mode: full`. Run read-only `ty-context long-task preflight <workdir>`, repair every handoff, Contract and `decision_required` error in the same Draft, then formally Compile only when ready.
|
|
61
61
|
11. When the first Compile returns `execution_model_checkpoint.required: true`, obey its terminal-turn boundary. Unless an earlier user message explicitly states this task's current-model or switch-and-resume strategy, do no product implementation, file edit, build or test after that result; end the current turn and ask the user to choose `continue_current_model` or switch models and then resume the active Long-Task. Generic “continue”, “resume”, “finish” or “continue the Goal” language does not satisfy the checkpoint. Later revisions return `required: false` and do not repeat it.
|
|
62
62
|
|
|
63
63
|
Architecture quality uses the existing authority model, not a new gate or field. The visible deliberation proves that architecture work occurred, not that subjective quality is machine-proven. Encode every material falsifiable invariant as a Source-backed technical obligation/global constraint/forbidden shortcut plus owner/path/Binding boundaries and a project-owned executable Check. Functional acceptance cannot substitute when the architecture claim can fail independently. An unverifiable design preference remains task-local, durable Context or `decision_required`; it must not be promoted into false proof.
|
|
64
64
|
|
|
65
65
|
## Rolling Execution
|
|
66
66
|
|
|
67
|
-
After Authority Lock and the one-time execution-model checkpoint are satisfied,
|
|
67
|
+
After Authority Lock and the one-time execution-model checkpoint are satisfied, the current Goal chooses implementation order, local planning, tools, repair hypotheses and whether one or multiple platform-native agents/subagents are useful. It may work across Outcome or Stage boundaries when that is the most efficient implementation path. Multiple-agent execution is optional, never a Harness allocation rule: agent reports are non-authoritative and Harness stores no delegation state. The derived Frontier is only an acceptance/verification and diagnosis projection: work in a later Stage cannot make an unpassed earlier gate accepted, and no implementation choice may silently change Product, Technical or Acceptance authority. All proof-bearing changes converge into the selected verification workspace.
|
|
68
68
|
|
|
69
69
|
Re-evaluate `Context Delta` whenever implementation or repair discovers a durable fact. Controlling Context changes always use Authority Revision; they require a user decision only when mapped Claims, targets, proof obligations or another decision boundary changes. Graph-derived, non-explicit `implementation-index` and `archive` are Supporting Context in referenced mode and may auto-revise when only navigation/background changed. Full snapshot mode treats every selected Context file as controlling.
|
|
70
70
|
|
|
71
71
|
If rolling implementation materially changes scope, ownership, dependency direction, the selected design or a debt disposition, refresh the Architecture Deliberation and express any authority change through marked Source/Context plus protected revision before continuing. This is refinement of the same checkpoint, not a second workflow stage.
|
|
72
72
|
|
|
73
|
-
Use `verify --explain [--outcome/--check]` when execution cost is unclear; it previews declared main and Counterfactual runner invocations without executing or writing Progress. Use targeted `verify --outcome/--check`
|
|
73
|
+
Use `verify --explain [--outcome/--check]` when execution cost is unclear; it previews declared main and Counterfactual runner invocations without executing or writing Progress. Use targeted `verify --outcome/--check` for optional feedback and repair when its expected localization value exceeds its cost. Progress is repair evidence only and never acceptance authority. Keep precise findings attached to the owning Source item, Claim, Assertion, Check, Binding and owner path. Do not add another model-switch pause or turn delegation into a Harness scheduler, state or proof source.
|
|
74
74
|
|
|
75
|
-
When the Contract declares a target-runtime Check because a proxy can pass while the target fails independently,
|
|
75
|
+
When the Contract declares a target-runtime Check because a proxy can pass while the target fails independently, bind it to the earliest owning Outcome and exact target even if implementation happens in another order. Every required target is proved separately from its root; Browser evidence requires Playwright and Native/Desktop evidence requires the project binary. For material UI, a useful early feedback run inspects a runnable vertical slice through the production shell/navigation entry, not only a deep link or detached route. The first useful runnable boundary and later coalesced changes are recommended, not mandatory, targeted-feedback points. `progress_stale` is a freshness fact: refresh the Check only before an intermediate decision relies on that Progress. Continuing implementation or entering Final Gate needs no targeted refresh because Final Gate ignores Progress and reruns all Checks. Use the cheapest reliable target Check and do not mandate a full environment rebuild per Outcome or per edit. This is optional rolling feedback, not acceptance, an implementation gate, a trigger queue or per-target progress state.
|
|
76
76
|
|
|
77
77
|
When implementation discovers a blocker or missing Contract paths, first classify the revision. Difficulty or delay alone never reclassifies machine-verifiable scope as external and never removes Source; a real scope, Product, Acceptance or machine/external boundary change must first be explicit marked Source. Keep exact revision identity, old-Authority continuity, compare-and-swap adoption, evidence invalidation and the complete Final Gate for every path:
|
|
78
78
|
|
|
@@ -87,7 +87,7 @@ Candidate diagnostics are transient: they authorize no acceptance and write no p
|
|
|
87
87
|
|
|
88
88
|
Complete Context, implementation and project tests, create a clean candidate commit, then run `ty-context long-task final-gate <workdir>`.
|
|
89
89
|
|
|
90
|
-
Final Gate recompiles Source authority, validates active task/revision/compiled/worktree identity, creates one Git-tree snapshot
|
|
90
|
+
Final Gate recompiles Source authority, captures semantic and raw Contract protected-input identity, validates active task/revision/compiled/worktree identity, creates one Git-tree snapshot and reruns every required Global and Outcome Check. It then recompiles again and requires unchanged Contract/fragments, Source, Controlling Context, verifier, runner and verification/workdir inputs, plus unchanged workspace/tree and Active Authority, before acceptance. It derives Stage results and target qualification from that run; it does not trust targeted Progress as a Stage pass. A target-runtime Check must exercise its exact target in that current Gate execution; rerunning a reader for a historical or tracked status report is not live target proof. Design-resource integrity, an isolated route or `visual_render` cannot replace required root-bound `design_conformance`, and unresolved design blockers remain blocking. Final Gate, Stop and close never trust historical Progress, Receipt or compiled cache.
|
|
91
91
|
|
|
92
92
|
Final Gate is the Long-Task path's sole `Architecture Conformance` carrier. It reruns the declared architecture obligations/constraints/forbidden shortcuts, owner/path/Binding boundaries and project-owned Checks on that same snapshot and blocks scope escape, bypass, duplicate authority, a second source of truth, wrong dependency direction, undeclared boundary change or new/worsened debt represented by those invariants. Do not also run the default Workflow's standalone Contract Conformance closure. Any later candidate or authority change invalidates the Gate and uses the existing freshness path again.
|
|
93
93
|
|
|
@@ -97,4 +97,4 @@ Before invoking platform-native Goal completion, perform one veto-only conforman
|
|
|
97
97
|
|
|
98
98
|
## Handoff
|
|
99
99
|
|
|
100
|
-
Report implementation, effective risk, Architecture Deliberation/Conformance status, Claim Coverage, Stage frontier/results, declared target profile, exact `target_state`, Live Gate result, acceptance scope, every pending external confirmation, Context status and blockers. Use verifier terms exactly: `progress_passing` means targeted repair evidence, `progress_stale` is a freshness fact rather than a current pass or immediate rerun command, `final_workflow_status: null` means unfinished, `authority_revision_adopted` means return to rolling execution, and `machine_accepted_external_pending` must retain its named confirmations. Contract target states are only `implementation_complete`, `target_profile_usable` and `production_release_ready`; terminal failure uses `not_accepted` or `blocked_external`. Never shorten targeted progress to “Outcome complete” or invent per-platform progress/status. State the
|
|
100
|
+
Report implementation, effective risk, Architecture Deliberation/Conformance status, Claim Coverage, Stage frontier/results, declared target profile, exact `target_state`, Live Gate result, acceptance scope, every pending external confirmation, Context status and blockers. Use verifier terms exactly: `progress_passing` means targeted repair evidence, `progress_stale` is a freshness fact rather than a current pass or immediate rerun command, `final_workflow_status: null` means unfinished, `authority_revision_adopted` means return to rolling execution, and `machine_accepted_external_pending` must retain its named confirmations and never be summarized as `AcceptedDeliveryTerminal` or full no-drift delivery. Contract target states are only `implementation_complete`, `target_profile_usable` and `production_release_ready`; terminal failure uses `not_accepted` or `blocked_external`. Never shorten targeted progress to “Outcome complete” or invent per-platform progress/status. State the theorem boundary honestly: undeclared or inaccurate Source cannot be discovered mechanically; the named project oracle must be semantically sound; the supported direct-literal verifier dependency graph is frozen while other declared verification inputs, indirect runtime access, installed package/runtime behavior, Harness verifier and Git metadata form the trusted computing boundary; the visible checkpoint cannot prove private reasoning or universal future-proofing; native-Goal/model selection belongs to the host/user; and internal platform delegation is not observed.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
interface:
|
|
2
|
-
display_name: "Long-Task Workflow"
|
|
3
|
-
short_description: "Run one Delivery Contract in the current native Goal"
|
|
4
|
-
default_prompt: "Use /long-task-workflow to prepare, execute, resume, verify, or close one Canonical Delivery Contract in the current workspace."
|
|
1
|
+
interface:
|
|
2
|
+
display_name: "Long-Task Workflow"
|
|
3
|
+
short_description: "Run one Delivery Contract in the current native Goal"
|
|
4
|
+
default_prompt: "Use /long-task-workflow to prepare, execute, resume, verify, or close one Canonical Delivery Contract in the current workspace."
|
|
@@ -6,7 +6,7 @@ Read this before Preflight, Compile, revision, resume, targeted verify, Final Ga
|
|
|
6
6
|
|
|
7
7
|
Run `ty-context long-task preflight <workdir>` before first formal Compile. Resolve every `error` and `decision_required` diagnostic and review warnings. Preflight is read-only: it creates no Active Authority, initial base, marker, cache, Progress, Receipt or pending revision, runs no project Check and persists no success record.
|
|
8
8
|
|
|
9
|
-
Preflight and Compile call the same activation-safety validator. Skipping Preflight bypasses no Source continuity, criterion, Claim/all-of-surface, Stage closure/cross-surface gate, required-target/root/runner binding, scenario/journey separation, capability adequacy, typed external impact, bounded Product Conformance, adapter/Observation, risk, owner/path/Binding,
|
|
9
|
+
Preflight and Compile call the same activation-safety validator. Skipping Preflight bypasses no closed-grammar Source/background continuity, architecture Source obligation, Control field/relation closure, atomic applicability dimensions, criterion, Claim/all-of-surface, Population universe binding, Stage closure/cross-surface gate, required-target/root/capability/runner binding, scenario/journey separation, capability adequacy, typed external impact, per-method selected-design artifact binding, bounded Product Conformance, adapter/Observation, risk, owner/path/Binding, recursively frozen verifier dependencies, narrow semantic Counterfactual/liveness or sensitivity rule.
|
|
10
10
|
|
|
11
11
|
The same workspace classifier also runs before activation and during verification. Before first lock it classifies `HEAD`-relative current paths; later it classifies immutable-`initial_task_base` changes. Protected authority, declared expected change and allowed support remain distinct from forbidden or unclassified paths, which block activation. During first enable, protection covers only exact files present in the current package asset tree for configured managed destinations plus the exact harness config/hook files; managed directory roots and broad `.codex/**` are never implicitly allowed.
|
|
12
12
|
|
|
@@ -39,25 +39,27 @@ The previous Authority remains active until exact approval and compare-and-swap
|
|
|
39
39
|
|
|
40
40
|
Every path-bearing field uses canonical grammar. Internal `.`/`..`, control characters, empty segments, absolute/drive/UNC paths and unsupported glob syntax fail closed.
|
|
41
41
|
|
|
42
|
-
Controlling Context includes core Context, explicit `context_refs`, verification/deployment Context and every file
|
|
42
|
+
Controlling Context includes core Context, explicit `context_refs`, verification/deployment Context and every selected Context file. `context_snapshot_mode: full` is mandatory; legacy referenced-mode Contracts require semantic migration rather than silently retaining a partial authority snapshot.
|
|
43
43
|
|
|
44
44
|
A selected design target, its exact/constraint interpretation, an authored token source or any applicable Control semantic is product/verification authority, not generated evidence. External design resources are ordinary Context-reachable Source: a candidate or unresolved selection cannot authorize fidelity work, while a selected exact target still requires downstream UI Authority Closure, stable key, readable immutable identity/digest, declared coverage, editable upstream/update route and Contract adoption. Open every affected exact target/constraint during authoring and repair; a registry mention alone is not consumption. Adding or changing its selected resource, selection basis, immutable identity, condition coverage or acceptance-affecting token/prototype fixture after Authority Lock follows Authority Revision and returns to rolling implementation. Never silently overwrite an adopted baseline; a candidate/planned target, implementation screenshot or historical diff cannot authorize fidelity work or preserve affected Progress by itself.
|
|
45
45
|
|
|
46
46
|
`context.toml` retrieval guidance (`triggers`, `read_when`, `read_policy`, default selection and unselected nodes) is excluded from the selected delivery-authority projection. Selected area ownership, role/dependency structure and selected Context contents remain protected revision material. Retrieval-only edits may preserve scoped Progress, but a changed final Git tree still invalidates historical final acceptance and must pass the Live Final Gate again.
|
|
47
47
|
|
|
48
|
-
## Targeted Verification And Recovery
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
## Targeted Verification And Recovery
|
|
49
|
+
|
|
50
|
+
Implementation remains Goal-owned throughout rolling execution. The Goal may use one agent or multiple platform-native agents/subagents when their expected benefit exceeds coordination cost, but Harness allocates and records none of them. Delegated reports are not Progress or proof, and every proof-bearing result must converge into the selected verification workspace. Stage/Outcome readiness, `progress_stale` and targeted feedback never become agent allocation, edit permission, a method Gate or a scheduler.
|
|
51
|
+
|
|
52
|
+
`verify --explain [--outcome/--check]` is a read-only execution preview. It groups declared Main Raw Executions, lists applicable Counterfactual runner invocations and bounded declared retry-attempt counts, but runs no command, writes no Progress, predicts no duration/internal subprocess count and creates no proof.
|
|
51
53
|
|
|
52
54
|
Before an expensive first targeted run, use the preview to review selected Check count, deduplicated Main executions, Counterfactual mutations and retry bounds. If the expanded plan reveals an obsolete carrier, unnecessarily broad invalidation surface or repeated expensive runner, repair the same Contract Draft/Authority through the normal revision path. The preview cannot see build systems or subprocesses hidden inside a project runner.
|
|
53
55
|
|
|
54
56
|
`verify --outcome/--check` runs scoped current-snapshot checks for repair and rechecks active identity before writing Progress. A Counterfactual finding is projected into the owning Main Check, changes an otherwise passed Check to `invalid_evidence`, clears Claim proofs and remains recoverable through `status`/`resume`. Global Checks use the same record without a new Global Outcome state.
|
|
55
57
|
|
|
56
|
-
For a declared target-runtime Check,
|
|
58
|
+
For a declared target-runtime Check, the earliest useful runnable boundary and later coalesced relevant changes are recommended targeted-feedback points only when their expected localization value exceeds cost. The owning Outcome binds proof; it does not gate implementation order. `progress_stale` is a fact about evidence freshness, not an immediate execution instruction. Refresh the declared Check only before an intermediate decision relies on its Progress. Continuing implementation and entering Final Gate require no targeted refresh because Final Gate ignores Progress and reruns all Checks. Do not create a per-edit/per-Outcome rebuild rule, implementation gate, trigger queue or platform state. These runs remain `acceptance_authorized: false`.
|
|
57
59
|
|
|
58
60
|
Do not add a second executing `diagnose-check` mode merely to avoid Progress: it would still pay the project runner's cost and create a competing execution path. Use project-owned fast feedback while editing, the read-only preview for declared cost shape, targeted verify at a useful stability boundary and the complete Final Gate for acceptance.
|
|
59
61
|
|
|
60
|
-
Progress freshness binds Outcome authority, runner, verification inputs, Controlling Context and implementation inputs. Retry defaults to none; one retry is allowed only for explicit `transient_once`, idempotent, read-only/test-sandbox work.
|
|
62
|
+
Progress freshness binds Outcome authority, applicability, runner, verification inputs, Controlling Context and implementation inputs. Retry defaults to none; one retry is allowed only for explicit `transient_once`, idempotent, read-only/test-sandbox work.
|
|
61
63
|
|
|
62
64
|
Status, Progress, Receipts and workdir compiled output are audit/recovery projections only. Development-period authority state is `manual_required` and never migrated.
|
|
63
65
|
|
|
@@ -65,7 +67,7 @@ Report their exact meaning: `progress_passing` is current targeted repair eviden
|
|
|
65
67
|
|
|
66
68
|
## Final Gate And Terminal Paths
|
|
67
69
|
|
|
68
|
-
Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate
|
|
70
|
+
Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate first verifies the accepted compiled authority is still fresh, then recompiles Source authority and records semantic plus raw protected-input identity for the Contract and fragments, every Source file, full Controlling Context, verifier/runner, recursively frozen local verifier dependencies, `verification_inputs` and workdir inputs. It validates the common-dir record/marker, creates one Git-tree snapshot and reruns every Check and sensitivity control. After execution it recompiles and re-hashes the same full protected set; any change returns `protected_inputs_changed_during_final_gate`, while an Active Authority race returns `active_authority_changed_during_final_gate`. Only unchanged protected inputs, workspace/tree and Authority may be accepted. This is the sole Long-Task `Architecture Conformance` carrier: material deliberation conclusions must already be declared through existing obligations/constraints/forbidden shortcuts, owners/paths/Bindings and project-owned Checks, and no separate default Contract Conformance closure runs. A target-runtime Check must exercise its exact target again in that Final Gate execution; rereading historical status does not become live proof merely because the reader reran. The Receipt reports the target profile/state and every Stage as `passed`, `failed`, `blocked_external` or `blocked_dependency`.
|
|
69
71
|
|
|
70
72
|
Commit, verifier migration, clear and abandon share one active-state lock. Stop/close clear only the identity actually accepted through CAS and preserve `machine_accepted_external_pending` plus every named external confirmation in output. Final Gate/Stop/close identify `acceptance_scope: declared_machine_authority` and `native_goal_effect: none`; close additionally identifies `closed_scope: machine_authority`. The Stop Hook emits the same scope as one non-blocking message for either accepted machine status. A stale Receipt exposes no accepted workflow status.
|
|
71
73
|
|
|
@@ -73,4 +75,4 @@ Before platform-native Goal completion, compare current Goal/user meaning with a
|
|
|
73
75
|
|
|
74
76
|
For invalid, mismatched, unrecoverable or stale-lock continuity, use only `ty-context long-task abandon <workdir> --force-corrupt-state`; it preserves authored Contract, Source, Context and Git content.
|
|
75
77
|
|
|
76
|
-
An older `long-task-delivery-v2` Contract that lacks Stage, required-target, scenario, journey, success/degradation,
|
|
78
|
+
An older `long-task-delivery-v2` Contract that lacks Stage, required-target capabilities, full Context mode, atomic applicability dimensions, scenario, journey, success/degradation, Population universe binding, Control-relation applicability, per-method design record/primary-observation artifacts, blocker-required capabilities, narrow semantic witnesses or typed external-impact fields is a manual migration. `upgrade --check` reports `long-task-v2-semantic-drift-authority`, and parsing lists missing field paths. Re-author those meanings from Source; never infer them from old Progress/Receipts or import historical passing evidence as acceptance. Reclassify every Check path explicitly: implementation/runtime material belongs in `input_paths`, `expected_output_paths` or `artifact_globs`; Oracle/config/data inputs belong in `verification_inputs`. Supported direct-literal local Oracle dependencies are frozen recursively, while non-literal loaders fail closed and indirect runtime access remains declared Oracle TCB.
|
|
@@ -4,11 +4,12 @@ Read this only while authoring or structurally revising the one `delivery-contra
|
|
|
4
4
|
|
|
5
5
|
## Source And Semantic Boundary
|
|
6
6
|
|
|
7
|
-
- Every declared Source file contains at least one Material Source Item. Mark items in original Markdown without rendering or changing meaning.
|
|
7
|
+
- Every declared Source file contains at least one Material Source Item. Mark items in original Markdown without rendering or changing meaning. Every other non-empty line belongs to the one schema-valid `design-resource-handoff-v1` formal block or a closed-grammar background block: `markdown-structure` permits only text-free anchors/horizontal rules and `provenance` permits only `ty-source-provenance` comments with fixed `input`, `mode`, conditional `source` and optional `sha256` fields. A text-bearing heading or free-form provenance field may carry authority and cannot be background. Arbitrary background prose and every other unclassified line fail closed.
|
|
8
8
|
- Marker keys and `source_claim` keys are set-equal and globally unique. `statement` preserves marked text after line-ending normalization, surrounding blank-line removal and trailing-space cleanup.
|
|
9
9
|
- Typed dispositions keep Result, Requirement, Control, Technical Obligation, Non-completing Claim, Acceptance, Global Constraint/Non-goal, Forbidden Shortcut, Risk, External Confirmation and Decision distinct.
|
|
10
10
|
- Every non-decision Source item owns exactly one same-kind, text-identical canonical target; no target may collapse multiple Source items. `out_of_scope` is not a resolution.
|
|
11
|
-
- A Source AC maps criterion-identically to one named Assertion and proves at least one independently Source-backed non-Result Claim.
|
|
11
|
+
- A Source AC maps criterion-identically to one named Assertion and proves at least one independently Source-backed non-Result Claim.
|
|
12
|
+
- At least one `technical_obligation` Source Item has `aspect=architecture`, maps text-identically to a named architecture obligation and is independently provable; a generic Result or unmarked architecture review cannot substitute.
|
|
12
13
|
- Missing recommended legacy Source Plan headings or keys never blocks authoring. Raw/mixed inputs enter this Contract Draft immediately; apply `source-authoring.md` alongside mapping until real Source, provenance and markers converge. Missing mandatory Material Source Item markers still blocks Preflight/Compile.
|
|
13
14
|
- A revised initial proposal and selected design resources are parallel Source inputs. Preserve their stable resource/surface/control/state/target keys, declared conditions, provider/project/run/entry provenance and immutable digest/snapshot; do not flatten visual meaning into an untraceable prose summary.
|
|
14
15
|
- `delegated` in a Source Plan is provenance, not a Contract disposition or new Claim kind. An instruction to synthesize, refine, complete, implement or use judgment delegates plan-level authoring, but it does not invent material tradeoff preferences. Before comparative research or a material product, technical, architecture or provider selection, identify the criteria that could change the research scope, candidate set or recommendation. If such a preference is unknown or ambiguous, ask a concise targeted question before research or selection and keep the item `decision_required` until answered; do not impose a fixed questionnaire or re-ask preferences already supplied by the user, Source, Context or controlling constraints.
|
|
@@ -18,7 +19,7 @@ Read this only while authoring or structurally revising the one `delivery-contra
|
|
|
18
19
|
|
|
19
20
|
## Outcome Boundary
|
|
20
21
|
|
|
21
|
-
Create an Outcome only when its result is independently observable, decidable, target-verifiable, dependency-expressible and localizable to its own Claims, Assertions, Checks and owner boundary. Requirement coupling,
|
|
22
|
+
Create an Outcome only when its result is independently observable, decidable, target-verifiable, dependency-expressible and localizable to its own Claims, Assertions, Checks and owner boundary. Requirement coupling, acceptance/verification-ready projection, targeted verification, precise failure localization, semantic resume and stale-result invalidation are valid reasons to decompose. Outcome boundaries never restrict implementation order. File count, implementation layer, context length, desired parallelism and Agent capacity are not.
|
|
22
23
|
|
|
23
24
|
For every Outcome declare:
|
|
24
25
|
|
|
@@ -32,6 +33,8 @@ For every Outcome declare:
|
|
|
32
33
|
|
|
33
34
|
Global non-goals, constraints and forbidden shortcuts remain Global authority and use Global Checks/Assertions when machine proof is required.
|
|
34
35
|
|
|
36
|
+
Declare only real applicability, not a blind Cartesian product. Each global or Outcome profile names one exact execution target, journey role, a non-empty duplicate-free set of atomic dimension assignments, keyed Given condition/input/state facts and ordered When actions. One profile cannot bundle phone/tablet, light/dark, default/loading or other multiple values of the same dimension. Every Claim-bearing fact lists all and only its applicable profile refs. Every Claim-bearing Assertion proves exactly one Claim in exactly one matching profile, and every required proof surface of every actual applicable cell has an attributable Assertion. Two cells may share one Check execution only when their individual Assertion failures remain distinguishable; risk-based, pairwise, representative or sampled coverage never substitutes for a declared applicable cell.
|
|
37
|
+
|
|
35
38
|
## Feedback-cost boundary
|
|
36
39
|
|
|
37
40
|
Declare each Check's `input_paths` and Binding carriers as the smallest sound causal envelope for that Check. Do not use a repository, application or platform root merely because it is convenient: a broad pattern is justified only when any matching change can actually invalidate the declared result. If independent capabilities have different invalidation surfaces or useful feedback boundaries, assign them to the owning Outcomes/Checks rather than making every early Stage gate stale.
|
|
@@ -45,7 +48,7 @@ Declare cheap machine-checkable prerequisites through existing environment requi
|
|
|
45
48
|
- Declare one ordered `stages` DAG in the same Contract. Every Outcome belongs to exactly one Stage; every Stage names one gate Outcome; the gate transitively depends on every other Outcome in that Stage; and every later Stage Outcome transitively depends on every prerequisite gate.
|
|
46
49
|
- A Stage Gate is not a second Final Gate or Receipt. It is one or more `stage_gate` Checks owned by the gate Outcome, and its status/frontier is derived from ordinary Outcome Progress.
|
|
47
50
|
- A multi-Outcome Stage Gate declares `cross_surface_consistency`. Its runtime record names at least two distinct `surface_ref` values, may use the same runtime target for several pages, and proves one matching state version.
|
|
48
|
-
- `task.target_profile` declares `required_state` plus a non-empty, duplicate-free `required_target_refs`. Each ref resolves to a `product` execution target with one bounded runtime family and
|
|
51
|
+
- `task.target_profile` declares `required_state` plus a non-empty, duplicate-free `required_target_refs`. Each ref resolves to a `product` execution target with one bounded runtime family, root entrypoint and explicit capabilities. A required product target declares its family capability plus `cold-start` and `production-root`; every Stage Gate and every `critical_user_path` Outcome provides root `target_runtime` proof for every required ref. Optional support/observer targets never substitute.
|
|
49
52
|
- Use `implementation_complete` only when code-level implementation is the selected target, `target_profile_usable` when the declared required targets must be usable, and `production_release_ready` only when release gates are part of the selected target. These are terminal target qualifications, not Outcome progress states.
|
|
50
53
|
|
|
51
54
|
## Architecture Deliberation And Closure
|
|
@@ -66,14 +69,14 @@ Do not encode subjective “clean architecture” or generic quality prose as ma
|
|
|
66
69
|
|
|
67
70
|
## Proxy And Target Runtime Independence
|
|
68
71
|
|
|
69
|
-
When a declared result can pass on a proxy surface while failing in its target runtime, author independent target-runtime proof for the exact required target ref. Put the project-owned live Check in the earliest Outcome that owns the first runnable target boundary rather than postponing it to a terminal release/quality Outcome.
|
|
72
|
+
When a declared result can pass on a proxy surface while failing in its target runtime, author independent target-runtime proof for the exact required target ref. Put the project-owned live Check in the earliest Outcome that owns the first runnable target boundary rather than postponing it to a terminal release/quality Outcome; this assigns proof ownership and does not dictate implementation order.
|
|
70
73
|
|
|
71
74
|
Use existing Contract semantics:
|
|
72
75
|
|
|
73
76
|
1. require `runtime_behavior` or the other proof surface that matches the actual Claim;
|
|
74
77
|
2. make the accepting runner exercise the target during the current Raw Execution and derive its asserted Observation from that same session;
|
|
75
78
|
3. include the runtime-affecting entrypoints, dependency manifests/lockfiles, configuration and integration carriers in `input_paths` or Bindings as appropriate;
|
|
76
|
-
4. freeze runner helpers/configuration as `verification_inputs
|
|
79
|
+
4. freeze runner helpers/configuration as `verification_inputs`; recursively freeze every statically resolvable local JS/TS import/re-export/require and JSON dependency, reject unresolved dynamic loaders, and permit a package-script runner only when its static Node entry closure is recoverable; and
|
|
77
80
|
5. add capability-specific probes only for Claims that actually require them.
|
|
78
81
|
|
|
79
82
|
A proxy check, static repository shape, tracked status report, prior screenshot, binary or historical run cannot be the sole proof of a Claim that can fail independently in the target. Use only the bounded execution-target runtime families and required refs in the Contract; do not add open-ended `platform_impact` flags or per-platform Progress state.
|
|
@@ -88,29 +91,30 @@ A proxy check, static repository shape, tracked status report, prior screenshot,
|
|
|
88
91
|
|
|
89
92
|
When the selected delivery includes a new/redesigned screen, primary layout/navigation/theme/component system, high-fidelity implementation or other material production UI, resolve Design Authority before Compile and author the result through existing Contract semantics:
|
|
90
93
|
|
|
91
|
-
- when selected external resources are an implementation handoff, place one strict marked `design-resource-handoff-v1` Markdown file in `task.source_paths` and run `ty-context design-resource preflight <handoff.md>` before Contract Preflight. The handoff must close every applicable subject × target × condition cell across all eight UI/UX dimensions, resolve typed locators against immutable resources and bind covered cells to Source Items and verification methods. Web/App profiles require a canonical entry, exact declared dependency closure and complete acquisition; unresolved/stale/unsupported/partial input blocks. Treat candidates and unresolved decisions honestly; only a selected exact target with a valid selection basis, declared condition coverage and immutable identity can be proposed for fidelity authority, and downstream UI Authority Closure still owns adoption;
|
|
94
|
+
- when selected external resources are an implementation handoff, place one strict marked `design-resource-handoff-v1` Markdown file in `task.source_paths` and run `ty-context design-resource preflight <handoff.md>` before Contract Preflight. The handoff must close every applicable subject × target × condition cell across all eight UI/UX dimensions, resolve typed locators against immutable resources and bind covered cells to Source Items and verification methods. Web/App profiles require a canonical entry, exact declared dependency closure and complete acquisition; unresolved/stale/unsupported/partial input blocks. Treat candidates and unresolved decisions honestly; only a selected exact target with a valid selection basis, declared condition coverage and immutable identity can be proposed for fidelity authority, and downstream UI Authority Closure still owns adoption;
|
|
92
95
|
- perform UI Authority Closure over stable surface/control/target keys: classify each material item as covered by owning Context/`DESIGN.md`, requiring an owner update, task-local Source, explicitly out of scope or genuinely `decision_required`. Product Surface Context owns cross-surface responsibility, Screen/interaction Context owns durable hierarchy/behavior, `DESIGN.md` owns visual-system/reference semantics and selected targets own concrete composition; Contract YAML must not duplicate or invent those owners;
|
|
93
96
|
- inspect owning surface/interaction Context, `DESIGN.md`, its authored token source/generation direction and material design references. Classify every reference as `exact-target`, `constraint` or `inspiration`, with its surface/route/component, path/URI and covered viewport/theme/mode/state;
|
|
94
97
|
- an unconfigured starter, style-only prose, inspiration-only set or conflicting target is not sufficient production authority. Resolve it by explicitly scoping Source to a prototype/non-fidelity result, recording an explicitly delegated and selected design target in real Source after material preferences are known, or keeping the unresolved/user-reserved direction `decision_required`;
|
|
95
98
|
- never let implementation output authorize itself: a generated implementation screenshot/diff is an Artifact, not the target. An acceptance-affecting target or baseline must be selected Source/verifier input before fidelity implementation can be accepted;
|
|
96
|
-
- derive
|
|
97
|
-
-
|
|
99
|
+
- derive the exact task-local Visual Coverage Set from declared Source, `project_context/**` and `DESIGN.md`: production surface/route/component, viewport, theme or product mode, interaction/state, content stress and accessibility/motion conditions. Do not invent an irrelevant Cartesian product, but cover every combination that is actually applicable;
|
|
100
|
+
- never use risk-based, pairwise, representative or sampled combinations to waive an applicable cell. Equivalent execution may be shared only when each fact/method retains an independently attributable Assertion and any omitted applicable combination remains blocking;
|
|
98
101
|
- encode each independently falsifiable visual expectation as an atomic Requirement, applicable Control field or named AC Assertion. Name the surface, viewport, theme/state/content condition and observable result when they matter to the claim;
|
|
99
|
-
-
|
|
102
|
+
- close every real Control's canonical fields independently through `field_coverage`: `surface`, `region`, `location`, `control_type`, `label_content`, `user_task`, `visibility`, `availability`, `trigger`, `input`, `validation`, `default_value`, `interaction`, `navigation_result`, `loading_state`, `empty_state`, `success_state`, `failure_state`, `recovery`, `permission`, `feedback` and `accessibility`. `specified` names concrete meaning, `not_applicable` carries a falsifiable reason, and `unresolved` blocks Compile; specified and not-applicable entries create Claims for every declared applicability profile, so omission can never silently mean non-applicable;
|
|
103
|
+
- close each Outcome's cross-Control/system meaning through `control_relation_closure` plus `control_relations`: shared state, dependency/order, mutual exclusion, navigation, permission, recovery, validation and feedback chains are explicit relations with Control refs, proof surfaces and applicability, while `state: not_applicable` is a negative Claim with exact applicability and an explicit assertion that no such relation applies; `unresolved` blocks;
|
|
100
104
|
- when an Outcome declares Controls, add the minimum aggregated Product `surface_bindings`: one stable binding per owner surface and required product target, its Control refs, existing Technical route/component Binding refs, one root-entry success Check and its real entry action. Every Control must be bound, every Control Claim must have target-local proof on the runtime-appropriate surface, and the root journey must prove each Control's declared `navigation_result` or its `interaction`/`trigger`/`location` fallback with all-of `interaction_trace` and `target_runtime`;
|
|
101
105
|
- bind the declared result to the owning Context/`DESIGN.md`, one authored token source and generation direction, selected target/constraint inputs, production component/route carriers, path envelopes and project-owned target checks. Freeze acceptance-affecting selected target files, token sources and fixed prototype fixtures in `verification_inputs`; bind production carriers through `input_paths`/Bindings and reserve `artifact_globs` for generated implementation renders, diffs and reports. Detached kits, deep links, mocks or marketing specimens may be references or supplemental checks but not substitute implementation carriers or the production root journey;
|
|
102
|
-
- for each selected exact/constraint target inside a surface binding, use the exact handoff target key and interpretation; declare `source_paths` as exactly the handoff plus that target's immutable resource paths and `condition_keys` as exactly its handoff condition refs. Put the same files in Check `verification_inputs`; map every covered handoff Source Item through `source_claims` to Claims
|
|
103
|
-
- explicitly inventory every declared design-acceptance blocker inside its surface binding. An empty array states that no blocker is declared; each declared entry
|
|
106
|
+
- for each selected exact/constraint target inside a surface binding, use the exact handoff target key and interpretation; declare `source_paths` as exactly the handoff plus that target's immutable resource paths and `condition_keys` as exactly its handoff condition refs. Put the same files in Check `verification_inputs`; map every covered handoff Source Item through `source_claims` to method-specific Source Claims and separate single-Claim Assertions at the target's exact applicability; and bind every handoff acceptance blocker in the surface binding. Every handoff verification method binds its own Assertion and an exact set of per-condition `evidence_artifacts`; each cell declares both `path` for its method record and `observation_path` for its primary method-native observation. Both paths are covered by the Check, primary-observation paths and current digests are pairwise distinct across methods/conditions, and typed current-execution `design_method` evidence names both. A Playwright Assertion must attach `ty-context-design-method:<target>:<method>:<condition>:record` and `...:observation` in every project instance before the adapter emits that evidence. The target-local Assertions also cover bound Control Claims, distinct current actual/comparison artifact paths and all-of `design_conformance`, `interaction_trace` and `target_runtime` where applicable. `visual_render`, handoff preflight, file hashes, counts or registry presence remain input/resource integrity and cannot substitute for implementation conformance;
|
|
107
|
+
- explicitly inventory every declared design-acceptance blocker inside its surface binding. An empty array states that no blocker is declared; each declared entry preserves exactly the handoff's `source_item_refs`, `verification_methods` and non-empty `required_capabilities`. A `machine_claim` is valid only when the exact bound execution target declares every required capability and the referenced Claims have target-local proof; otherwise use a target-blocking External Confirmation whose impact includes the Outcome. There is no in-band not-applicable waiver: removing a blocker from scope first requires explicit revised Source and, after Authority Lock, protected Contract revision. Empty refs block Compile/Final Gate;
|
|
104
108
|
- use `ui_browser` only for declared browser ACs. A browser or Expo-Web proxy cannot prove a native/mobile/desktop target that can fail independently; use a project-owned current-execution target Check when existing proof surfaces can truthfully represent the claim, otherwise retain named human/device confirmation as an external confirmation rather than inventing machine proof;
|
|
105
109
|
- keep subjective visual direction, taste or approval outside false machine proof. Resolve an undecided direction as `decision_required`; represent required human design or new-baseline approval as an explicit external confirmation.
|
|
106
110
|
- for combined design-and-implementation delivery, ordinary design Outcomes/Stages may author candidates before selection, but candidate/planned artifacts cannot authorize fidelity Claims. Append the selected result to real marked Context-reachable Source and its owning Context/`DESIGN.md` reference; after Authority Lock adopt it through Authority Revision before downstream fidelity implementation. This creates no target-selection state, second Contract or second Gate.
|
|
107
111
|
|
|
108
|
-
External design resources authorize fidelity only when they become a selected exact target with a validated handoff; they remain ordinary upstream Source rather than a Contract Draft, verification result or alternate authority. The revised initial proposal plus selected immutable canonical resources and the residual `design-resource-handoff-v1` is the recommended implementation input; no standalone Source Plan handoff is required. Map each covered Source Item into the root conformance Assertion and each declared verification method to its own independently failing Assertion; carry blocker Source Items and methods unchanged into a target-local machine Claim or target-blocking External Confirmation. A legacy Source Plan remains valid ordinary Source if supplied. The single Product `surface_bindings` projection is an aggregated cross-reference over existing Source, Controls, Technical Bindings, targets, Checks, Assertions, verification inputs and External Confirmations; it creates no `uiux_delivery` authority block, Claim kind, risk level, lifecycle state, required design directory, per-Control screenshot matrix or Gate.
|
|
112
|
+
External design resources authorize fidelity only when they become a selected exact target with a validated handoff; they remain ordinary upstream Source rather than a Contract Draft, verification result or alternate authority. The revised initial proposal plus selected immutable canonical resources and the residual `design-resource-handoff-v1` is the recommended implementation input; no standalone Source Plan handoff is required. Map each covered Source Item into the root conformance Assertion and each declared verification method to its own independently failing Assertion; carry blocker Source Items and methods unchanged into a target-local machine Claim or target-blocking External Confirmation. A legacy Source Plan remains valid ordinary Source if supplied. The single Product `surface_bindings` projection is an aggregated cross-reference over existing Source, Controls, Technical Bindings, targets, Checks, Assertions, verification inputs and External Confirmations; it creates no `uiux_delivery` authority block, Claim kind, risk level, lifecycle state, required design directory, per-Control screenshot matrix or Gate.
|
|
109
113
|
|
|
110
114
|
## Compact Authoring
|
|
111
115
|
|
|
112
|
-
Compact V2 may omit only deterministic defaults: empty optional arrays/nulls, `
|
|
116
|
+
Compact V2 may omit only deterministic defaults: empty optional arrays/nulls, `requested_level: auto`, runner `argv: []`, `cwd: .`, `timeout_ms: 30000`, `retry_policy: none`, `idempotent: false`, and empty output/artifact/assertion/environment lists. `context_snapshot_mode: full` remains explicit and is the only accepted authority mode.
|
|
113
117
|
|
|
114
|
-
Goal, target profile/required targets, ordered Stages, Source/Source Claims, Context, observable results, success/degradation requirements, owners/paths, REQ,
|
|
118
|
+
Goal, target profile/required targets, ordered Stages, Source/Source Claims and non-authoritative background ownership, Context, observable results, exact applicability profiles, success/degradation requirements, owners/paths, REQ, all-field CTRL closure, Control relations and production `surface_bindings`, selected target conditions/conformance artifacts, design-blocker dispositions, OBL, proof surfaces, Given/When scenarios, journey roles, Evidence Capabilities, runner targets/effects, verification inputs, single-Claim Assertions, behavioral semantic witnesses and liveness Assertions, risk, forbidden shortcuts and typed external confirmations remain explicit.
|
|
115
119
|
|
|
116
120
|
Compiler-generated Outcome/Check/Claim identities replace handwritten mechanical cross-entity references. This does not authorize compiler inference of product meaning, owners, architecture, proof or risk.
|
|
@@ -5,25 +5,25 @@ Read this only while designing or repairing Contract Checks and proof.
|
|
|
5
5
|
## General Proof Rules
|
|
6
6
|
|
|
7
7
|
- Every Outcome has at least one executable Check and one non-Result atomic Claim.
|
|
8
|
-
- Required proof surfaces are non-empty, unique and all-of. Claim-bearing
|
|
8
|
+
- Required proof surfaces are non-empty, unique and all-of. Every Claim-bearing Assertion proves exactly one Claim at one exact applicability profile and uses explicit comparable Observations and expected values; every Claim/applicability/proof-surface cell must be covered.
|
|
9
9
|
- `truthy`/`falsy` are diagnostic-only. `exists` proves only implementation-structure obligations. Missing or type-incomparable Observation never proves a Claim; negative proof uses an explicit value such as `equals: false`.
|
|
10
10
|
- Claim and Population proof is emitted only after the entire Check passes. Exit failure, missing artifact, failed population, failed Assertion or invalid Counterfactual yields no Claim proof.
|
|
11
|
-
- Verification inputs include entrypoints, helpers, fixtures/config, package scripts and lockfiles and cannot overlap implementation carriers.
|
|
11
|
+
- Verification inputs include entrypoints, helpers, fixtures/config, package scripts and lockfiles and cannot overlap implementation carriers. The frozen runner identity recursively includes the supported direct-literal local verifier module/config/data graph; runtime-owned Check inputs/outputs/artifacts are explicitly excluded from Oracle identity, while non-literal loaders, `createRequire` and package scripts without a recoverable static Node entry fail closed. Other indirect Oracle access must be declared or treated as named TCB.
|
|
12
12
|
- Runners receive the minimum environment whitelist plus only declared environment requirements. Never expose actual secret values in findings.
|
|
13
13
|
|
|
14
14
|
## Runner And Observation Identity
|
|
15
15
|
|
|
16
|
-
Evidence adapter is derived from runner kind. Only Playwright may prove `ui_browser`; structured runners prove non-browser surfaces. Raw Execution identity binds
|
|
16
|
+
Evidence adapter is derived from runner kind. Only Playwright may prove `ui_browser`; structured runners prove non-browser surfaces. Raw Execution identity binds the runner, its recursively frozen local dependency closure and canonical declared Environment Requirements, not actual values. Bare installed packages and the Harness/runtime remain named trusted-computing-boundary components rather than silently mutable project helpers.
|
|
17
17
|
|
|
18
18
|
Across all Checks sharing a Raw Execution, one Claim-bearing Observation belongs to one Assertion. Shared setup may execute once only when independent per-Check observations and artifacts remain unambiguous.
|
|
19
19
|
|
|
20
20
|
## Scenario And Evidence Capabilities
|
|
21
21
|
|
|
22
|
-
- Every Check declares non-empty keyed `scenario.given` and `scenario.when` steps. One Check covers one materially coherent journey; a different success path belongs in another Check or vertical Outcome.
|
|
22
|
+
- Every Check declares non-empty keyed `scenario.given` and `scenario.when` steps. One Check covers one materially coherent journey; a different success path belongs in another Check or vertical Outcome. A Claim-bearing Assertion's `applicability_ref` must match the Check target, journey role, duplicate-free atomic dimension assignments, all keyed Given refs and ordered When refs exactly.
|
|
23
23
|
- Every Assertion declares a non-empty all-of `evidence_capabilities` set. `presence` proves static existence only and cannot alone prove a behavioral Claim. Each other capability requires exactly one typed current-execution record bound to the declared Assertion key; missing, duplicate, unknown or undeclared records fail closed.
|
|
24
24
|
- `interaction_trace` names the exact target plus the declared Given keys and ordered action keys. Playwright derives it only from an executed declared AC carrying matching `[given:<key>]` and `[action:<key>]` steps; `[ac:<assertion-key>]` remains the AC binding.
|
|
25
25
|
- `state_delta` requires different before/after hashes and named changed fields. `durable_readback` requires independent write/read sessions with equal state hashes. `cross_surface_consistency` requires at least two distinct surface refs, known target refs and one state hash.
|
|
26
|
-
- `boundary_invocation` and `external_side_effect` require the Check itself to execute on the named observer target. `failure_injection` requires an observed fault and recovery state; `visual_render` binds a declared artifact hash; `design_conformance` binds one compiled selected target, exact required product target, declared condition set and distinct current actual/comparison artifact paths; `target_runtime` binds exact target/root/current session and requires a cold start for a root journey; `input_variation` requires at least two distinct inputs, differing propagated outputs and an observed failure case.
|
|
26
|
+
- `boundary_invocation` and `external_side_effect` require the Check itself to execute on the named observer target. `failure_injection` requires an observed fault and recovery state; `visual_render` binds a declared artifact hash; `design_conformance` binds one compiled selected target, exact required product target, declared condition set and distinct current actual/comparison artifact paths; `design_method` binds one handoff verification method, its exact condition, declared method-record path and declared primary-observation path. Primary observations are pairwise unique by current path and digest across method/condition cells; `target_runtime` binds exact target/root/current session and requires a cold start for a root journey whose execution target declares the matching family, `cold-start` and `production-root` capabilities; `input_variation` requires at least two distinct inputs, differing propagated outputs and an observed failure case.
|
|
27
27
|
- Structured runners emit `long-task-check-result-v3` for capability records. V2 payloads remain decodable only for presence-only compatibility; they cannot satisfy a declared non-presence capability. Evidence records contain bounded hashes/ids/refs, not unrestricted raw payloads.
|
|
28
28
|
|
|
29
29
|
## Live Target Runtime Evidence
|
|
@@ -38,8 +38,8 @@ Across all Checks sharing a Raw Execution, one Claim-bearing Observation belongs
|
|
|
38
38
|
|
|
39
39
|
- When a rolling blocker causes a semantic or proof revision, review only the affected weak-observability or high-risk Outcomes before adoption. Ask whether a cheaper proxy, fixed response or self-reported success could pass while the declared result still fails at a farther independent boundary.
|
|
40
40
|
- Evidence must reach the furthest independently failing boundary named by the Claim. A proxy may prove its own result, but it cannot prove a downstream state or effect merely by reporting success.
|
|
41
|
-
-
|
|
42
|
-
- Keep this risk-proportional and internal. Do not create an evidence matrix, product-effect taxonomy, universal restart/end-to-end suite
|
|
41
|
+
- Every behavioral Claim-bearing Assertion requires a same-Check claim-local semantic Counterfactual. Use `replace_json_value` or `replace_text` to alter only the asserted semantic field/fragment while preserving the production carrier; the designated Assertion must fail and a claimless target-runtime liveness Assertion in `preserved_assertions` must keep passing. `replace_file` remains compatibility-only and cannot establish semantic binding; `remove_paths` remains for non-behavioral existence/structure claims.
|
|
42
|
+
- Keep this risk-proportional and internal. Do not create an evidence matrix, product-effect taxonomy, universal restart/end-to-end suite or persistent review state.
|
|
43
43
|
|
|
44
44
|
For semantic Product Conformance, require one separate read-only Global `conformance` Check only when `weak_observability` combines with multiple Stages or multiple required product runtime families. It starts from a required root product target, includes `target_runtime`, uses a Raw Execution identity independent of Outcome Checks and runs inside the existing Final Gate. Single-Stage/single-family weak work keeps the existing same-Check sensitivity path and does not pay this extra runtime cost.
|
|
45
45
|
|
|
@@ -53,26 +53,27 @@ Standard frozen Playwright verifier content is trusted. Weak-observability Outco
|
|
|
53
53
|
|
|
54
54
|
## Visual UI Evidence
|
|
55
55
|
|
|
56
|
-
- A selected implementation handoff must already pass `ty-context design-resource preflight`. For each covered row, turn its declared verification methods into project-owned, independently failing observations in the target conformance Check: geometry/pixel/token/content, component state/interaction trace, motion timeline, responsive reflow/input method, accessibility semantics and asset integrity are different obligations. The strict index proves that none was silently omitted; it does not prove that the project verifier
|
|
56
|
+
- A selected implementation handoff must already pass `ty-context design-resource preflight`. For each covered row, turn its declared verification methods into project-owned, independently failing observations in the target conformance Check: geometry/pixel/token/content, component state/interaction trace, motion timeline, responsive reflow/input method, accessibility semantics and asset integrity are different obligations. Each method maps to its own Assertion and typed `design_method` evidence; every exact condition declares a method record plus a method-native primary observation whose current path and digest cannot be reused by another cell. Playwright requires explicit record/observation attachments from every project instance. The strict index proves that none was silently omitted; it does not prove that the project verifier is semantically sound.
|
|
57
57
|
- Keep `design_resource_integrity` and `design_implementation_conformance` distinct. Stable paths/hashes, provider/export success, manifest/registry membership and expected counts prove resource integrity; `visual_render` proves a current artifact exists. Neither proves the production implementation matches a selected target.
|
|
58
|
-
- When external design resources are Source, prove
|
|
59
|
-
- A `design_conformance` record is accepted only for the compiled target/Assertion/current Check target, an equal declared condition-key set and both declared actual/comparison artifacts collected by the current Check. Missing or swapped targets, conditions or artifacts fail closed; the implementation render cannot also be the comparison authority.
|
|
60
|
-
- Use Playwright for every declared `ui_browser` visual AC and bind each independently falsifiable AC to its own `[ac:<assertion-key>]` Test Instance. A broad screenshot or one passing page case does not silently prove separate viewport, theme, state, content-stress, layout or accessibility claims.
|
|
58
|
+
- When external design resources are Source, prove every selected exact-target/constraint condition that the Contract explicitly adopts. Candidate comparison, a mutable provider link, extraction success, metadata-only output, resource digest or an isolated prototype run is authoring/integrity material and cannot become product acceptance. Resolve each acceptance-affecting fact through a typed locator plus immutable path/hash and declared target/condition applicability before Compile. Include the handoff and every source-profile entry/dependency in `verification_inputs`; project-owned method-specific single-Claim design-conformance, interaction and target-runtime observations must still fail independently on the current production target.
|
|
59
|
+
- A `design_conformance` record is accepted only for the compiled target/Assertion/current Check target, an equal declared condition-key set and both declared actual/comparison artifacts collected by the current Check. Its Assertion applicability must also equal the adopted target, conditions, journey and input/state facts. Missing or swapped targets, conditions or artifacts fail closed; the implementation render cannot also be the comparison authority.
|
|
60
|
+
- Use Playwright for every declared `ui_browser` visual AC and bind each independently falsifiable AC to its own `[ac:<assertion-key>]` Test Instance. A broad screenshot or one passing page case does not silently prove separate viewport, theme, state, content-stress, layout or accessibility claims; representative, sampled or pairwise coverage cannot waive an actual applicable cell.
|
|
61
61
|
- Make the test environment deterministic enough for its claim: freeze the relevant browser/project, viewport, theme/mode, locale/timezone, font loading, fixtures/data and animation/motion policy in declared verifier inputs or configuration.
|
|
62
62
|
- Any reviewed screenshot baseline that affects pass/fail must exist for the accepting Compile and be included in `verification_inputs`. Generated screenshots, diffs and reports are Artifacts and review material; they are not editable acceptance authority. Creating or replacing a baseline after Authority Lock is verifier-material revision and must never be silently auto-updated to make a failure pass.
|
|
63
63
|
- Confirm that each baseline is a selected `exact-target` for the named surface/viewport/theme/state or implements a named `constraint`; an inspiration reference cannot become a fidelity oracle merely because it is available. The implementation's current screenshot is never its own target.
|
|
64
|
-
- Screenshot comparison proves only the named visual similarity claim. Pair it with explicit DOM/layout/accessibility/motion/responsive/input assertions whenever the handoff or Contract separately declares no overflow, action visibility, focus behavior, target size, semantic state, reduced motion or other observable behavior. One generic `design_conformance` record cannot erase distinct Source Claims or verification methods; every handoff method binds a separate Assertion and the trusted Check must fail if any asserted method fails.
|
|
64
|
+
- Screenshot comparison proves only the named visual similarity claim. Pair it with explicit DOM/layout/accessibility/motion/responsive/input assertions whenever the handoff or Contract separately declares no overflow, action visibility, focus behavior, target size, semantic state, reduced motion or other observable behavior. One generic `design_conformance` record cannot erase distinct Source Claims or verification methods; every handoff method binds a separate Assertion and the trusted Check must fail if any asserted method fails.
|
|
65
65
|
- Keep evidence aligned with stable surface/control/target keys. Visual similarity, interaction/navigation, validation/recovery, permission behavior, accessibility and target-runtime conformance are independently failing claims and need their own Assertions/capabilities when declared; one broad screenshot or UI pass cannot prove all Control fields.
|
|
66
66
|
- Run checks against production components or real product routes. For each bound Control, the named root-entry journey must begin at the required product target root, execute the declared entry action and prove its navigation result—or interaction, trigger or location fallback—with `interaction_trace` plus `target_runtime`. A detached kit/mock/deep-link harness is acceptable only when the Contract explicitly makes that artifact the product surface; otherwise it cannot substitute for the production carrier or root journey.
|
|
67
|
-
- Keep subjective visual quality and approval external. A new visual direction or baseline that needs human judgment remains an explicit external confirmation even when all machine checks pass.
|
|
68
|
-
- `ui_browser` proves browser UI only. When a native/mobile/desktop UI can fail independently, browser output is proxy evidence; require a project-owned live target-runtime Check that truthfully fits an existing proof surface or keep the device/simulator review external.
|
|
67
|
+
- Keep subjective visual quality and approval external. A new visual direction or baseline that needs human judgment remains an explicit external confirmation even when all machine checks pass.
|
|
68
|
+
- `ui_browser` proves browser UI only. When a native/mobile/desktop UI can fail independently, browser output is proxy evidence; require a project-owned live target-runtime Check that truthfully fits an existing proof surface or keep the device/simulator review external.
|
|
69
|
+
- Preserve each handoff blocker's non-empty `required_capabilities`. A machine Claim closes it only on the exact execution target that declares every capability; physical device, sensor, camera, orientation, haptic, screen-reader, pixel-density, safe-area or comparable observations cannot be borrowed from a proxy target. If that runtime observation is unavailable or the Oracle cannot consume the target-owned acceptance criteria, keep the blocker as a target-blocking External Confirmation.
|
|
69
70
|
|
|
70
71
|
## Structured Evidence And Sensitivity
|
|
71
72
|
|
|
72
|
-
Every claim-bearing `structured_json_v2` Check needs same-Check Claim-related Counterfactual sensitivity
|
|
73
|
+
Every claim-bearing `structured_json_v2` Check needs same-Check Claim-related Counterfactual sensitivity. Population declares a real `universe_binding_key`; every universe carrier is an owning-Check `input_path`, and the current observation proves exact universe = eligible = observed plus valid exclusions by entity id. Population never substitutes for the claim-local narrow semantic witness and preserved target-runtime liveness required by a behavioral Claim. Artifacts and another Check never substitute for sensitivity.
|
|
73
74
|
|
|
74
|
-
Outcome Counterfactual V2 names an Outcome `binding_key`; Global Counterfactual V2 resolves an Outcome-owned `binding_ref`. A Counterfactual mutates only a proven subset of implementation carriers, never Source, Context, runners or verification inputs, and accepts only designated `assertion_value_mismatch` findings.
|
|
75
|
+
Outcome Counterfactual V2 names an Outcome `binding_key`; Global Counterfactual V2 resolves an Outcome-owned `binding_ref`. A Counterfactual mutates only a proven subset of implementation carriers, never Source, Context, runners or verification inputs, and accepts only designated `assertion_value_mismatch` findings. Behavioral witnesses use claim-local `replace_json_value` or `replace_text`, list their designated Claim-bearing failure Assertions, and list the claimless liveness Assertions that must remain passing.
|
|
75
76
|
|
|
76
|
-
An `existing` mutation target must exist at Preflight/Compile. A `planned` target may be absent until implementation but must exist at Final Gate; once created, its changes stale targeted Progress.
|
|
77
|
+
An `existing` mutation target must exist at Preflight/Compile and the JSON pointer/text fragment must resolve uniquely. A `planned` target may be absent until implementation but must exist at Final Gate; once created, its changes stale targeted Progress.
|
|
77
78
|
|
|
78
79
|
Artifacts remain review material. They do not prove Claim sensitivity by themselves.
|