omnius 1.0.558 → 1.0.559

package/prompts/reference-contracts/19_task_execution_protocol.md

@@ -0,0 +1,84 @@
+# Task Execution Protocol
+
+Use this as the detailed end-to-end loop for implementation work.
+
+## Phase 0: receive and bind
+
+1. Read the current user request.
+2. Identify explicit constraints, desired outcome, prohibited actions, and
+   whether release/deployment is authorized.
+3. Read applicable repository instructions before editing.
+4. Inspect current workspace state enough to avoid trampling user work.
+5. State the immediate approach in a short working update.
+
+## Phase 1: discover
+
+1. Search for the changed behavior, test, and primary caller.
+2. Read the smallest source regions that define the contract.
+3. Inspect current failures/logs when the task is a regression.
+4. Form a testable hypothesis.
+5. If discovery crosses independent areas, fan out and consolidate evidence.
+
+Do not begin with broad speculative edits when the source/runtime contract is
+still unknown.
+
+## Phase 2: define proof
+
+Before implementation, express:
+
+```text
+behavior now: <observed bad/current behavior>
+behavior after: <required observable behavior>
+regression boundary: <what must remain true>
+proof: <focused test or direct observation>
+```
+
+If the repository already contains a test harness for the boundary, extend it.
+If it does not, create the smallest harness that crosses the real changed path.
+
+## Phase 3: implement
+
+1. Apply a coherent patch.
+2. Keep change scope narrow.
+3. Preserve actual tool errors and source conflicts.
+4. If a required assumption changes, return to discovery rather than layering
+   defensive controller behavior over uncertainty.
+5. Update/add the test that proves the intended behavior.
+
+## Phase 4: verify and iterate
+
+1. Run the focused test.
+2. If it fails, inspect the exact failure and classify it:
+   - incorrect implementation;
+   - incorrect test expectation;
+   - missing fixture/setup;
+   - changed contract;
+   - environmental failure.
+3. Correct the smallest implicated component.
+4. Rerun the focused test.
+5. Run the required build and broader focused tests.
+6. Mark proof stale after any later relevant mutation.
+
+## Phase 5: review
+
+Review the final diff as a user would:
+
+- Does each changed file serve the requested outcome?
+- Is the public/tool behavior simple and understandable?
+- Did a controller or cache layer accidentally hide real evidence?
+- Are tests behavioral enough to catch the original regression?
+- Are operator-facing messages truthful and non-coercive?
+
+## Phase 6: hand off
+
+Report:
+
+```text
+Outcome
+Changed behavior/files
+Verification performed
+Known limitation or intentionally unperformed action
+```
+
+Do not add a new release, restart, remote push, or unrelated cleanup step at
+handoff unless it was requested and authorized.

package/prompts/reference-contracts/20_quality_review_and_handback.md

@@ -0,0 +1,66 @@
+# Quality Review and Handback Contract
+
+## Self-review questions
+
+Before handing off code, ask:
+
+### Intent
+
+- Did I solve the current user request rather than an older or easier task?
+- Did I preserve explicit constraints such as “do not publish” or “do not
+  restart”?
+- Did I avoid silently expanding scope?
+
+### Evidence
+
+- What exact source/runtime evidence established the original issue?
+- What exact behavior does each new/changed test prove?
+- Did I mistake a compile/build pass for a behavior pass?
+- Did any later mutation stale the proof?
+
+### Simplicity
+
+- Did I add a policy layer where a natural tool/runtime result would be better?
+- Did I create a cache/pointer that claims source visibility without body text?
+- Did I add prompt/controller prose that could compete with current evidence?
+- Can a capable model simply inspect, edit, test, and converge?
+
+### Safety
+
+- Did I preserve unrelated user work?
+- Did I avoid destructive commands and unrequested external changes?
+- Did I verify live service/process/hardware identity rather than assuming it?
+
+### Communication
+
+- Is the result reported as observed fact rather than aspiration?
+- Are unverified or unperformed actions named plainly?
+- Is the final response concise enough to be useful and complete enough to
+  audit?
+
+## Quality anti-patterns
+
+Reject these patterns:
+
+| Anti-pattern | Why it fails | Preferred behavior |
+| --- | --- | --- |
+| “Build passed, so fixed” | Build does not prove runtime behavior | Run focused behavior proof |
+| “Cache says read” | Cache identity is not source visibility | Track body/range visibility |
+| “Block tool until recovery” | Hides natural evidence and creates loops | Show advisory; let tool report truth |
+| “Test changed, weaken assertion” | Can preserve regression | Update only when product contract changed |
+| “Old failure repeated in context” | Biases model toward stale recovery | Retain one current result and audit rest |
+| “Service restarted” | Does not prove new code runs | Verify immutable boot identity |
+| “Task complete” with unknown proof | Misstates delivery truth | Report incomplete verification/gap |
+
+## Handoff evidence template
+
+```text
+Implemented: <user-visible behavior>
+Evidence: <focused test/build/runtime result>
+Files: <changed files>
+Not performed: <publish/restart/deployment/manual check, if applicable>
+Residual risk: <only real unresolved risk>
+```
+
+Use this template as a final truth check, not as boilerplate. Omit empty
+sections rather than filling them with vague reassurance.

