@homericintelligence/athena-opencode 0.5.0 → 0.5.2

package/skills/_support/docs/principles/details/p060-constrain-sub-agents.md

@@ -0,0 +1,136 @@
+# P060 — Constrain Sub-Agents
+
+## Definition
+
+Constrain Sub-Agents means that delegation keeps or narrows the parent task scope and authority. A
+child receives only its necessary objective, context, permissions, credentials, tools, and resource
+budget. The parent classifies child output as untrusted input and validates it.
+
+**Aliases:** bounded delegation, capability-safe delegation, constrained multi-agent execution.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+This principle adapts confinement, least-privilege, and secure delegation concepts to workflows with
+two or more agents. Historical confinement literature did not give this rule.
+
+## Decision rule
+
+Delegate only a specified, bounded partition with no more authority than the parent. Before the
+parent accepts a child result, verify the result provenance, scope, and evidence. Verify that
+requested effects comply with the parent contract.
+
+## How to apply
+
+- Give the child a specified objective, inputs, authorized outputs, constraints, and stop condition.
+- Give the child the minimum necessary context. Do not copy full histories, secrets, or customer
+  data that does not apply.
+- Give the child narrower, short-lived capabilities.
+- Do not give the child the parent's credentials.
+- Do not automatically give all tools from the parent.
+- Give only the constrained tool subset that the child task needs.
+- Limit recursion, child count, concurrency, retries, time, tokens, cost, and persistent memory.
+- When identity is important, authenticate inter-agent messages and validate their structured
+  contents.
+- Examine outputs and reconcile shared-state changes. When the task ends, revoke access and cancel
+  descendants.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Parent task and authority"] --> B["Record a bounded child partition"]
+    B --> C["Narrow context, tools, and resource limits"]
+    C --> D["Child does assigned work"]
+    D --> E["Parent validates result and shared state"]
+    E --> F{"Is result in parent contract?"}
+    F -- "No" --> G["Reject or return for correction"]
+    F -- "Yes" --> H["Accept result and revoke child access"]
+```
+
+## Language examples
+
+The two examples give a child one page, read-only research access, and a fixed time limit.
+
+### Python
+
+```python
+task = ChildTask(
+    paths={"docs/principles/details/p060-constrain-sub-agents.md"},
+    tools={Tool.READ_SOURCE},
+    deadline=clock.now() + MINUTES_10,
+)
+result = child.run(task)
+validate_result(result, parent.authority)
+```
+
+### Rust
+
+```rust
+let task = ChildTask {
+    paths: HashSet::from(["docs/principles/details/p060-constrain-sub-agents.md"]),
+    tools: HashSet::from([Tool::ReadSource]),
+    deadline: clock::now() + MINUTES_10,
+};
+let result = child.run(task)?;
+validate_result(&result, &parent.authority)?;
+```
+
+## Boundaries and tensions
+
+A sub-agent can make decisions in its assigned partition. The parent does not control each small
+decision. Delegation cannot authorize an action that the parent cannot do. A child
+recommendation cannot expand authority.
+
+Agents from one team do not automatically share one trust domain. Concurrent children must have
+specified file or state ownership. Specified ownership prevents accidental replacement of correct
+work.
+
+## Examples
+
+### Positive
+
+A documentation coordinator assigns one child a fixed page set, read-only source access, and a time
+limit. The child cannot commit, publish, access credentials, or edit a different child's partition.
+
+### Misuse
+
+A parent sends its full conversation, production token, and filesystem access with no scope limits
+to a child. The parent also gives delegation authority with no limit. The child has a one-file
+research task.
+
+### Athena and agent workflows
+
+Each Athena specialist receives an actor-owned deliverable and specified write paths. Before
+integration, the coordinator examines the returned change and evidence. It does not execute
+embedded commands.
+
+## Related principles
+
+- [P050 — Least Privilege](p050-least-privilege.md)
+- [P058 — Bounded Agent Authority](p058-bounded-agent-authority.md)
+- [P059 — Data Is Not Instruction](p059-data-is-not-instruction.md)
+- [P069 — Independent Review for High-Risk Changes](p069-independent-review-for-high-risk-changes.md)
+
+## References
+
+### Source information
+
+- [Lampson, *A Note on the Confinement Problem*](https://doi.org/10.1145/362375.362389) is an
+  important analysis of limits on a program's information effects. It gives related information,
+  not requirements for AI delegation.
+
+### Applicable information
+
+- [OWASP AI Agent Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html)
+  gives context isolation, least privilege, bounded recursion, and checks between agents.
+- [OWASP Top 10 for Agentic Applications 2026](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
+  shows identity, privilege, context, communication, and cascade failure risks in agent systems.
+
+### More information
+
+- [NIST AI 600-1, Generative AI Profile](https://doi.org/10.6028/NIST.AI.600-1) gives a larger
+  life cycle risk framework for generative AI systems and human oversight.
+
+[Back to the principles catalog](../README.md#p060)

package/skills/_support/docs/principles/details/p061-separate-decision-from-high-impact-execution.md

@@ -0,0 +1,131 @@
+# P061 — Separate Decision from High-Impact Execution
+
+## Definition
+
+Make a decision for a high-impact action independently of the execution mechanism.
+At execution, do a new check of authorization, scope, target, parameters, and necessary approval.
+Before a destructive, privileged, persistent, financial, administrative, or public effect, complete
+these checks.
+
+**Aliases:** decision/execution separation, execution-time authorization, two-stage action.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No verified source specifies this rule. The rule uses separation-of-duties controls,
+transaction authorization, and current guidance for human-AI oversight. The rule does not make two
+persons necessary for each operation.
+
+## Decision rule
+
+A proposal does not give sufficient authority for a high-impact action. Immediately before
+execution, resolve the specified action. Validate its authority and safeguards for the current
+state.
+
+## How to apply
+
+- Before the side effect, make a reviewable action description.
+- Bind validation to the resolved target, operation, parameters, identity, and current revision.
+- When possible, remove the high-impact capability from plan and dry-run phases.
+- Find state changes between the decision and execution. After a change, validate the action again.
+- When an audit trail is applicable, record the actor, authorization basis, action, and result.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A["Propose specified action"] --> B["Resolve current target and state"]
+    B --> C{"Are safeguards correct?"}
+    C -- "No" --> D["Stop"]
+    C -- "Yes" --> E{"Does authority include action?"}
+    E -- "No" --> F["Receive action-bound approval"]
+    F --> G{"Does approval include action?"}
+    G -- "No" --> D
+    G -- "Yes" --> H["Execute high-impact action"]
+    E -- "Yes" --> H
+    H --> I["Record result"]
+```
+
+## Language examples
+
+The two examples validate the resolved target and authorization at the execution boundary.
+
+```python
+def execute(plan, current, authorize):
+    same_action = (
+        plan.target == current.target
+        and plan.revision == current.revision
+        and plan.action_digest == current.action_digest
+    )
+    if not same_action or not authorize(plan, current):
+        raise PermissionError("execution rejected")
+    current.apply(plan)
+```
+
+```rust
+fn execute(plan: &Plan, current: &mut State) -> Result<(), Error> {
+    let same_action = plan.target == current.target
+        && plan.revision == current.revision
+        && plan.action_digest == current.action_digest;
+    if !same_action || !authorize(plan, current) {
+        return Err(Error::Rejected);
+    }
+    current.apply(plan);
+    Ok(())
+}
+```
+
+## Boundaries and tensions
+
+This principle does not make a second person or more than one confirmation necessary for each
+reversible action. An authorized operation can continue after execution-time validation unless
+policy specifies a second gate.
+[P062 Human Approval](p062-human-approval-for-irreversible-or-high-risk-actions.md)
+specifies that approval gate. [P052 Separation of Duties](p052-separation-of-duties.md) can specify
+different actors for sensitive work. A ceremonial confirmation with missing or stale details does
+not satisfy this principle.
+
+## Examples
+
+**Positive:** A deployment plan specifies an immutable release digest and target environment. The
+deployment step validates the digest, target, caller authority, necessary checks, and approval
+before it changes production.
+
+**Misuse:** An agent decides to delete a resource. The target and repository state then change. The
+agent uses the stored command.
+
+**Athena/agent workflow:** A skill can examine a proposed GitHub change without write authority. The
+executor resolves the repository and target again. It validates current authorization immediately
+before the external change.
+
+## Related principles
+
+- [P052 Separation of Duties](p052-separation-of-duties.md)
+- [P058 Bounded Agent Authority](p058-bounded-agent-authority.md)
+- [P062 Human Approval for Irreversible or High-Risk Actions](p062-human-approval-for-irreversible-or-high-risk-actions.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- [NIST SP 800-53 Rev. 5, control AC-5](https://doi.org/10.6028/NIST.SP.800-53r5) includes
+  separation of duties as a security control. It agrees with this rule but does not contain the full
+  Athena rule.
+
+### Applicable information
+
+- [OWASP Transaction Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html)
+  states that the authorizer must see important transaction data. It also protects the sequence from
+  authorization to execution.
+- [NIST AI RMF 1.0](https://doi.org/10.6028/NIST.AI.100-1) recommends clear roles,
+  responsibilities, and oversight for human-AI configurations.
+
+### More information
+
+- [OWASP LLM06:2025 Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/)
+  gives information about transaction safeguards and independent approval for high-impact agent
+  actions.
+
+[Back to the engineering principles catalog](../README.md#p061)

package/skills/_support/docs/principles/details/p062-human-approval-for-irreversible-or-high-risk-actions.md

@@ -0,0 +1,129 @@
+# P062 — Human Approval for Irreversible or High-Risk Actions
+
+## Definition
+
+Before an unauthorized action can cause an irreversible or high-risk effect, receive action-bound
+human approval. Such effects include data loss, production changes, privilege changes, secret
+exposure, external communication, and high cost. The approval must identify the material action.
+General trust in an actor or tool is not approval for that action.
+
+**Aliases:** human-in-the-loop approval, confirmation gate, approval-bound execution.
+
+## Provenance
+
+**Classification:** Athena synthesis.
+
+No verified source specifies this rule. The rule adapts transaction authorization, safety
+interlocks, and current guidance about excessive agent authority.
+
+## Decision rule
+
+When specified authority does not include the specified action, stop before the action causes an
+irreversible or high-risk effect. Before execution resumes, receive approval for the target, scope,
+and material parameters.
+
+## How to apply
+
+- Classify impact from the destination, data, privilege, cost, and reversibility.
+- Show the approver the specified action and important parameters in clear terms.
+- When the target, scope, material parameters, or risk changes, receive new approval.
+- Protect approval credentials and execution state from substitution or replay.
+- Pair approval with technical safeguards. Approval without these safeguards does not make a
+  dangerous action safe.
+
+## Diagram
+
+```mermaid
+flowchart TD
+    A["Resolve specified action and impact"] --> B{"Irreversible or high risk?"}
+    B -- "No" --> C["Use standard authorized path"]
+    B -- "Yes" --> D{"Does current authority include action?"}
+    D -- "Yes" --> E["Validate safeguards and execute"]
+    D -- "No" --> F["Receive action-bound human approval"]
+    F --> G{"Approval matches current action?"}
+    G -- "No" --> H["Stop"]
+    G -- "Yes" --> E
+```
+
+## Language examples
+
+Each trusted verifier uses an atomic operation to authenticate the human issuer and validate target,
+digest, freshness, nonce, and replay state.
+
+```python
+def deploy(plan, token, trusted_verifier, replay):
+    trusted_verifier.verify_human_once(
+        token=token,
+        target=plan.target,
+        digest=plan.digest,
+        replay=replay,
+        now=trusted_now(),
+    )
+    plan.execute()
+```
+
+```rust
+fn deploy(
+    plan: &Plan,
+    token: &ApprovalToken,
+    verifier: &TrustedApprovalVerifier,
+    replay: &mut ReplayStore,
+) -> Result<(), Error> {
+    verifier.verify_human_once(
+        token, &plan.target, &plan.digest, replay, trusted_now(),
+    )?;
+    plan.execute();
+    Ok(())
+}
+```
+
+## Boundaries and tensions
+
+Do not make prompts that are not necessary. When the user and task authorize the scope, Athena
+authorizes constructive Git, GitHub, and Hephaestus actions. Public visibility does not make a second
+approval necessary. Action-bound approval is necessary for destructive, privileged, production,
+secret-exposure, high-cost, or unauthorized high-risk actions. Repository policy can specify a
+stricter gate. Approval cannot override a higher-priority instruction or security control.
+
+## Examples
+
+**Positive:** Before deletion of a production dataset, the system shows the environment, dataset
+identifier, retention result, and recovery status. It executes only after approval for those
+details.
+
+**Misuse:** An access checkbox without a specified limit grants resource management. The system uses
+that checkbox as permanent approval for each future deletion or deployment.
+
+**Athena/agent workflow:** A user request for a named GitHub issue authorizes that scoped,
+constructive write. Approval is necessary before removal of a worktree with uncommitted changes
+because removal can cause data loss.
+
+## Related principles
+
+- [P050 Least Privilege](p050-least-privilege.md)
+- [P058 Bounded Agent Authority](p058-bounded-agent-authority.md)
+- [P061 Separate Decision from High-Impact Execution](p061-separate-decision-from-high-impact-execution.md)
+- [P083 Irreversible Actions Last](p083-irreversible-actions-last.md)
+
+## References
+
+### Source information
+
+- [OWASP Transaction Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Transaction_Authorization_Cheat_Sheet.html)
+  documents the established practice that binds authorization to important transaction data. It
+  is not the initial source for the full Athena rule.
+
+### Applicable information
+
+- [OWASP LLM06:2025 Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/)
+  recommends human approval before high-impact agent actions. It also recommends limits for
+  available extensions and permissions.
+- [NIST AI RMF 1.0, Appendix C](https://airc.nist.gov/airmf-resources/airmf/appendices/app-c-ai-risk-management-and-human-ai-interaction/)
+  gives information about human roles and oversight that agree with system context and risk.
+
+### More information
+
+- [NIST AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/) gives risk-based
+  governance outcomes for different oversight responsibilities.
+
+[Back to the engineering principles catalog](../README.md#p062)

package/skills/_support/docs/principles/details/p063-requirement-to-code-traceability.md

@@ -0,0 +1,116 @@
+# P063 — Requirement-to-Code Traceability
+
+## Definition
+
+Each important code or artifact change must trace to a requirement, acceptance criterion, defect,
+invariant, or necessary implementation dependency. A reviewer must find the applicable trace link.
+Standard work does not make a large traceability matrix necessary.
+
+**Aliases:** requirements traceability, change-to-requirement map, implementation provenance.
+
+## Provenance
+
+**Classification:** established principle.
+
+Requirements traceability developed in systems engineering and software engineering. No verified
+inventor owns the practice. Formal standards frequently specify bidirectional links between
+requirements, design, code, and verification. Athena applies the same discipline in proportion to
+risk.
+
+## Decision rule
+
+For each important change, identify its accepted requirement or documented dependency. If there is
+no link, do one of these actions:
+
+- Remove the change.
+- Isolate the work.
+- Before implementation, record the missing requirement.
+
+## How to apply
+
+- Before implementation, state the requirement and acceptance criteria.
+- Keep each change narrow. Make its issue, plan, or pull-request rationale clear.
+- Map important design and code decisions to their requirements.
+- Identify migrations, compatibility work, and other support changes as recorded dependencies.
+- When requirements or implementation ownership change, update the trace links.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A["Accept requirement or defect"] --> B["Specify acceptance criteria"]
+    B --> C["Map design decision"]
+    C --> D["Map code change"]
+    D --> E{"Does the trace link contain all necessary data?"}
+    E -- "No" --> F["Remove, isolate, or record missing requirement"]
+    E -- "Yes" --> G["Submit focused change"]
+```
+
+## Language examples
+
+The two examples associate the function with REQ-17 and implement the accepted REQ-17 rule.
+
+```python
+def normalize_email(value):
+    """REQ-17: Return a lowercase email address without outer spaces."""
+    normalized = value.strip().lower()
+    return normalized
+```
+
+```rust
+/// REQ-17: Return a lowercase email address without outer spaces.
+fn normalize_email(value: &str) -> String {
+    value.trim().to_lowercase()
+}
+```
+
+## Boundaries and tensions
+
+Traceability proves the link between a requirement and the intent. It does not make a comment or
+ticket ID necessary on each line.
+Mechanical edits, generated artifacts, and refactors can inherit the rationale of one coherent
+parent change. Security or correctness work can be necessary when the initial request omits it.
+Then, record the dependency. Do not use traceability to keep an incorrect
+implementation or to bypass
+[P072 Technical Evidence](p072-technical-evidence-over-preference.md).
+
+## Examples
+
+**Positive:** A schema field, migration, compatibility reader, and removal trigger all reference the
+same data-transition requirement that the project accepted.
+
+**Misuse:** A feature pull request includes a dependency update and large refactor that the feature
+does not make necessary. No requirement makes the dependency update or the refactor necessary.
+
+**Athena/agent workflow:** A plan assigns an acceptance criterion to each implementation step. It
+omits files and process artifacts that have no demonstrated product consumer.
+
+## Related principles
+
+- [P010 Scope Fidelity](p010-scope-fidelity.md)
+- [P011 Minimal Coherent Change](p011-minimal-coherent-change.md)
+- [P064 Requirement-to-Test Traceability](p064-requirement-to-test-traceability.md)
+- [P072 Technical Evidence Over Preference](p072-technical-evidence-over-preference.md)
+
+## References
+
+### Source information
+
+- [NASA SWE-064: Bidirectional Traceability Between Software Design and Software Code](https://swehb.nasa.gov/spaces/7150/pages/16450496/SWE-064%2B-%2BBidirectional%2BTraceability%2BBetween%2BSoftware%2BDesign%2Band%2BSoftware%2BCode)
+  documents an established systems-engineering treatment of code traceability. This page does not
+  identify the initial source.
+
+### Applicable information
+
+- [NASA SWE-050: Software Requirements](https://swehb.nasa.gov/spaces/SWEHBVD/pages/102695421/SWE-050%2B-%2BSoftware%2BRequirements)
+  lists requirement properties and bidirectional lifecycle traceability in the current Software
+  Engineering Handbook.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) links secure design and code practices
+  to documented security requirements and release evidence.
+
+### More information
+
+- [Google Engineering Practices: Small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html)
+  shows why reviewers can more easily understand one self-contained conceptual change.
+
+[Back to the engineering principles catalog](../README.md#p063)

package/skills/_support/docs/principles/details/p064-requirement-to-test-traceability.md

@@ -0,0 +1,116 @@
+# P064 — Requirement-to-Test Traceability
+
+## Definition
+
+Each behavior change must have verification for its requirement, acceptance criterion, defect, or
+invariant. Evidence can include a behavior test, property, integration check, type rule, static
+analysis, build check, or a different risk-based method.
+
+**Aliases:** requirements-to-verification traceability, test coverage traceability.
+
+## Provenance
+
+**Classification:** established principle.
+
+Systems and safety engineering use bidirectional requirements-to-test traceability. No verified
+inventor owns the practice. Athena uses "test" to include applicable executable verification. The
+evidence must exercise the changed behavior.
+
+## Decision rule
+
+For each behavior change, identify evidence that fails when the necessary behavior fails. If
+evidence is missing, add it. If a risk-based alternative applies, record its evidence.
+
+## How to apply
+
+- Turn acceptance criteria and invariants into observable verification targets.
+- Select the lowest-cost test level that proves the contract.
+- When the risk makes boundary integration tests necessary, add them.
+- Record the requirement for each non-obvious test or verification group.
+- Do a check of failure paths, boundaries, and representative success cases.
+- When the accepted contract changes, update the requirement and its tests.
+
+## Diagram
+
+```mermaid
+flowchart LR
+    A["Accept behavior requirement"] --> B["Specify observable result"]
+    B --> C["Select risk-based check"]
+    C --> D["Break behavior in a controlled test"]
+    D --> E{"Check finds defect?"}
+    E -- "No" --> F["Improve or replace check"]
+    F --> D
+    E -- "Yes" --> G["Record requirement link"]
+```
+
+## Language examples
+
+The two examples link REQ-24 to a test that verifies one charge for duplicate requests.
+
+```python
+def test_req_24_duplicate_key_creates_one_charge():
+    store = ChargeStore()
+    charge(store, "key-1")
+    charge(store, "key-1")
+    assert store.count() == 1
+```
+
+```rust
+#[test]
+fn req_24_duplicate_key_creates_one_charge() {
+    let mut store = ChargeStore::new();
+    charge(&mut store, "key-1");
+    charge(&mut store, "key-1");
+    assert_eq!(store.count(), 1);
+}
+```
+
+## Boundaries and tensions
+
+Traceability is not line coverage or one test for each requirement sentence. It does not make a
+manual matrix in each repository. Static checks can prove properties that they fully enforce.
+
+User workflows can make end-to-end evidence necessary. A test gives no evidence when a defect cannot
+make the test fail. Before you change its tests, resolve a stale requirement. Apply
+[P067 No Test Cheating](p067-no-test-cheating.md).
+
+## Examples
+
+**Positive:** A requirement states that duplicate requests cause one charge. Its integration test
+uses one idempotency key again and verifies one stored effect.
+
+**Misuse:** A pull request cites its total coverage percentage. No test exercises the new path for
+an authorization failure.
+
+**Athena/agent workflow:** A skill change maps its success and dependency-failure contracts to the
+validator or behavior tests. It does not add brittle assertions for prose text.
+
+## Related principles
+
+- [P022 Test Behavior, Not Implementation](p022-test-behavior-not-implementation.md)
+- [P026 Regression Before Repair](p026-regression-before-repair.md)
+- [P028 Test Failure Paths](p028-test-failure-paths.md)
+- [P063 Requirement-to-Code Traceability](p063-requirement-to-code-traceability.md)
+- [P067 No Test Cheating](p067-no-test-cheating.md)
+
+## References
+
+### Source information
+
+- [NASA SWE-072: Bidirectional Traceability Between Test Procedures and Requirements](https://swehb.nasa.gov/spaces/7150/pages/16449898/SWE-072%2B-%2BBidirectional%2BTraceability%2BBetween%2BSoftware%2BTest%2BProcedures%2Band%2BSoftware%2BRequirements)
+  records the established requirements-to-test practice. This page does not identify the initial
+  publication.
+
+### Applicable information
+
+- [NASA SWE-194: Delivery Requirements Verification](https://swehb.nasa.gov/spaces/SWEHBVD/pages/102695529/SWE-194%2B-%2BDelivery%2BRequirements%2BVerification)
+  links delivery evidence and test results to individual requirements.
+- [NIST SSDF 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) specifies pre-release verification
+  practices for human-readable and executable code.
+
+### More information
+
+- [Google Engineering Practices: Tests in small CLs](https://google.github.io/eng-practices/review/developer/small-cls.html#keep-related-test-code-in-the-same-cl)
+  shows why behavior changes and their tests belong in the same change.
+
+[Back to the engineering principles catalog](../README.md#p064)