From eab6b83f06ef910df113f4ccaaa0306dcce8b0ff Mon Sep 17 00:00:00 2001 From: Bryan Sayler <207279+bryansayler@users.noreply.github.com> Date: Wed, 14 Oct 2026 05:16:51 -0500 Subject: [PATCH 1/4] docs(governance): preserve scoped Quirk working defaults --- AGENTS.md | 4 ++ docs/governance/WORKING_DEFAULTS.md | 58 +++++++++++++++++++++++++++++ 2 files changed, 62 insertions(+) create mode 100644 docs/governance/WORKING_DEFAULTS.md diff --git a/AGENTS.md b/AGENTS.md index bfeb691..bb2d8b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,6 +87,10 @@ python scripts/validate_evidence_receipts.py --repository Quirk-Systems/.github ## Context Pointers +- For Quirk design, implementation, prompting, execution, or documentation, use + [working defaults](docs/governance/WORKING_DEFAULTS.md) according to scope. + Identify the owning layer and inherit applicable guidance; declare local + differences without duplicating policy or inferring execution authority. - Changing anything about receipts, decisions, or the PR gate: read `docs/governance/EVIDENCE_BINDING.md` first, because the validator's freshness and coverage rules are stricter than they look. diff --git a/docs/governance/WORKING_DEFAULTS.md b/docs/governance/WORKING_DEFAULTS.md new file mode 100644 index 0000000..f16201d --- /dev/null +++ b/docs/governance/WORKING_DEFAULTS.md @@ -0,0 +1,58 @@ +# Quirk working defaults + +Basis: Bryan's direction of 2026-10-14 to persist the Capability Watch recommendations and consider hierarchy throughout Quirk work. This document records that working direction; repository admission, canonical definitions, runtime authorization, and deployment retain their existing owners and gates. It adds no concept IDs or execution grants. + +## Apply according to scope + +Preserve Quirk as a creative medium, capability ecosystem, and participatory world. Apply these defaults across design, building, mapping, implementation, code, creation, prompting, execution, research, learning loops, graphs, worldbuilding, extensions, events, tools, skills, plugins, resources, documentation, plans, notes, and changelogs. A tiny task needs only the relevant part. + +Current explicit instructions and applicable access constraints govern the task. Defaults remain revisable and cannot override higher-priority instructions or another person's choices. Use existing accepted contracts and sources. Do not turn a recommendation, retrieved source, successful check, or installed tool into authority. + +## Hierarchy and relationships + +| Layer | Owns | Child behavior | +| --- | --- | --- | +| Shared Quirk principles | Breadth, protected distinctions, shared working defaults | Inherit applicable principles without redefining canon | +| Domain | Domain meaning, methods, contracts, taste scope | Extend within the domain owner's remit | +| Project or system | Intended outcome, architecture, resources, accepted decisions | Declare parent, dependencies, local constraints | +| Component or capability | One responsibility, inputs, outputs, effects, interface | Inherit project guidance; state meaningful differences only | +| Task or run | Present intent, actor, scope, budget, acceptance evidence | Select relevant context; keep the run's basis traceable | +| Session and artifact | Work state, exact sources, results, unresolved next step | Checkpoint and link corrections; preserve historical originals | + +Hierarchy organizes responsibility and context; it does not grant access. Keep containment/inheritance separate from dependency, provenance, temporal order, extension, and authority relationships. Use the owning model's typed relations; do not create a new taxonomy merely to draw a graph. Allow multiple dependencies or interpretations without inventing multiple authoritative parents. + +For substantial work, identify the owning source, parent, affected consumers, interfaces, and lifecycle. For local differences, record scope, reason, owner, source revision, and reopening condition when relevant. Resolve conflicts with applicable instructions and the actual source owner; recency or hierarchy depth alone does not win. Pause only the affected action when a required conflict cannot be resolved. + +## Prioritize useful work + +Use dependency and consequence before novelty or tool count. The Capability Watch recommendation order is: comparable observations and prior-proposal reconciliation; one coherent integration proof and a bounded command/effect map where needed; one useful capability trial; broader runtime enforcement or market exploration when the chosen work needs it. This is a sequencing default, not a requirement to implement the whole roadmap. + +Explain each recommendation through its evidence, expected benefit, uncertainty, prerequisites, responsible role, required skills/resources, smallest method, completion evidence, and stop or rollback condition. Distinguish a proposed owner from an accepted assignment. Give resource estimates in useful units and label them as estimates; protect human attention alongside time, compute, money, and maintenance. + +Use the existing Work Queue and source artifacts. Add a record only when no existing owner can hold the state. Prefer one bounded outcome, a small work-in-progress limit, and the cheapest observation that could change the decision. Compare against the ordinary workflow when judging improvement. Stop optional tests and analysis once the material uncertainty and required gates are resolved. + +## Evidence and learning + +Preserve raw sources, original expression, exact revisions when available, and transformation lineage. Separate observation, inference, proposal, human preference, process disposition, and outcome. Repeated summaries of one source are one lineage. Unknown, inaccessible, incomplete, untried, deferred, declined, failed, and successful are distinct states; silence is not approval or evidence of value. + +For change detection, compare stable identities within equivalent source, host, account/access, filtering, pagination, and observation contexts. Retain raw and normalized captures with parser version and coverage. Missing or truncated data cannot prove removal. Fingerprint package version, callable surface/schema, descriptions, and effects separately. An unchanged schema cannot guarantee unchanged remote behavior. + +Describe effects concretely: reads, writes, spending, data disclosure, metadata changes, and external consequences. Reuse compatible existing contracts and receipts rather than minting substitutes. Test the disputed behavior, including relevant error, retry, replay, and recovery cases; structural validation proves only what it checked. + +A learning loop needs an observation, bounded hypothesis, baseline, method, measured result, disposition, and wanted reopening condition. Keep process closure separate from evidence: retiring a proposal can leave its outcome UNKNOWN. Preserve alternatives and deliberate creative departures. Human benefit and taste require actual human evidence; quiet participation and private unfinished work remain valid. + +## Continuity and propagation + +Maintain one owning source and small applicable projections. Child assets inherit the parent profile; duplicate a full policy only when an offline consumer needs a versioned export. Keep historical work pinned to its original basis and link corrections or successors. + +At creation, resume, and material change, read the applicable current source, select a coherent revision, inspect local differences and affected dependencies, then update only the affected consumers. Preserve concurrent edits. Record source revision, meaningful change, delivered target, verification, limits, and recovery in the existing artifact or changelog. + +Track authored, persisted, delivered, loaded, behavior-tested, admitted, and deployed separately. A save proves persistence; a prompt update proves configuration; a draft PR proves a reviewable proposal. None establishes universal adoption. Report stale, incompatible, unreachable, or unobserved consumers honestly. + +Scheduled reviews retain separate last-attempt and last-successful state, covered period, source references, coverage, findings, prior-proposal outcomes, and deduplication keys. Retry only on relevant change or an actually missed/failed intended period. An unchanged blocker does not justify repeated alerts. If state cannot be saved, report that limit and do not claim the checkpoint advanced. + +## Change discipline + +Preserve authorization already provided for relevant reversible work. Do not introduce repeated confirmation for the same scope, and do not expand to unrequested publication, spending, external messaging, protected runtime changes, or canonical promotion. + +Use the owning repository's validation and receipt rules. Corrections to these defaults update the source and affected projections, with exact scope and evidence. New systems, tools, skills, plugins, and documents must identify their owner and inherited guidance; they do not each need a new governance system. From 12ccf8f8b0c0d9077a9fae5ae94920f794752b29 Mon Sep 17 00:00:00 2001 From: Bryan Sayler <207279+bryansayler@users.noreply.github.com> Date: Wed, 14 Oct 2026 05:20:54 -0500 Subject: [PATCH 2/4] docs(evidence): bind working defaults to tested subject --- .../working-defaults-eab6b83f06ef.json | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 .quirk/evidence/working-defaults-eab6b83f06ef.json diff --git a/.quirk/evidence/working-defaults-eab6b83f06ef.json b/.quirk/evidence/working-defaults-eab6b83f06ef.json new file mode 100644 index 0000000..649c475 --- /dev/null +++ b/.quirk/evidence/working-defaults-eab6b83f06ef.json @@ -0,0 +1,56 @@ +{ + "schema_version": "evidence-receipt.v1", + "receipt_id": "qreceipt.working-defaults.eab6b83f06ef", + "repository": "Quirk-Systems/.github", + "status": "verified", + "subject": { + "base_commit": "eb889adf3009951de873890103199600f4aad20f", + "commit": "eab6b83f06ef910df113f4ccaaa0306dcce8b0ff", + "changed_paths": [ + "AGENTS.md", + "docs/governance/WORKING_DEFAULTS.md" + ] + }, + "claims": [ + { + "claim_id": "qclaim.working-defaults.eab6b83f06ef", + "claim_type": "evidence", + "authority_effect": "none", + "statement": "Documents user-directed scoped working defaults and links them from AGENTS. Repository validation passed in a normal checkout using its existing configuration; ruff and actionlint were unavailable. No runtime, canonical admission, or universal adoption is established.", + "evidence_paths": [ + "AGENTS.md", + "docs/governance/WORKING_DEFAULTS.md" + ] + } + ], + "artifacts": [ + { + "path": "AGENTS.md", + "state": "present", + "git_blob": "bb2d8b1f7916fde57c0c39ab0e7190a1ef721755", + "sha256": "sha256:4eb99e0512bcd7304ff2f1f54aac694c7232ef397e84b7e12bd60ef75c7343bc" + }, + { + "path": "docs/governance/WORKING_DEFAULTS.md", + "state": "present", + "git_blob": "f16201d9bb746e9ee64f468e169c905df012bcff", + "sha256": "sha256:6af5ed22b44518dec3177bc17d057bdefb2c707605579b02b8188c710e2d7106" + } + ], + "verification": { + "commands": [ + { + "command": "scripts/validate.sh", + "result": "pass", + "exit_code": 0 + } + ], + "verified_at": "2026-10-14T10:20:53Z" + }, + "authority": { + "admission_effect": "none", + "authority_ref": null + }, + "correction": null, + "receipt_sha256": "sha256:af41743d84536523bc67d12e55e2d9bf48f21a1230400e813f9570d2a3adf5ad" +} From ca8a20696020c09800db645c1e24f42d3e010ed4 Mon Sep 17 00:00:00 2001 From: Bryan Sayler <207279+bryansayler@users.noreply.github.com> Date: Fri, 30 Oct 2026 01:42:16 -0500 Subject: [PATCH 3/4] docs(governance): define sufficient work scope and completion --- docs/governance/WORKING_DEFAULTS.md | 30 +++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/governance/WORKING_DEFAULTS.md b/docs/governance/WORKING_DEFAULTS.md index f16201d..113ff36 100644 --- a/docs/governance/WORKING_DEFAULTS.md +++ b/docs/governance/WORKING_DEFAULTS.md @@ -8,6 +8,32 @@ Preserve Quirk as a creative medium, capability ecosystem, and participatory wor Current explicit instructions and applicable access constraints govern the task. Defaults remain revisable and cannot override higher-priority instructions or another person's choices. Use existing accepted contracts and sources. Do not turn a recommendation, retrieved source, successful check, or installed tool into authority. +## Match scope to purpose + +Use outcome-based scope selection to reduce incomplete handoffs and preserve continuity. + +**Choose the scope that can fulfill the purpose. Complete the authorized work with sufficient breadth, depth, integration, and verification. Use small steps where they improve learning or control risk.** + +Separate thinking breadth, execution increments, and completion commitment. An internal step is not automatically a user handoff. Preserve ambition, distinctive expression, humor, and useful uncertainty. Concise reporting does not imply shallow work. + +| Situation | Recognition | Appropriate scope | +| --- | --- | --- | +| Discovery before choosing | The problem, goal, or viable approaches remain unclear. | Explore materially different possibilities and assumptions before selecting. | +| Coupled system design | Decisions affect several components, interfaces, owners, or downstream uses. | Map the relevant whole, resolve dependencies, and implement coherent stages. | +| Complete-loop value | An isolated component cannot deliver the promised benefit. | Complete and verify the integrated path, including applicable failure and recovery behavior. | +| Creative development | Quality depends on cadence, contrast, surprise, emotional development, or an ending. | Develop enough of a passage, performance, scene, or interaction to experience and judge those qualities. | +| Sufficient evidence | A tiny demonstration cannot distinguish the claimed result from chance, missing cases, or short-lived effects. | Match comparison, coverage, sample, and duration to the claim; label unavailable evidence. | +| Authorized routine execution | The outcome is clear and remaining choices are ordinary implementation decisions. | Finish and verify the authorized batch without repeated requests to continue. | +| Consequential change | Effects are difficult to reverse, affect others, or create lasting commitments. | Establish dependencies, alternatives, applicable authority, and recovery before execution. | +| Understanding or experience | The purpose is meaning, reflection, play, or articulating what matters. | Give it room; a clearer understanding or satisfying experience can complete the request without an action item. | + +Repeated candidates, plans, patches, or trials without meaningful progress trigger reassessment of the goal, architecture, or method. Do not manufacture another tiny step to preserve a failing approach. + +Before reducing scope, establish the larger outcome, what the increment resolves, what the narrower scope would lose, and why stopping afterward is appropriate. Continue through ordinary decisions and already-authorized work. Legitimate stopping reasons are completion, a consequential human decision, an agreed resource limit, or a blocker that cannot responsibly be resolved. Explain partial results and preserve a usable resume state. + +Keep explicit requests for one change, a short exercise, read-only inspection, a bounded experiment, or a limited budget intact. Apply the broader reasoning within those limits. Existing grants remain scoped; this preference supplies no new authority to spend, publish, message others, deploy, delete, merge, or promote unrelated work. Do not invent evidence of human benefit or claim universal runtime adoption. + + ## Hierarchy and relationships | Layer | Owns | Child behavior | @@ -27,9 +53,9 @@ For substantial work, identify the owning source, parent, affected consumers, in Use dependency and consequence before novelty or tool count. The Capability Watch recommendation order is: comparable observations and prior-proposal reconciliation; one coherent integration proof and a bounded command/effect map where needed; one useful capability trial; broader runtime enforcement or market exploration when the chosen work needs it. This is a sequencing default, not a requirement to implement the whole roadmap. -Explain each recommendation through its evidence, expected benefit, uncertainty, prerequisites, responsible role, required skills/resources, smallest method, completion evidence, and stop or rollback condition. Distinguish a proposed owner from an accepted assignment. Give resource estimates in useful units and label them as estimates; protect human attention alongside time, compute, money, and maintenance. +Explain each recommendation through its evidence, expected benefit, uncertainty, prerequisites, responsible role, required skills/resources, sufficient method, completion evidence, and stop or rollback condition. Distinguish a proposed owner from an accepted assignment. Give resource estimates in useful units and label them as estimates; protect human attention alongside time, compute, money, and maintenance. -Use the existing Work Queue and source artifacts. Add a record only when no existing owner can hold the state. Prefer one bounded outcome, a small work-in-progress limit, and the cheapest observation that could change the decision. Compare against the ordinary workflow when judging improvement. Stop optional tests and analysis once the material uncertainty and required gates are resolved. +Use the existing Work Queue and source artifacts. Add a record only when no existing owner can hold the state. Choose a coherent completion scope, keep a proportionate work-in-progress limit, and use the cheapest observation sufficient for the disputed claim. The scope exceptions above govern when broader work is required. Compare against the ordinary workflow when judging improvement. Stop optional tests and analysis once the material uncertainty and required gates are resolved. ## Evidence and learning From 35c3a05341de125f6466b663775105cb7307527b Mon Sep 17 00:00:00 2001 From: Bryan Sayler <207279+bryansayler@users.noreply.github.com> Date: Fri, 30 Oct 2026 01:49:58 -0500 Subject: [PATCH 4/4] docs(evidence): bind scope guidance to ca8a20696020 --- .../evidence/purpose-scope-ca8a20696020.json | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 .quirk/evidence/purpose-scope-ca8a20696020.json diff --git a/.quirk/evidence/purpose-scope-ca8a20696020.json b/.quirk/evidence/purpose-scope-ca8a20696020.json new file mode 100644 index 0000000..8c7f47d --- /dev/null +++ b/.quirk/evidence/purpose-scope-ca8a20696020.json @@ -0,0 +1,58 @@ +{ + "schema_version": "evidence-receipt.v1", + "receipt_id": "qreceipt.purpose-scope.ca8a20696020", + "repository": "Quirk-Systems/.github", + "status": "verified", + "subject": { + "base_commit": "12ccf8f8b0c0d9077a9fae5ae94920f794752b29", + "commit": "ca8a20696020c09800db645c1e24f42d3e010ed4", + "changed_paths": [ + "docs/governance/WORKING_DEFAULTS.md" + ] + }, + "claims": [ + { + "claim_id": "qclaim.purpose-scope.ca8a20696020", + "claim_type": "evidence", + "authority_effect": "none", + "statement": "Adds general scope-selection guidance, eight exceptions, explicit limits, and completion criteria. Diff whitespace, agent assets, and existing receipt checks passed. scripts/validate.sh ran 233 tests with one failure caused by an unchanged overdue planning document. Full repository validation, hosted checks, runtime adoption, and human benefit are not established.", + "evidence_paths": [ + "docs/governance/WORKING_DEFAULTS.md" + ] + } + ], + "artifacts": [ + { + "path": "docs/governance/WORKING_DEFAULTS.md", + "state": "present", + "git_blob": "113ff3678ddb0c2b1493aa6b8a16bc0364ac18f1", + "sha256": "sha256:44135e1ecf6eb1dfb45774ddc86db28bf3ac96a97ad78e743f6bbc0decd50426" + } + ], + "verification": { + "commands": [ + { + "command": "git diff --check 12ccf8f8b0c0d9077a9fae5ae94920f794752b29 HEAD", + "result": "pass", + "exit_code": 0 + }, + { + "command": "python3 scripts/validate_agent_assets.py", + "result": "pass", + "exit_code": 0 + }, + { + "command": "python3 scripts/validate_evidence_receipts.py --repository Quirk-Systems/.github --root . --receipts .quirk/evidence", + "result": "pass", + "exit_code": 0 + } + ], + "verified_at": "2026-10-30T06:45:12.159370Z" + }, + "authority": { + "admission_effect": "none", + "authority_ref": null + }, + "correction": null, + "receipt_sha256": "sha256:5105260a36fea3370abe2c49ff19462a0434882a5aac6ab9045f71ba5b79da87" +}