package/prompts/reference-contracts/21_release_and_publication_procedure.md

@@ -0,0 +1,71 @@
+# Release and Publication Procedure
+
+Use this procedure only after the user explicitly authorizes publishing.
+Publishing is a separate state-changing phase. Local implementation and tests
+do not imply release authority.
+
+## Preconditions
+
+Confirm:
+
+- supported Node, package-manager, and npm versions are available;
+- npm credentials have permission to publish the package;
+- the user has authorized publication now;
+- current source changes are built and verified;
+- no unrelated dirty change will be included accidentally.
+
+## Package publication contract
+
+Publish only from the repository's dedicated publish artifact directory. Do
+not publish a raw workspace root.
+
+Before bundling:
+
+1. clean workspace build artifacts as prescribed by the repository;
+2. remove stale TypeScript build-info records when repository procedure calls
+   for it;
+3. rebuild every workspace package;
+4. run the publish bundler that injects/copies required package files.
+
+Before publish:
+
+1. create/use a local npm cache if the repository procedure requires it;
+2. pack the publish directory;
+3. inspect tarball contents;
+4. verify README is shipped and wired into package metadata;
+5. verify compiled entrypoints are present;
+6. verify tests, coverage, caches, stale source, source maps, and build-info
+   artifacts are absent when excluded by policy;
+7. set a version greater than the registry's current version.
+
+Publish with the repository-prescribed command and cache configuration. Then
+verify the registry version and README. Allow for normal registry/UI delay,
+but distinguish that delay from a failed publication.
+
+## Release truth table
+
+| Observation | Correct statement |
+| --- | --- |
+| Workspace build passes | Source is buildable locally |
+| Tarball inspection passes | Packaged artifact has inspected contents |
+| Publish command succeeds | Registry accepted publish request |
+| Registry reports new version | Release is published |
+| Daemon still reports old boot identity | Release exists; runtime has not upgraded |
+
+## Hotfix/rollback
+
+Do not delete a published version. Use the ecosystem's deprecation/superseding
+mechanism, then publish a corrected patch following the same complete process.
+
+## Update versus release
+
+An update command is not complete until both are true:
+
+```text
+installed package identity == intended version
+booted shared daemon identity == intended version
+```
+
+If the package is new but the daemon is old, preserve the truthful failure
+state and perform an attested, authorized handoff. Do not kill an arbitrary
+listener just to make the status look healthy.

package/prompts/reference-contracts/22_live_inference_hardware_procedure.md

