mstar-harness: Instructions file for Codex

Morning Star Harness Maintenance

This repository contains the Morning Star runtime skills, workflow engine, CLI, and host plugins. This file defines repository maintenance policy; runtime behavior belongs in skills/mstar-*.

Working rules

• Read the affected source and direct contracts before editing. Fix the demonstrated problem or requested outcome with the smallest complete change; avoid speculative features, compatibility layers, and unrelated refactors.
• Keep each rule in its authoritative topic. Follow harness core for runtime semantics and roles for skill selection; do not duplicate their load matrices, gates, or role procedures here.
• Use tools actually available in the session. Continue authorized work through verification; ask only when a material decision or required authorization remains unresolved. Do not add a separate human approval gate for every diff.
• Respect existing assignments and write ownership. Preserve other contributors' changes; do not reset or clean their work.
• Do not edit user secrets or credential files. Changes to global host configuration or security-sensitive defaults require explicit user authorization.
• No hard block without a way out. Every refusal a user-facing entry can emit must name the actual cause and state the exact recovery the operator can perform through a supported, documented interface — the same entry or another documented one, but never a hidden or manual escape (hand-editing state, undocumented flags, or steps the tooling does not expose). A refusal that leaves the operator with nothing to do, a gate with no paired recovery, and a generic "blocked" message that masks an identifiable cause are all defects. Never add a hard limit without shipping its recovery in the same change, and cover both with a test.
• Fault tolerance and discoverability first for agent-facing operations. All document and content mutations are agent-authored, and agent mistakes are expected, not exceptional. Before any restriction: mutations stay revisable through ordinary public operations (no one-way doors, no hidden manual repair), every parameter is optional except a minimal required set with safe defaults, and commands, parameters, and recovery paths are discoverable from --help and refusal text — an undiscoverable capability does not exist. Principle anchor and audit backlog: #365.
• Test layout. Module-unit suites colocate as src/<module>.test.ts (unit mirror of one module); cross-module behavior suites live in test/. Test-support helpers live with the package that owns them. Engine note: the engine build compiles src/**, so colocated suites are typechecked and their declarations land in dist/.
• Tests derive volatile facts, never pin them. A test that asserts a repository fact — the release version, an inventory of packages/roles/skills or its count, a checkout path — MUST read it from the source that owns it (the manifest, a directory listing, the CLI). A literal is acceptable only as a synthetic fixture input that nothing compares against reality: "4.0.0" as input is fine, version === "4.0.0" is not. This class has been cleaned up across the engine, dsh and CLI suites before and came back, because a one-off cleanup leaves no rule behind. A pinned release version reddens every release branch while main stays green, so ordinary PR CI cannot surface it — derive the value, or the failure lands on whoever prepares the next release.