project-tiny-context-harness 0.7.2 → 0.7.4
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 +7 -5
- package/assets/README.md +49 -14
- package/assets/README.zh-CN.md +26 -13
- package/assets/agents/AGENTS_CORE.md +5 -5
- package/assets/context_templates/global.md +1 -0
- package/assets/skills/context_development_engineer/SKILL.md +4 -1
- package/assets/skills/context_uiux_design/SKILL.md +19 -6
- package/assets/skills/long-task-workflow/SKILL.md +10 -9
- package/assets/skills/long-task-workflow/references/authority-lifecycle.md +7 -5
- package/assets/skills/long-task-workflow/references/contract-authoring.md +24 -6
- package/assets/skills/long-task-workflow/references/evidence-design.md +14 -1
- package/assets/skills/source-plan-authoring/SKILL.md +2 -2
- package/dist/commands/long-task-authoring.js +25 -0
- package/dist/commands/long-task.js +3 -0
- package/dist/lib/design-md.d.ts +3 -0
- package/dist/lib/design-md.js +48 -55
- package/dist/lib/doctor.js +8 -0
- package/dist/lib/long-task-activation-validation.js +13 -2
- package/dist/lib/long-task-authoring-authority-preview.js +1 -0
- package/dist/lib/long-task-authority-material-diff.js +26 -0
- package/dist/lib/long-task-authority-materials.d.ts +2 -2
- package/dist/lib/long-task-authority-materials.js +6 -0
- package/dist/lib/long-task-authority-policy.d.ts +12 -0
- package/dist/lib/long-task-authority-policy.js +9 -0
- package/dist/lib/long-task-authority-revision-analysis.d.ts +33 -0
- package/dist/lib/long-task-authority-revision-analysis.js +91 -0
- package/dist/lib/long-task-authority-revision.js +93 -158
- package/dist/lib/long-task-authority-types.d.ts +7 -0
- package/dist/lib/long-task-authority.js +32 -3
- package/dist/lib/long-task-check-evidence-decoder.d.ts +2 -2
- package/dist/lib/long-task-check-evidence-decoder.js +11 -1
- package/dist/lib/long-task-check-execution-policy.d.ts +3 -0
- package/dist/lib/long-task-check-execution-policy.js +5 -0
- package/dist/lib/long-task-check-runner.js +2 -0
- package/dist/lib/long-task-check-shape.js +33 -3
- package/dist/lib/long-task-conformance-policy.d.ts +5 -0
- package/dist/lib/long-task-conformance-policy.js +35 -0
- package/dist/lib/long-task-contract-types.d.ts +14 -4
- package/dist/lib/long-task-delivery-compiler.js +1 -0
- package/dist/lib/long-task-delivery-parser.js +5 -2
- package/dist/lib/long-task-delivery-types.d.ts +2 -0
- package/dist/lib/long-task-delivery-types.js +2 -0
- package/dist/lib/long-task-delivery-validation.js +11 -0
- package/dist/lib/long-task-evidence-capability-codec.d.ts +2 -0
- package/dist/lib/long-task-evidence-capability-codec.js +231 -0
- package/dist/lib/long-task-evidence-capability-policy.d.ts +8 -0
- package/dist/lib/long-task-evidence-capability-policy.js +147 -0
- package/dist/lib/long-task-evidence-capability-runtime.d.ts +2 -0
- package/dist/lib/long-task-evidence-capability-runtime.js +86 -0
- package/dist/lib/long-task-evidence-capability-types.d.ts +74 -0
- package/dist/lib/long-task-evidence-capability-types.js +1 -0
- package/dist/lib/long-task-evidence-findings.js +5 -1
- package/dist/lib/long-task-evidence-v2.js +38 -23
- package/dist/lib/long-task-final-v2.js +42 -1
- package/dist/lib/long-task-outcome-parser.js +14 -3
- package/dist/lib/long-task-playwright-evidence.d.ts +2 -1
- package/dist/lib/long-task-playwright-evidence.js +70 -2
- package/dist/lib/long-task-progress.js +4 -0
- package/dist/lib/long-task-root-shape.d.ts +1 -0
- package/dist/lib/long-task-root-shape.js +84 -3
- package/dist/lib/long-task-runner-environment.js +1 -1
- package/dist/lib/long-task-runner-freeze.d.ts +2 -2
- package/dist/lib/long-task-runner-freeze.js +3 -1
- package/dist/lib/long-task-runtime-types.d.ts +13 -0
- package/dist/lib/long-task-semantic-contract-types.d.ts +36 -0
- package/dist/lib/long-task-semantic-contract-types.js +1 -0
- package/dist/lib/long-task-semantic-drift-migration.d.ts +3 -0
- package/dist/lib/long-task-semantic-drift-migration.js +68 -0
- package/dist/lib/long-task-shape-primitives.d.ts +3 -0
- package/dist/lib/long-task-shape-primitives.js +25 -0
- package/dist/lib/long-task-stage-policy.d.ts +4 -0
- package/dist/lib/long-task-stage-policy.js +120 -0
- package/dist/lib/long-task-status-projection.d.ts +4 -1
- package/dist/lib/long-task-status-projection.js +63 -3
- package/dist/lib/long-task-status-v2.d.ts +11 -1
- package/dist/lib/long-task-status-v2.js +25 -3
- package/dist/lib/long-task-target-policy.d.ts +6 -0
- package/dist/lib/long-task-target-policy.js +127 -0
- package/dist/lib/migrations.js +29 -0
- package/dist/schemas/long-task-delivery-v2/long-task-delivery-v2.schema.json +61 -7
- package/migrations/README.md +7 -0
- package/package.json +2 -2
|
@@ -15,7 +15,7 @@ The host and user own model selection and native-Goal lifecycle. The workflow ha
|
|
|
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 stale item must block completion. Findings should localize repair through Source Item, Outcome, Claim, Assertion, Check,
|
|
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 stale item must block completion. In particular, a proxy target, presence text, degradation path, fixed input, self-reported boundary effect or internal entrypoint must never substitute for the declared target behavior. Findings should localize repair through Source Item, Stage, Outcome, Claim, Assertion, Check, Evidence Capability, execution target, Binding and owner boundary.
|
|
19
19
|
|
|
20
20
|
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 covers declared machine Authority and has no direct native-Goal effect. Never substitute prose, progress, historical tests, Receipts, one exit code or Agent judgment for the Final Gate.
|
|
21
21
|
|
|
@@ -35,36 +35,37 @@ Do not copy reference detail into another plan or state file. The same `delivery
|
|
|
35
35
|
|
|
36
36
|
Before the first successful formal Compile, continuously revise the same non-authoritative `delivery-contract.yaml` as the Contract Draft. 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 standalone Contract Draft Skill, Draft Receipt, Authoring State, draft schema/CLI/runtime state or second plan.
|
|
37
37
|
|
|
38
|
-
A Draft Outcome is an Outcome in that pre-Authority-Lock Draft, not a new schema field or runtime entity. Decompose only independently observable, decidable and target-verifiable results whose dependencies and owner boundary can be stated. Use those boundaries to keep a dependency-ready working set, target verification, localize failures, resume findings/next actions and stale local results precisely.
|
|
38
|
+
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 keep a stage-constrained dependency-ready working set, target verification, localize failures, resume findings/next actions and stale local results precisely.
|
|
39
39
|
|
|
40
|
-
`depends_on` means acceptance readiness. The current Goal
|
|
40
|
+
`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 must 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.
|
|
41
41
|
|
|
42
42
|
> Outcome decomposes execution and diagnosis, not completion authority.
|
|
43
43
|
|
|
44
44
|
## Entry And Authoring Loop
|
|
45
45
|
|
|
46
46
|
1. Read the user request or external proposal plus minimum controlling Context and decide `Context Delta: none|required`.
|
|
47
|
+
- For material production UI, read the Contract-authoring visual guidance before Compile. An unconfigured starter, style-only rule or inspiration-only reference is incomplete design authority unless Source explicitly scopes the result as prototype/non-fidelity or delegates a separate selected target before implementation.
|
|
47
48
|
2. If a valid active binding exists, run `ty-context long-task resume <workdir>` and read the lifecycle reference.
|
|
48
|
-
3. Otherwise author one complete Delivery Contract for the whole selected delivery. Do not create a second Contract plan, matrix or top-level Contract split.
|
|
49
|
+
3. Otherwise author one complete Delivery Contract for the whole selected delivery. Declare the target profile, its non-empty required product target refs, each target's runtime family/root entrypoint, ordered Stages and vertical Outcomes. Do not create a second Contract plan, matrix or top-level Contract split.
|
|
49
50
|
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 the text; marked Source Item keys and `source_claim` keys are exactly equal.
|
|
50
51
|
5. An ordinary prose plan or optional Source Plan remains valid Source after marker-only enumeration and does not need to match the recommended Source Plan structure. Preserve stable semantic keys and Markdown anchors where practical.
|
|
51
52
|
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.
|
|
52
53
|
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.
|
|
53
54
|
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`.
|
|
54
|
-
9. Run read-only `ty-context long-task preflight <workdir>`, repair every error and `decision_required` finding in the same Draft, then formally Compile only when ready.
|
|
55
|
+
9. Give every Check an atomic Given/When scenario and journey role; give every Assertion the minimum all-of Evidence Capabilities that can actually prove its Claim. Separate required success and degradation Checks. Type every external confirmation with impacted Claim refs and target-blocking effect. Run read-only `ty-context long-task preflight <workdir>`, repair every error and `decision_required` finding in the same Draft, then formally Compile only when ready.
|
|
55
56
|
10. When the first Compile returns `execution_model_checkpoint.required: true`, stop before implementation and ask the user to choose `continue_current_model` or switch models and then resume the active Long-Task. A task-specific choice already stated explicitly satisfies the checkpoint. Later revisions return `required: false` and do not repeat it.
|
|
56
57
|
|
|
57
58
|
Architecture quality uses the existing authority model, not a new gate: when Source or controlling Context declares an architecture invariant, encode it 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.
|
|
58
59
|
|
|
59
60
|
## Rolling Execution
|
|
60
61
|
|
|
61
|
-
After Authority Lock and the one-time execution-model checkpoint are satisfied, implement
|
|
62
|
+
After Authority Lock and the one-time execution-model checkpoint are satisfied, implement only Outcomes in the derived current Stage frontier, plus prerequisite regression repairs and current Finding repairs, in the current workspace. A later Stage cannot substitute for an unpassed earlier gate. Small implementation plans and repair hypotheses are internal execution state and cannot silently change Product, Technical or Acceptance authority.
|
|
62
63
|
|
|
63
64
|
Re-evaluate `Context Delta` whenever implementation or repair discovers a durable fact. Controlling Context changes use protected revision; 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.
|
|
64
65
|
|
|
65
66
|
Use targeted `verify --outcome/--check` only to drive repair. 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 coordinate parallel subagents.
|
|
66
67
|
|
|
67
|
-
When the Contract declares a target-runtime Check because a proxy can pass while the target fails independently, run it at the earliest owning Outcome's first runnable boundary. After accumulated changes to
|
|
68
|
+
When the Contract declares a target-runtime Check because a proxy can pass while the target fails independently, run it at the earliest owning Outcome's first runnable boundary. Every required target is proved separately from its root; Browser evidence requires Playwright and Native/Desktop evidence requires the project binary. After accumulated changes to declared `input_paths` or Binding carriers make the result stale, rerun before dependent work grows. Coalesce related edits and use the cheapest reliable target Check; do not mandate a full environment rebuild per Outcome or per edit. This is rolling feedback through existing targeted verify, not acceptance, a trigger queue or per-target progress state.
|
|
68
69
|
|
|
69
70
|
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. Proven monotonic evidence strengthening may use ordinary `compile --revise` directly. If every protected reason is only owner/expected-change/allowed-support expansion, continue editing the same `delivery-contract.yaml` and use `ty-context long-task diagnose-revision <workdir> [--outcome <key>] [--check <key>]` to exercise only existing active Check identities with unchanged runner/verifier authority; safe monotonic strengthening may coexist. Candidate diagnostics are transient: they authorize no acceptance and write no pending/approval state, Active Authority, cache, Progress or Receipt. Semantic changes, proof weakening, runner or verifier-content changes, and risk-increase candidates are preview-only and must not run; risk downgrade is rejected. When the candidate is complete, run ordinary `compile --revise` once, present its exact material decision summary to the user, and never approve it yourself. Keep the previous Authority active until exact approval and atomic adoption. Adoption is not delivery completion: discard historical/candidate evidence, run `status` or `resume`, and return to rolling implementation or repair under the revised Authority before Final Gate.
|
|
70
71
|
|
|
@@ -72,7 +73,7 @@ When implementation discovers a blocker or missing Contract paths, first classif
|
|
|
72
73
|
|
|
73
74
|
Complete Context, implementation and project tests, create a clean candidate commit, then run `ty-context long-task final-gate <workdir>`.
|
|
74
75
|
|
|
75
|
-
Final Gate recompiles Source authority, validates active task/revision/compiled/worktree identity, creates one Git-tree snapshot, reruns every required Global and Outcome Check and rechecks active identity before acceptance. A target-runtime Check must exercise its target in that current Gate execution; rerunning a reader for a historical or tracked status report is not live target proof. Final Gate, Stop and close never trust historical Progress, Receipt or compiled cache.
|
|
76
|
+
Final Gate recompiles Source authority, validates active task/revision/compiled/worktree identity, creates one Git-tree snapshot, reruns every required Global and Outcome Check and rechecks active identity 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. Final Gate, Stop and close never trust historical Progress, Receipt or compiled cache.
|
|
76
77
|
|
|
77
78
|
Machine acceptance covers only declared machine authority. Preserve every pending external confirmation through `final-gate`, `status`, `resume`, `stop-check`, the package-owned Stop Hook and `close`; accepted output identifies `acceptance_scope: declared_machine_authority` and `native_goal_effect: none`, while `closed_scope: machine_authority` means only Authority cleanup. Do not invent external-confirmation or native-Goal tracking state.
|
|
78
79
|
|
|
@@ -80,4 +81,4 @@ Before invoking platform-native Goal completion, perform one veto-only conforman
|
|
|
80
81
|
|
|
81
82
|
## Handoff
|
|
82
83
|
|
|
83
|
-
Report implementation, effective risk, Claim Coverage, 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 not a current pass, `final_workflow_status: null` means unfinished, `authority_revision_adopted` means return to rolling execution, and `machine_accepted_external_pending` must retain its named confirmations.
|
|
84
|
+
Report implementation, effective risk, 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 not a current pass, `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 threat-model limits: undeclared requirements cannot be discovered, installed verifier/Git metadata are trusted, native-Goal/model selection belongs to the host/user, and internal platform delegation is not observed.
|
|
@@ -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, adapter/Observation, risk, owner/path/Binding, runner/input, Counterfactual or sensitivity rule.
|
|
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, runner/input, Counterfactual or sensitivity rule.
|
|
10
10
|
|
|
11
11
|
Preflight keeps every independently discovered diagnostic. When a structural duplicate makes the same Claim ambiguous or repeated, only that pair receives stable `diagnostic_id`, `repair_group`, `repair_priority` and `blocked_by` metadata so the structural blocker is repaired first. Independent findings keep their compact existing shape; no finding is hidden, reclassified or treated as resolved, and no repair state or authority is created.
|
|
12
12
|
|
|
@@ -18,9 +18,9 @@ Its JSON result includes `execution_model_checkpoint.required: true`. Before pro
|
|
|
18
18
|
|
|
19
19
|
After Authority Lock, every revision compares against active authority and follows one of three paths:
|
|
20
20
|
|
|
21
|
-
1. proven monotonic evidence strengthening
|
|
21
|
+
1. proven monotonic evidence strengthening—including adding capabilities while preserving every existing Assertion meaning—pure verifier relocation, proven tightening and supporting-only Context revision may auto-revise;
|
|
22
22
|
2. a candidate whose only protected reasons are owner, expected-change or allowed-support expansion remains inactive but may be exercised with `diagnose-revision` through existing active Check identities whose runner/verifier authority is unchanged; safe monotonic strengthening may coexist; or
|
|
23
|
-
3. every semantic change, proof weakening, runner or verifier-content change, risk change or other protected reason requires the exact revision identity and is never candidate-executed.
|
|
23
|
+
3. every Source/Product/target profile/required-target/Stage/success-degradation/external-impact semantic change, removed capability or scenario step, root-to-internal move, proof weakening, runner or verifier-content change, risk change or other protected reason requires the exact revision identity and is never candidate-executed.
|
|
24
24
|
|
|
25
25
|
`diagnose-revision` recompiles the same `delivery-contract.yaml` in memory, creates only a disposable workspace snapshot when class 2 is proven, and returns transient repair results with `acceptance_authorized: false`. It writes no pending/approval state, authority/marker, cache, Progress or Receipt. Repeated edits therefore accumulate only in the one existing Contract authoring file, not a pending Draft authority or candidate state plane.
|
|
26
26
|
|
|
@@ -42,14 +42,16 @@ Progress freshness binds Outcome authority, runner, verification inputs, Control
|
|
|
42
42
|
|
|
43
43
|
Status, Progress, Receipts and workdir compiled output are audit/recovery projections only. Development-period authority state is `manual_required` and never migrated.
|
|
44
44
|
|
|
45
|
-
Report their exact meaning: `progress_passing` is current targeted repair evidence rather than “Outcome complete”; `progress_stale` is not a current pass; `final_workflow_status: null` means the Goal is unfinished.
|
|
45
|
+
Report their exact meaning: `progress_passing` is current targeted repair evidence rather than “Outcome complete”; `progress_stale` is not a current pass; `final_workflow_status: null` means the Goal is unfinished. `status`/`resume` derive `ready_stages`, `ready_outcomes` and Stage status from current Progress; they do not persist a Stage pass. `target_state` remains `not_accepted` until a fresh Final Gate accepts, becomes `blocked_external` for a target blocker, or names the Contract's `implementation_complete`, `target_profile_usable` or `production_release_ready` state after machine acceptance. Do not invent per-platform progress/status.
|
|
46
46
|
|
|
47
47
|
## Final Gate And Terminal Paths
|
|
48
48
|
|
|
49
|
-
Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate captures active identity, recompiles Source authority, reads complete current Context, validates common-dir record/marker, creates a Git-tree snapshot, reruns all Checks and sensitivity controls and rechecks identity before acceptance. A target-runtime Check must exercise its target again in that Final Gate execution; rereading historical status does not become live proof merely because the reader reran. A concurrent revision returns `active_authority_changed_during_final_gate`.
|
|
49
|
+
Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate captures active identity, recompiles Source authority, reads complete current Context, validates common-dir record/marker, creates a Git-tree snapshot, reruns all Checks and sensitivity controls and rechecks identity before acceptance. 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`. A concurrent revision returns `active_authority_changed_during_final_gate`.
|
|
50
50
|
|
|
51
51
|
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.
|
|
52
52
|
|
|
53
53
|
Before platform-native Goal completion, compare current Goal/user meaning with accepted marked Source and check for a pending revision, unresolved blocker or omitted requirement. This review may only veto completion and direct Source/Contract repair; it is not a second acceptance Gate and cannot create proof.
|
|
54
54
|
|
|
55
55
|
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.
|
|
56
|
+
|
|
57
|
+
An older `long-task-delivery-v2` Contract that lacks Stage, required-target, scenario, journey, success/degradation, capability 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.
|
|
@@ -31,6 +31,14 @@ For every Outcome declare:
|
|
|
31
31
|
|
|
32
32
|
Global non-goals, constraints and forbidden shortcuts remain Global authority and use Global Checks/Assertions when machine proof is required.
|
|
33
33
|
|
|
34
|
+
## Stage And Target Profile
|
|
35
|
+
|
|
36
|
+
- 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.
|
|
37
|
+
- 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.
|
|
38
|
+
- 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.
|
|
39
|
+
- `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 root entrypoint. Every Stage Gate and every `critical_user_path` Outcome provides root `target_runtime` proof for every required ref; optional support/observer targets never substitute.
|
|
40
|
+
- 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.
|
|
41
|
+
|
|
34
42
|
## Architecture Closure
|
|
35
43
|
|
|
36
44
|
Architecture protection is risk-triggered and project-specific. Use it when the delivery declares module ownership, unique source of truth, dependency direction, API/schema/data boundary, state lifecycle, persistence/recovery, security boundary, compatibility/migration or a forbidden bypass.
|
|
@@ -47,7 +55,7 @@ Do not encode subjective “clean architecture” or generic quality prose as ma
|
|
|
47
55
|
|
|
48
56
|
## Proxy And Target Runtime Independence
|
|
49
57
|
|
|
50
|
-
When a declared result can pass on a proxy surface while failing in its target runtime, author independent target-runtime proof. 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.
|
|
58
|
+
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.
|
|
51
59
|
|
|
52
60
|
Use existing Contract semantics:
|
|
53
61
|
|
|
@@ -57,24 +65,34 @@ Use existing Contract semantics:
|
|
|
57
65
|
4. freeze runner helpers/configuration as `verification_inputs` and declare only genuine environment requirements; and
|
|
58
66
|
5. add capability-specific probes only for Claims that actually require them.
|
|
59
67
|
|
|
60
|
-
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.
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
## Success, Degradation And External Boundaries
|
|
71
|
+
|
|
72
|
+
- Set `success_path_required` and `degradation_path_required` explicitly. A Result Claim is proved only by a `success` Check; the same Check cannot be both success and degradation, and an honest unavailable/pending/recovery state cannot replace required success.
|
|
73
|
+
- External confirmations declare `kind`, exact `impact_claims` and `blocks_target`. A `functional_prerequisite` blocks the selected target; a `production_release_gate` blocks a production-release target but may remain non-blocking for a lower target. Reclassification or impact changes are protected authority.
|
|
74
|
+
- `boundary_invocation` and `external_side_effect` are machine evidence only when their Check executes on a declared independent `observer` target. Product self-report never proves the downstream effect.
|
|
61
75
|
|
|
62
76
|
## Visual Delivery Authoring
|
|
63
77
|
|
|
64
|
-
When
|
|
78
|
+
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:
|
|
65
79
|
|
|
80
|
+
- 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;
|
|
81
|
+
- 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`;
|
|
82
|
+
- 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;
|
|
66
83
|
- derive a task-local, risk-proportional 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;
|
|
67
84
|
- select representative combinations rather than silently creating a full Cartesian requirement; an omitted combination remains unproven, while Source that explicitly requires full coverage must retain that scope;
|
|
68
85
|
- 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;
|
|
69
|
-
- bind the declared result to the owning Context/`DESIGN.md`, one authored token source and generation direction, production component/route carriers, path envelopes and project-owned
|
|
86
|
+
- 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. Detached kits, mocks or marketing specimens may be references but not substitute implementation carriers;
|
|
87
|
+
- 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;
|
|
70
88
|
- 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.
|
|
71
89
|
|
|
72
|
-
This guidance adds no visual Schema, Claim kind, risk level, lifecycle state, coverage artifact or Gate. It only makes visual meaning explicit enough for
|
|
90
|
+
This guidance adds no visual Schema, Claim kind, risk level, lifecycle state, coverage artifact, required design directory or Gate. It only makes visual meaning explicit enough for existing Source, Requirement/Control/Assertion, proof-surface, verification-input and external-confirmation mechanisms to verify what was actually declared.
|
|
73
91
|
|
|
74
92
|
## Compact Authoring
|
|
75
93
|
|
|
76
94
|
Compact V2 may omit only deterministic defaults: empty optional arrays/nulls, `context_snapshot_mode: referenced`, `requested_level: auto`, runner `argv: []`, `cwd: .`, `timeout_ms: 30000`, `retry_policy: none`, `idempotent: false`, and empty output/artifact/assertion/environment lists.
|
|
77
95
|
|
|
78
|
-
Goal, Source/Source Claims, Context, observable results, owners/paths, REQ, applicable CTRL states, OBL, proof surfaces, runner targets/effects, verification inputs, Assertions, risk, forbidden shortcuts and external confirmations remain explicit.
|
|
96
|
+
Goal, target profile/required targets, ordered Stages, Source/Source Claims, Context, observable results, success/degradation requirements, owners/paths, REQ, applicable CTRL states, OBL, proof surfaces, Given/When scenarios, journey roles, Evidence Capabilities, runner targets/effects, verification inputs, Assertions, risk, forbidden shortcuts and typed external confirmations remain explicit.
|
|
79
97
|
|
|
80
98
|
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.
|
|
@@ -17,9 +17,18 @@ Evidence adapter is derived from runner kind. Only Playwright may prove `ui_brow
|
|
|
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
|
+
## Scenario And Evidence Capabilities
|
|
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.
|
|
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
|
+
- `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
|
+
- `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; `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.
|
|
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
|
+
|
|
20
29
|
## Live Target Runtime Evidence
|
|
21
30
|
|
|
22
|
-
- For a target-runtime Claim, the accepting Check must exercise
|
|
31
|
+
- For a target-runtime Claim, the accepting Check must exercise the exact declared required target during the current runner invocation and derive structured Observations from the same runtime session. Browser target runtime is proved only by Playwright; Native/Desktop target runtime is proved only by the project binary. Rerunning a parser for a tracked or generated status report reruns the parser, not the target.
|
|
23
32
|
- A proxy surface may prove its own Claim but cannot substitute when proxy and target can fail independently. Static source/config shape proves structure only. The existence of a build, installation, started process or clean fatal-error scan proves only those exact assertions.
|
|
24
33
|
- If the declared result includes a runnable product surface or interaction, observe a stable product-owned sentinel or the declared interaction in the target session. A generic process/activity/window, development shell or absence of errors is insufficient for that broader Claim.
|
|
25
34
|
- Historical reports, screenshots, binaries and logs are review material. Current-run screenshots/logs may accompany a Check as Artifacts, but the accepting Observation must come from the live runner execution and cannot be imported from historical state.
|
|
@@ -32,6 +41,8 @@ Across all Checks sharing a Raw Execution, one Claim-bearing Observation belongs
|
|
|
32
41
|
- For a behavioral Claim, prefer a Counterfactual that disrupts the claimed causal capability when removing a carrier would prove only file dependence. `replace_file` may supply a declared inert/failing implementation fixture; `remove_paths` remains valid when carrier existence is itself the claimed boundary.
|
|
33
42
|
- Keep this risk-proportional and internal. Do not create an evidence matrix, product-effect taxonomy, universal restart/end-to-end suite, new mutation type or persistent review state.
|
|
34
43
|
|
|
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
|
+
|
|
35
46
|
## Playwright
|
|
36
47
|
|
|
37
48
|
Claim-bearing Playwright proof is only `playwright.case.<ac-key>.passed equals true`. `[ac:<assertion-key>]` binds one declared AC per Test Instance; ordinary tags are ignored and legacy `[<key>]` binds only a declared key.
|
|
@@ -45,9 +56,11 @@ Standard frozen Playwright verifier content is trusted. Weak-observability Outco
|
|
|
45
56
|
- 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.
|
|
46
57
|
- 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.
|
|
47
58
|
- 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.
|
|
59
|
+
- 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.
|
|
48
60
|
- Screenshot comparison proves only the named visual similarity claim. Pair it with explicit DOM/layout/accessibility assertions when the Contract separately claims no overflow, action visibility, focus behavior, target size, semantic state, reduced motion or other observable behavior.
|
|
49
61
|
- Run checks against production components or real product routes. A detached kit/mock harness is acceptable only when the Contract explicitly makes that artifact the product surface; otherwise it cannot substitute for the production carrier.
|
|
50
62
|
- 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.
|
|
63
|
+
- `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.
|
|
51
64
|
|
|
52
65
|
## Structured Evidence And Sensitivity
|
|
53
66
|
|
|
@@ -46,7 +46,7 @@ Before authoring:
|
|
|
46
46
|
|
|
47
47
|
1. Assign every supplied artifact a stable input ID and inspect it with format-appropriate capabilities. Cover all pages, frames, screens, tables, diagrams, annotations and visible states that can carry material meaning; never silently sample a multi-part artifact.
|
|
48
48
|
2. Classify each input as user instruction, authoritative product requirement, authoritative technical constraint, existing plan, repository/Context evidence, reference or inspiration. User-stated precedence wins; otherwise report material conflicts as `DEC` instead of merging them silently.
|
|
49
|
-
3. For screenshots or visual references, inventory visible surfaces, regions, controls, content hierarchy, navigation cues and represented states
|
|
49
|
+
3. For screenshots or visual references, inventory visible surfaces, regions, controls, content hierarchy, navigation cues and represented states, then classify the interpretation as `exact-target`, `constraint` or `inspiration`. Treat it as inspiration unless the user or a higher-authority input makes exact/constraint scope explicit; do not import unrelated branding, sample data or product scope.
|
|
50
50
|
4. Record an Input Inventory in the Source Plan with each input ID, role, authority, material content incorporated and any unreadable or intentionally unused portion. The inventory is traceability, not a new semantic type or authority.
|
|
51
51
|
5. Make the resulting plan self-contained: incorporate every material requirement or constraint into a keyed item. Keep an external artifact reference only when the artifact itself remains necessary for exact visual, legal or other non-textual comparison.
|
|
52
52
|
|
|
@@ -206,7 +206,7 @@ Include a `CTRL` when:
|
|
|
206
206
|
|
|
207
207
|
For each included control, state every independently decided field separately: `Surface`, `Region`, `Control type`, `Label/content`, `Location`, `User task`, `Visibility`, `Availability`, `Trigger`, `Input`, `Validation`, `Default`, `Interaction`, `Navigation/result`, `Loading`, `Empty`, `Success`, `Failure`, `Recovery`, `Permission`, `Feedback` and `Accessibility`. Use `not applicable` when a field was considered and genuinely does not apply; do not hide an undecided product choice behind that phrase.
|
|
208
208
|
|
|
209
|
-
Give every decided Control field its own stable semantic meaning. Do not compress placement, behavior, state or feedback into one broad sentence when more than one field has been decided; later repository-aware authoring must be able to map each field independently. Do not claim exact visual styling, animation, copy or responsive behavior unless it is direct, evidence-backed or within recorded delegation.
|
|
209
|
+
Give every decided Control field its own stable semantic meaning. Do not compress placement, behavior, state or feedback into one broad sentence when more than one field has been decided; later repository-aware authoring must be able to map each field independently. Do not claim exact visual styling, animation, copy or responsive behavior unless it is direct, evidence-backed or within recorded delegation. When exact non-textual comparison remains necessary, preserve the selected reference id/path/URI and its covered viewport/theme/state instead of replacing it with prose.
|
|
210
210
|
|
|
211
211
|
## Acceptance Scenarios
|
|
212
212
|
|
|
@@ -28,6 +28,17 @@ task:
|
|
|
28
28
|
id: replace-me
|
|
29
29
|
title: Replace me
|
|
30
30
|
goal: Describe the complete observable delivery goal.
|
|
31
|
+
target_profile:
|
|
32
|
+
key: replace-target
|
|
33
|
+
description: The declared product target is usable from its root entrypoint.
|
|
34
|
+
required_state: target_profile_usable
|
|
35
|
+
required_target_refs: [replace-runtime]
|
|
36
|
+
execution_targets:
|
|
37
|
+
- key: replace-runtime
|
|
38
|
+
description: The product runtime used by the acceptance oracle.
|
|
39
|
+
role: product
|
|
40
|
+
runtime_family: process
|
|
41
|
+
root_entrypoint: tests/replace-oracle.mjs
|
|
31
42
|
source_paths: [plans/replace-me.md]
|
|
32
43
|
context_refs: [project_context/areas/replace-me.md]
|
|
33
44
|
source_claims:
|
|
@@ -37,14 +48,22 @@ source_claims:
|
|
|
37
48
|
disposition:
|
|
38
49
|
type: claim
|
|
39
50
|
refs: [replace-outcome.requirement.replace-requirement]
|
|
51
|
+
stages:
|
|
52
|
+
- key: delivery
|
|
53
|
+
title: Delivery
|
|
54
|
+
depends_on: []
|
|
55
|
+
gate_outcome: replace-outcome
|
|
40
56
|
risk:
|
|
41
57
|
facts: {}
|
|
42
58
|
global: {}
|
|
43
59
|
outcomes:
|
|
44
60
|
- key: replace-outcome
|
|
45
61
|
title: Replace outcome
|
|
62
|
+
stage: delivery
|
|
46
63
|
product:
|
|
47
64
|
observable_result: Describe what a user or system can observe.
|
|
65
|
+
success_path_required: true
|
|
66
|
+
degradation_path_required: false
|
|
48
67
|
owner:
|
|
49
68
|
label: replace-owner
|
|
50
69
|
context_refs: [project_context/areas/replace-me.md]
|
|
@@ -64,6 +83,11 @@ outcomes:
|
|
|
64
83
|
acceptance:
|
|
65
84
|
checks:
|
|
66
85
|
- key: replace-check
|
|
86
|
+
journey_roles: [success, stage_gate]
|
|
87
|
+
execution_target: {target_ref: replace-runtime, entrypoint: root}
|
|
88
|
+
scenario:
|
|
89
|
+
given: [{key: source-ready, statement: The planned source carrier is available.}]
|
|
90
|
+
when: [{key: inspect-result, statement: Inspect the product result through the declared runtime.}]
|
|
67
91
|
proof_surface: runtime_behavior
|
|
68
92
|
runner:
|
|
69
93
|
type: node_oracle
|
|
@@ -77,6 +101,7 @@ outcomes:
|
|
|
77
101
|
criterion: The declared outcome and requirement are observable.
|
|
78
102
|
claims: [result, requirement.replace-requirement]
|
|
79
103
|
observation: result
|
|
104
|
+
evidence_capabilities: [state_delta, target_runtime]
|
|
80
105
|
operator: equals
|
|
81
106
|
expected: true
|
|
82
107
|
counterfactual_controls:
|
|
@@ -68,6 +68,9 @@ export async function longTask(args) {
|
|
|
68
68
|
workdir,
|
|
69
69
|
workflow_status: result.workflow_status,
|
|
70
70
|
external_confirmations: result.external_confirmations,
|
|
71
|
+
target_profile: result.target_profile,
|
|
72
|
+
target_state: result.target_state,
|
|
73
|
+
stage_results: result.stage_results,
|
|
71
74
|
acceptance_scope: result.acceptance_scope,
|
|
72
75
|
closed_scope: result.closed_scope,
|
|
73
76
|
native_goal_effect: result.native_goal_effect,
|
package/dist/lib/design-md.d.ts
CHANGED
|
@@ -1,2 +1,5 @@
|
|
|
1
1
|
export declare const DESIGN_MD_PATH = "DESIGN.md";
|
|
2
|
+
export declare const UNCONFIGURED_DESIGN_AUTHORITY_MARKER = "Design authority status: `unconfigured`";
|
|
3
|
+
export type DesignAuthorityStatus = "missing" | "unconfigured" | "configured";
|
|
2
4
|
export declare function createDesignMdIfMissing(projectRoot: string): Promise<boolean>;
|
|
5
|
+
export declare function inspectDesignAuthorityStatus(projectRoot: string): Promise<DesignAuthorityStatus>;
|
package/dist/lib/design-md.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import path from "node:path";
|
|
2
|
-
import { pathExists, writeTextIfChanged } from "./fs.js";
|
|
2
|
+
import { pathExists, readText, writeTextIfChanged } from "./fs.js";
|
|
3
3
|
export const DESIGN_MD_PATH = "DESIGN.md";
|
|
4
|
+
export const UNCONFIGURED_DESIGN_AUTHORITY_MARKER = "Design authority status: `unconfigured`";
|
|
4
5
|
export async function createDesignMdIfMissing(projectRoot) {
|
|
5
6
|
const target = path.join(projectRoot, DESIGN_MD_PATH);
|
|
6
7
|
if (await pathExists(target)) {
|
|
@@ -8,12 +9,24 @@ export async function createDesignMdIfMissing(projectRoot) {
|
|
|
8
9
|
}
|
|
9
10
|
return writeTextIfChanged(target, designMdTemplate());
|
|
10
11
|
}
|
|
12
|
+
export async function inspectDesignAuthorityStatus(projectRoot) {
|
|
13
|
+
const target = path.join(projectRoot, DESIGN_MD_PATH);
|
|
14
|
+
if (!(await pathExists(target)))
|
|
15
|
+
return "missing";
|
|
16
|
+
const content = await readText(target);
|
|
17
|
+
if (content.includes(UNCONFIGURED_DESIGN_AUTHORITY_MARKER)) {
|
|
18
|
+
return "unconfigured";
|
|
19
|
+
}
|
|
20
|
+
const legacyStarter = content.includes('name: "Starter Design System"') &&
|
|
21
|
+
content.includes('description: "Neutral baseline design guidance for projects that have not defined their own visual system."');
|
|
22
|
+
return legacyStarter ? "unconfigured" : "configured";
|
|
23
|
+
}
|
|
11
24
|
function designMdTemplate() {
|
|
12
25
|
return [
|
|
13
26
|
"---",
|
|
14
27
|
'version: "alpha"',
|
|
15
|
-
'name: "
|
|
16
|
-
'description: "
|
|
28
|
+
'name: "Unconfigured Project Design"',
|
|
29
|
+
'description: "Starter tokens for explicit prototypes only; not an approved production visual system or page-layout target."',
|
|
17
30
|
"colors:",
|
|
18
31
|
' canvas: "#F8FAFC"',
|
|
19
32
|
' surface: "#FFFFFF"',
|
|
@@ -25,22 +38,22 @@ function designMdTemplate() {
|
|
|
25
38
|
' on-primary: "#FFFFFF"',
|
|
26
39
|
"typography:",
|
|
27
40
|
" display:",
|
|
28
|
-
' fontFamily: "
|
|
41
|
+
' fontFamily: "system-ui"',
|
|
29
42
|
' fontSize: "2.5rem"',
|
|
30
43
|
" fontWeight: 700",
|
|
31
44
|
" lineHeight: 1.1",
|
|
32
45
|
" title:",
|
|
33
|
-
' fontFamily: "
|
|
46
|
+
' fontFamily: "system-ui"',
|
|
34
47
|
' fontSize: "1.5rem"',
|
|
35
48
|
" fontWeight: 700",
|
|
36
49
|
" lineHeight: 1.25",
|
|
37
50
|
" body:",
|
|
38
|
-
' fontFamily: "
|
|
51
|
+
' fontFamily: "system-ui"',
|
|
39
52
|
' fontSize: "1rem"',
|
|
40
53
|
" fontWeight: 400",
|
|
41
54
|
" lineHeight: 1.6",
|
|
42
55
|
" label:",
|
|
43
|
-
' fontFamily: "
|
|
56
|
+
' fontFamily: "system-ui"',
|
|
44
57
|
' fontSize: "0.875rem"',
|
|
45
58
|
" fontWeight: 600",
|
|
46
59
|
" lineHeight: 1.3",
|
|
@@ -54,79 +67,59 @@ function designMdTemplate() {
|
|
|
54
67
|
" md: 16px",
|
|
55
68
|
" lg: 24px",
|
|
56
69
|
" xl: 32px",
|
|
57
|
-
"components:",
|
|
58
|
-
" app-shell:",
|
|
59
|
-
' backgroundColor: "{colors.canvas}"',
|
|
60
|
-
' textColor: "{colors.text}"',
|
|
61
|
-
" surface-card:",
|
|
62
|
-
' backgroundColor: "{colors.surface}"',
|
|
63
|
-
' textColor: "{colors.text}"',
|
|
64
|
-
' rounded: "{rounded.md}"',
|
|
65
|
-
" padding: 16px",
|
|
66
|
-
" quiet-control:",
|
|
67
|
-
' backgroundColor: "{colors.surface-muted}"',
|
|
68
|
-
' textColor: "{colors.text-muted}"',
|
|
69
|
-
' rounded: "{rounded.sm}"',
|
|
70
|
-
" padding: 8px",
|
|
71
|
-
" primary-action:",
|
|
72
|
-
' backgroundColor: "{colors.primary}"',
|
|
73
|
-
' textColor: "{colors.on-primary}"',
|
|
74
|
-
' typography: "{typography.label}"',
|
|
75
|
-
' rounded: "{rounded.md}"',
|
|
76
|
-
" padding: 12px",
|
|
77
|
-
" primary-action-hover:",
|
|
78
|
-
' backgroundColor: "{colors.primary-hover}"',
|
|
79
|
-
' textColor: "{colors.on-primary}"',
|
|
80
|
-
' typography: "{typography.label}"',
|
|
81
|
-
' rounded: "{rounded.md}"',
|
|
82
|
-
" padding: 12px",
|
|
70
|
+
"components: {}",
|
|
83
71
|
"---",
|
|
84
72
|
"",
|
|
85
|
-
"# Design
|
|
73
|
+
"# Design Authority",
|
|
86
74
|
"",
|
|
87
75
|
"## Overview",
|
|
88
76
|
"",
|
|
89
|
-
|
|
90
|
-
"-
|
|
91
|
-
"-
|
|
77
|
+
`- ${UNCONFIGURED_DESIGN_AUTHORITY_MARKER}.`,
|
|
78
|
+
"- This file is a non-authoritative scaffold, not an approved brand, component system or page-layout target.",
|
|
79
|
+
"- Material production UI must not use these starter tokens as permission to invent information hierarchy, layout or visual language.",
|
|
80
|
+
"- Replace this status and the provisional tokens only after project-specific visual decisions stabilize.",
|
|
81
|
+
"",
|
|
82
|
+
"### Design Authority Index",
|
|
83
|
+
"",
|
|
84
|
+
"- Authored exact-value token source: not selected.",
|
|
85
|
+
"- Generation direction and generated token targets: not selected.",
|
|
86
|
+
"- Durable design references: none selected.",
|
|
87
|
+
"- For each selected reference, record a stable id, surface/route/component, project path or URI, `exact-target` / `constraint` / `inspiration` interpretation, and the viewport/theme/state conditions it covers.",
|
|
92
88
|
"",
|
|
93
89
|
"## Colors",
|
|
94
90
|
"",
|
|
95
|
-
"-
|
|
96
|
-
"-
|
|
97
|
-
"- Avoid introducing decorative gradients, random accent colors or single-hue palettes unless the product brand explicitly calls for them.",
|
|
91
|
+
"- These colors are provisional accessibility-oriented prototype values only; they are not a project palette or brand decision.",
|
|
92
|
+
"- Replace them from one authored token source before material production styling.",
|
|
98
93
|
"",
|
|
99
94
|
"## Typography",
|
|
100
95
|
"",
|
|
101
|
-
"-
|
|
102
|
-
"-
|
|
96
|
+
"- The system-font typography is provisional prototype scaffolding only.",
|
|
97
|
+
"- Record the selected type family, hierarchy and loading behavior before fidelity implementation.",
|
|
103
98
|
"",
|
|
104
99
|
"## Layout",
|
|
105
100
|
"",
|
|
106
|
-
"-
|
|
107
|
-
"-
|
|
108
|
-
"- On small screens, stack content in priority order and keep primary actions reachable without overlapping other UI.",
|
|
101
|
+
"- This scaffold declares no production page composition, information hierarchy or responsive layout.",
|
|
102
|
+
"- Put durable screen responsibility and interaction structure in `project_context/**`; reference selected visual targets in the Design Authority Index.",
|
|
109
103
|
"",
|
|
110
104
|
"## Components",
|
|
111
105
|
"",
|
|
112
|
-
"-
|
|
113
|
-
"-
|
|
114
|
-
"- Prefer clear affordances, visible focus states and stable dimensions so labels, icons and dynamic text do not resize the layout.",
|
|
106
|
+
"- No production component visual language is selected yet.",
|
|
107
|
+
"- When components are selected, record their visual tokens and relevant default, hover, active, focus, disabled, loading and error states without duplicating an authored code token source.",
|
|
115
108
|
"",
|
|
116
109
|
"## Do's and Don'ts",
|
|
117
110
|
"",
|
|
118
|
-
"- Do
|
|
119
|
-
"- Do
|
|
120
|
-
"- Do
|
|
121
|
-
"- Don't
|
|
122
|
-
"- Don't add generic AI-looking
|
|
111
|
+
"- Do treat `unconfigured` as a stop/routing signal for material production UI, not as visual permission.",
|
|
112
|
+
"- Do classify selected references as `exact-target`, `constraint` or `inspiration` before implementation.",
|
|
113
|
+
"- Do use these tokens only for an explicitly throwaway prototype while authority remains unconfigured.",
|
|
114
|
+
"- Don't promote an implementation screenshot or diff into its own target baseline.",
|
|
115
|
+
"- Don't add generic AI-looking gradients, oversized cards, excessive rounding or decorative blobs without selected design authority.",
|
|
123
116
|
"",
|
|
124
117
|
"## Design Change Workflow",
|
|
125
118
|
"",
|
|
126
|
-
"- Read this file before creating design drafts, redesigning UI, changing visual systems or
|
|
119
|
+
"- Read this file before creating design drafts, redesigning UI, changing visual systems or implementing material production UI.",
|
|
127
120
|
"- When there is a scan target such as UI source, page files, build output or a local/remote URL, run `npx impeccable detect <target>` before finalizing design changes.",
|
|
128
121
|
"- Treat Impeccable findings as design-review signals: fix issues that affect clarity, consistency, accessibility or trust, and note when there is no suitable scan target.",
|
|
129
|
-
"- After design decisions stabilize,
|
|
122
|
+
"- After design decisions stabilize, replace the unconfigured marker, index the selected targets and authored token source/generation direction, and record durable tokens, component rules and do/don't guidance.",
|
|
130
123
|
"",
|
|
131
124
|
].join("\n");
|
|
132
125
|
}
|
package/dist/lib/doctor.js
CHANGED
|
@@ -4,6 +4,7 @@ import os from "node:os";
|
|
|
4
4
|
import { readdir } from "node:fs/promises";
|
|
5
5
|
import { DEFAULT_CONTEXT_FILE_SOFT_BUDGET_BYTES, DEFAULT_CONTEXT_TOTAL_SOFT_BUDGET_BYTES, inspectDefaultContextFootprint, } from "./context-default-footprint.js";
|
|
6
6
|
import { readConfig } from "./config.js";
|
|
7
|
+
import { inspectDesignAuthorityStatus } from "./design-md.js";
|
|
7
8
|
import { harnessConfigPath, harnessRoot } from "./harness-root.js";
|
|
8
9
|
import { pathExists } from "./fs.js";
|
|
9
10
|
import { unsupportedSchemaMessage } from "./schema-guard.js";
|
|
@@ -62,6 +63,13 @@ export async function runDoctor(projectRoot) {
|
|
|
62
63
|
catch (error) {
|
|
63
64
|
report.warnings.push(`default Context footprint unavailable: ${error instanceof Error ? error.message : String(error)}`);
|
|
64
65
|
}
|
|
66
|
+
const designAuthority = await inspectDesignAuthorityStatus(projectRoot);
|
|
67
|
+
if (designAuthority === "unconfigured") {
|
|
68
|
+
report.info.push("design authority: unconfigured; DESIGN.md is a starter scaffold and does not authorize material production UI until project-specific tokens and exact-target/constraint/inspiration references are selected");
|
|
69
|
+
}
|
|
70
|
+
else {
|
|
71
|
+
report.info.push(`design authority: ${designAuthority}`);
|
|
72
|
+
}
|
|
65
73
|
for (const location of await findUserSuperpowersSkills()) {
|
|
66
74
|
report.warnings.push(`user-level using-superpowers Skill detected at ${location}. Tiny Context workflows do not depend on it and doctor will not modify global configuration. To disable it explicitly for Codex, remove/disable that plugin or add a matching [[skills.config]] entry with enabled = false in ${path.join(os.homedir(), ".codex", "config.toml")}.`);
|
|
67
75
|
}
|
|
@@ -3,6 +3,7 @@ import { addDiagnosticError } from "./long-task-authoring-preflight-diagnostics.
|
|
|
3
3
|
import { compileProductClaimCoverage, } from "./long-task-claims.js";
|
|
4
4
|
import { hashDeclaredFiles, validateCounterfactualPaths, validateTechnicalPaths, validateVerificationInputSeparation, } from "./long-task-delivery-preflight.js";
|
|
5
5
|
import { validateClaimEvidenceSensitivity } from "./long-task-evidence-sensitivity-policy.js";
|
|
6
|
+
import { validateSemanticConformance } from "./long-task-conformance-policy.js";
|
|
6
7
|
import { deliveryContractStructureDiagnostics, validateDeliveryContractStructure, } from "./long-task-delivery-validation.js";
|
|
7
8
|
import { validateRawExecutionObservationOwnership } from "./long-task-observation-ownership.js";
|
|
8
9
|
import { freezeDeliveryCheck } from "./long-task-runner-freeze.js";
|
|
@@ -56,7 +57,10 @@ export async function validateContractForActivation(options) {
|
|
|
56
57
|
return emptyCompiledResult(claims, risk, sourceHashes, sourceItems, context);
|
|
57
58
|
const globalChecks = [];
|
|
58
59
|
for (const check of contract.global.acceptance.checks) {
|
|
59
|
-
const
|
|
60
|
+
const executionTarget = contract.task.execution_targets.find((target) => target.key === check.execution_target.target_ref);
|
|
61
|
+
if (!executionTarget)
|
|
62
|
+
continue;
|
|
63
|
+
const frozen = await attempt(mode, diagnostics, () => freezeDeliveryCheck(check, null, repository, workspace, executionTarget, contract.task.execution_targets), null, check.key);
|
|
60
64
|
if (frozen)
|
|
61
65
|
globalChecks.push(frozen);
|
|
62
66
|
}
|
|
@@ -64,7 +68,10 @@ export async function validateContractForActivation(options) {
|
|
|
64
68
|
for (const outcome of contract.outcomes) {
|
|
65
69
|
const checks = [];
|
|
66
70
|
for (const check of outcome.acceptance.checks) {
|
|
67
|
-
const
|
|
71
|
+
const executionTarget = contract.task.execution_targets.find((target) => target.key === check.execution_target.target_ref);
|
|
72
|
+
if (!executionTarget)
|
|
73
|
+
continue;
|
|
74
|
+
const frozen = await attempt(mode, diagnostics, () => freezeDeliveryCheck(check, outcome.key, repository, workspace, executionTarget, contract.task.execution_targets), outcome.key, check.key);
|
|
68
75
|
if (frozen)
|
|
69
76
|
checks.push(frozen);
|
|
70
77
|
}
|
|
@@ -91,6 +98,10 @@ export async function validateContractForActivation(options) {
|
|
|
91
98
|
await attempt(mode, diagnostics, () => validateClaimEvidenceSensitivity(contract, globalChecks, outcomes, mode === "collect"
|
|
92
99
|
? (error) => addDiagnosticError(diagnostics, new Error(error))
|
|
93
100
|
: undefined));
|
|
101
|
+
if (risk)
|
|
102
|
+
await attempt(mode, diagnostics, () => validateSemanticConformance(contract, risk.effective_level, allChecks, mode === "collect"
|
|
103
|
+
? (error) => addDiagnosticError(diagnostics, new Error(error))
|
|
104
|
+
: undefined));
|
|
94
105
|
}
|
|
95
106
|
return {
|
|
96
107
|
claims,
|