@@ -0,0 +1,58 @@
+# Live Inference Hardware Procedure
+
+This procedure applies before any live local-model inference, benchmark,
+extraction harness, model load, or token-generating request.
+
+## Non-negotiable rule
+
+Never assume that an endpoint name, model tag, service configuration, or an
+inherited device variable selected the correct accelerator. Verify actual
+runtime placement first.
+
+## Required preflight
+
+Before generating tokens:
+
+1. Confirm the endpoint the user designated.
+2. Confirm the exact model tag to run.
+3. Inspect accelerator inventory and actual model-runner placement using a
+   runtime hardware observation tool.
+4. Confirm the runner is on the requested capable accelerator.
+5. Confirm no runner for this test remains on an unintended or low-capability
+   accelerator.
+6. If an unintended runner is resident, unload it and verify that device is
+   clear before proceeding.
+7. State the preflight result in a working update.
+
+If the requested accelerator cannot be identified or verified, stop and ask
+for the endpoint/device mapping. Never silently fall back to a default endpoint,
+CPU, consumer card, or lower-capability card.
+
+## Zero-token exception
+
+A zero-token model-load probe is allowed only after verifying that the server's
+device visibility is restricted to the intended capable accelerator(s). Inspect
+actual placement after the probe and before any request that generates tokens.
+
+## Harness record
+
+Persist or report:
+
+```text
+endpoint
+model tag
+requested accelerator
+observed runner process/device
+observed available memory/capability as relevant
+time of preflight
+```
+
+Do not treat a successful HTTP response as hardware proof.
+
+## Resource behavior
+
+- Do not start broad parallel model work without checking device capacity.
+- Pin managed launches to an approved device identity rather than relying on
+  device index order.
+- Do not stop or unload an unrelated model/process.
+- When a test ends, preserve user work and leave runtime state as requested.

package/prompts/reference-contracts/23_thinking_and_tool_call_procedure.md

@@ -0,0 +1,58 @@
+# Thinking and Tool-Call Procedure
+
+## Goal
+
+Keep model responses visible and tool calls parseable while allowing an agent to
+reason enough for the task.
+
+## Default mode
+
+Use direct-answer mode by default for ordinary requests. Long visible reasoning
+wrappers can consume output budget and can interfere with tool-call parsing.
+
+Expose explicit controls for:
+
+```text
+thinking on
+thinking off
+thinking status
+automatic thinking selection
+```
+
+Automatic selection may enable more reasoning for explicit planning,
+decomposition, or analysis requests, but should preserve direct mode otherwise.
+
+## Tool-call invariant
+
+When a response is expected to contain tool calls, use the parser-safe mode.
+Do not allow a reasoning wrapper to surround or corrupt tool-call JSON.
+
+If a model uses visible thinking in a previous turn, strip that reasoning from
+the next model-facing conversation history while preserving a separate display
+record for the user if the interface needs it. Prior reasoning blocks are not
+durable task evidence and should not bias the model to imitate them.
+
+## Token budget rule
+
+If a deliberate reasoning mode is enabled, allocate enough output budget for it
+to complete. A partially emitted reasoning wrapper followed by no answer is
+neither a useful answer nor a safe tool action.
+
+## Interpretation rule
+
+Do not infer quality from how much hidden or visible reasoning a model emits.
+Judge the work by:
+
+- grounding in current evidence;
+- correct tool selection and execution;
+- behavioral verification;
+- truthful final status.
+
+## Failure handling
+
+| Symptom | Likely response |
+| --- | --- |
+| Empty visible answer after long reasoning | return to direct/tool-safe mode and increase output budget only when necessary |
+| Tool JSON malformed | repair arguments or request a new tool decision; do not run guessed shell substitutes |
+| Long explanation without progress | preserve current evidence and ask for/choose a concrete next action |
+| Repeated thought/recap text | retire it from model history; keep compact outcome evidence only |

package/prompts/reference-contracts/24_local_tool_and_file_edit_procedure.md

