Context Artifacts Need Governance
Instruction files, task templates, and Agent profiles can make repository context easier to find. They are not a universal three-layer standard and do not automatically load or override each other. Record the host tool, version, discovery rules, and tested fixtures.
| Artifact | Useful purpose | Not a substitute for |
|---|---|---|
| Instruction | scoped engineering guidance | authorization or secret handling |
| Prompt template | repeatable task framing | test oracle or business policy |
| Agent profile | task-specific context and tools | sandbox or identity boundary |
Build a Verifiable Contract
Each artifact should state scope, evidence, expected checks, and escalation:
## Scope
- Allowed paths: `packages/api/**`
- Escalate before permission or deployment changes.
## Evidence
- Source of truth: `docs/api-contract.md@revision`
- Check: `npm run test:api`
Keep authoritative product policy in owned, versioned systems. Keep secrets in a secret manager. Enforce side effects through server controls, CI, protected branches, approvals, and least-privilege command runners.
Treat Context as Untrusted
Comments, issues, generated files, package metadata, and retrieved documentation can contain instruction injection. Do not let repository text authorize network access, credential use, test bypasses, or destructive changes. Prefer read-only discovery, sandboxed execution, bounded egress, reviewable diffs, and explicit human approval for consequential actions.
Test and Release
Test normal work, conflicting instructions, stale commands, injected instructions, forbidden paths, and missing evidence. Measure correct evidence selection, scope adherence, relevant tests, review quality, and escalation behavior, not obedience to arbitrary wording. Roll out artifact changes reversibly and retain a known-good revision.