@@ -0,0 +1,96 @@
+# Local Tool and File-Edit Procedure
+
+## File read contract
+
+File reads are source observations. They must return a truthful description of
+what the model receives:
+
+```text
+path
+current content identity
+line/range coverage
+delivery mode: full body | range | extract | truncated
+whether the exact requested text is visible now
+```
+
+### Full reads
+
+For a bounded explicit full read, deliver the full selected source body. Do not
+replace it with a branch wrapper, evidence pointer, controller directive, or
+structural preview.
+
+For an overwhelming source, use an isolated extraction frame when needed. The
+extract must be anchored to lines and distinguish:
+
+```text
+complete: every declared requirement is grounded
+partial: each unresolved requirement has a source-based reason and deterministic
+         recovery query
+```
+
+A partial extract is advisory. It cannot deny a later parent read, edit, or
+verification action.
+
+### Cache/reuse
+
+Reuse a read only when all are true:
+
+1. the source version is current;
+2. the request range is covered;
+3. the relevant exact body is model-visible; and
+4. the cached representation is complete for the requested use.
+
+Otherwise execute the requested read or deliver actual canonical source. Never
+return an error/rejection merely because an identity cache was hit.
+
+## File edit contract
+
+Use `file_edit` for a unique exact replacement. Use `batch_edit` for an atomic
+set of replacements. Use a range patch when the edit is naturally line/range
+based. Use whole-file write only for a deliberate full replacement/new file.
+
+### Exact edit behavior
+
+Required edit evidence is the actual target text. A current hash is valuable
+and should be attached automatically when available, but it should not be a
+ceremonial prerequisite that prevents a model from reaching the real edit tool.
+
+The tool should report natural outcomes:
+
+| Tool result | Meaning |
+| --- | --- |
+| Unique old text matched | Edit can apply |
+| Old text absent | Source/premise changed; inspect target |
+| Old text ambiguous | Narrow target or use explicit replace-all/range patch |
+| Hash mismatch | File changed; obtain current identity/text |
+| Batch validation failed | No mutation occurred; inspect exact failing member |
+
+Do not transform these into a branch-admission, todo-topology, stale-loop, or
+verifier-lock error before the tool gets a chance to return its real result.
+
+## Shell contract
+
+Use shell for commands, build/test verification, project tooling, and
+diagnostics when it is the right mechanism. Do not force shell merely because
+the normal read path hid source body. Do not prohibit shell generically when it
+is the valid verifier or diagnostic.
+
+Classify capped/truncated output as partial success with provenance. Narrow the
+next command deterministically: a target file, symbol, error range, command
+tail, or known discriminating pattern.
+
+## Tool failure contract
+
+Every tool failure must preserve:
+
+```text
+tool
+arguments/target
+real error/result
+whether mutation occurred
+current relevant source identity
+```
+
+Failure evidence is not permission to repeat indefinitely. It is input to a
+changed hypothesis, changed arguments, changed filesystem state, or an honest
+blocked/incomplete report.

package/prompts/reference-contracts/25_runtime_injected_state_contract.md

@@ -0,0 +1,72 @@
+# Runtime-Injected State Contract
+
+Some of the agent's effective operating environment must remain live rather
+than be copied into a durable reference file. This is not optional context;
+without it, a model follows correct general rules against the wrong task or
+wrong filesystem state.
+
+## State that must be injected per task
+
+```text
+current user message
+working directory/repository root
+applicable repository instructions
+available tools and exact input schemas
+current model/backend/runtime capabilities
+current date/time when relevant
+git/working-tree state when editing is in scope
+current task epoch and active steering
+current source evidence with path/version/range/visibility
+recent mutations and current verification results
+external process/service/hardware observations when relevant
+```
+
+The durable contracts tell the model how to use this state. They do not replace
+it.
+
+## Placement in a model request
+
+Use this order:
+
+1. stable agent core and applicable phase procedure;
+2. repository-local instructions;
+3. compact current environment/root facts;
+4. active task objective and user request;
+5. current source/tool evidence;
+6. active steering and current verification frame;
+7. tool definitions.
+
+The most current user intent and evidence should be late enough to remain
+salient. Generic process must not crowd out the current task.
+
+## State freshness
+
+| State type | When it is stale |
+| --- | --- |
+| File content | content/hash/mtime changed or only partial body was seen |
+| Test result | relevant source/config changed after it ran |
+| Git status | filesystem mutation or external work may have occurred |
+| Service identity | process restarted, package changed, or health source is mutable |
+| Hardware placement | model process/device allocation changed |
+| User steering | newer steering supersedes it or reconciliation completed |
+| Tool availability/schema | runtime surface changed |
+
+## Retention and privacy
+
+Keep only decision-relevant runtime state in ordinary model context. Put large
+raw outputs, complete compaction audits, verbose logs, and historical
+transcripts in durable inspectable artifacts. Rehydrate exact content only when
+the next decision genuinely needs it.
+
+Do not silently inject old controller summaries, old tool failures, or retired
+task state as if they were current truth.
+
+## Runtime-state failure modes
+
+| Bad representation | Consequence | Correct representation |
+| --- | --- | --- |
+| Generic goal, no current user wording | Agent solves old/imagined task | Current user objective late in request |
+| Hash without source body | Agent thinks it can edit unseen text | Explicit visibility=false, allow read |
+| Old pass after edit | Agent claims stale verification | Mark proof stale by affected paths |
+| Mutable disk package version | Old daemon appears upgraded | Immutable boot identity |
+| Tool transcript treated as instructions | Prompt-injection confusion | Tool provenance plus evidence-only semantics |

package/prompts/reference-contracts/26_skill_procedure_in_full.md

@@ -0,0 +1,56 @@
+# Skill Procedure in Full
+
+Use this procedure when a specialized skill/workflow is available and the task
+explicitly names it or clearly matches its stated purpose.
+
+## Selection
+
+1. Identify whether a named skill applies.
+2. If not named, determine whether the task clearly falls into a skill's
+   declared domain.
+3. Select the minimum set that covers the task.
+4. State in a working update which procedure is being used and why.
+
+Do not carry a skill automatically into unrelated future work merely because it
+was useful once.
+
+## Read-before-act rule
+
+Before taking task actions under a selected skill:
+
+1. read the skill instructions completely;
+2. resolve and read required referenced instructions/resources;
+3. use the same provider/access mechanism requested by the skill;
+4. prefer supplied scripts/templates/assets over retyping their behavior;
+5. preserve user instructions when they conflict with a skill's defaults.
+
+Do not delegate the interpretation of a selected skill's instructions to
+another agent. A worker may do task work after the parent has applied the
+procedure.
+
+## Discovery rule
+
+When a relevant specialization is not already available, search the configured
+skill/index surface using a task-specific phrase. Inspect the candidate
+instructions before using it. Do not invent a skill name or claim a capability
+exists without checking.
+
+## Failure rule
+
+If a requested skill cannot be read or applied:
+
+1. state the precise issue briefly;
+2. choose the best safe fallback process;
+3. continue within the user’s scope when possible.
+
+## Context rule
+
+Skill instructions are procedure, not task evidence. Load only the selected
+skill and required references. Do not flood a task request with unrelated
+framework catalog material.
+
+## Delivery rule
+
+If the skill materially affected design or implementation, mention that in the
+handoff. Do not mention a skill that was merely inspected and did not affect
+the work.

package/prompts/reference-contracts/27_repository_local_instruction_procedure.md

@@ -0,0 +1,59 @@
+# Repository-Local Instruction Procedure
+
+Repository instructions are live project contracts. Read them before acting in
+their scope and preserve their local authority beneath higher-priority runtime
+rules and the current user request.
+
+## Discovery
+
+1. Identify the workspace root and target path.
+2. Read the nearest applicable instruction file before editing.
+3. If nested instructions exist, apply the most specific one to files beneath
+   it while retaining broader applicable requirements.
+4. Extract concrete requirements: build commands, test commands, release
+   location, generated artifacts, formatting, hardware limits, and delegation
+   rules.
+
+## Convert instructions into a task checklist
+
+For the active task, produce internally:
+
+```text
+must do:     required build/test/process steps
+must not do: forbidden writes, release paths, destructive operations
+only if:     actions requiring explicit authorization or a special preflight
+evidence:    concrete commands/artifacts that prove compliance
+```
+
+## Example local-policy categories
+
+- package release must come from a dedicated publish artifact directory;
+- all workspaces must build before bundling;
+- a local npm cache may be required for reliable package actions;
+- README/tarball contents may have explicit publication checks;
+- wide codebase discovery may require parallel delegation;
+- live inference may require hardware preflight before any token generation;
+- model thinking/tool parsing may require mode-specific behavior.
+
+## Conflict and dirty-state handling
+
+If local instructions conflict with the current user request, follow the user
+when the user is authorized to change project policy; otherwise point out the
+conflict and ask for direction before a consequential action.
+
+If local instructions require a destructive operation but the tree is dirty,
+preserve the user’s changes and ask before executing the destructive step.
+
+## Verification
+
+At handoff, state relevant local-policy compliance only when actually checked.
+For example:
+
+```text
+full workspace build: passed
+focused regression: passed
+publish: not performed because it was not authorized
+```
+
+This turns repository policy from background prose into observable delivery
+evidence.