@homericintelligence/athena-opencode 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/README.md +30 -17
  2. package/package.json +2 -2
  3. package/plugin.js +20 -5
  4. package/skills/TECHNICAL_ENGLISH.md +78 -0
  5. package/skills/_cli.py +33 -22
  6. package/skills/_plugin.json +1 -0
  7. package/skills/_support/docs/dependency-resolution.md +203 -0
  8. package/skills/_support/docs/policies/development.md +131 -0
  9. package/skills/_support/docs/policies/evidence-integrity.md +40 -0
  10. package/skills/_support/docs/principles/README.md +565 -0
  11. package/skills/_support/docs/principles/details/p001-kiss.md +114 -0
  12. package/skills/_support/docs/principles/details/p002-yagni.md +109 -0
  13. package/skills/_support/docs/principles/details/p003-dry.md +126 -0
  14. package/skills/_support/docs/principles/details/p004-solid.md +165 -0
  15. package/skills/_support/docs/principles/details/p005-modularity.md +123 -0
  16. package/skills/_support/docs/principles/details/p006-principle-of-least-astonishment.md +115 -0
  17. package/skills/_support/docs/principles/details/p007-subtraction-over-addition.md +113 -0
  18. package/skills/_support/docs/principles/details/p008-understand-before-subtracting.md +115 -0
  19. package/skills/_support/docs/principles/details/p009-general-mechanisms-over-special-cases.md +108 -0
  20. package/skills/_support/docs/principles/details/p010-scope-fidelity.md +117 -0
  21. package/skills/_support/docs/principles/details/p011-minimal-coherent-change.md +128 -0
  22. package/skills/_support/docs/principles/details/p012-evidence-before-modification.md +115 -0
  23. package/skills/_support/docs/principles/details/p013-avoid-hasty-abstractions.md +112 -0
  24. package/skills/_support/docs/principles/details/p014-preserve-unrequested-behavior.md +110 -0
  25. package/skills/_support/docs/principles/details/p015-architecture-conformance.md +124 -0
  26. package/skills/_support/docs/principles/details/p016-separation-of-concerns.md +125 -0
  27. package/skills/_support/docs/principles/details/p017-high-cohesion-low-coupling.md +130 -0
  28. package/skills/_support/docs/principles/details/p018-information-hiding.md +128 -0
  29. package/skills/_support/docs/principles/details/p019-explicit-contracts.md +134 -0
  30. package/skills/_support/docs/principles/details/p020-executable-architecture.md +130 -0
  31. package/skills/_support/docs/principles/details/p021-evolutionary-and-reversible-design.md +126 -0
  32. package/skills/_support/docs/principles/details/p022-test-behavior-not-implementation.md +129 -0
  33. package/skills/_support/docs/principles/details/p023-parameterized-table-driven-testing.md +129 -0
  34. package/skills/_support/docs/principles/details/p024-boundary-value-testing.md +128 -0
  35. package/skills/_support/docs/principles/details/p025-property-based-testing-for-invariants.md +133 -0
  36. package/skills/_support/docs/principles/details/p026-regression-before-repair.md +134 -0
  37. package/skills/_support/docs/principles/details/p027-deterministic-and-hermetic-tests.md +128 -0
  38. package/skills/_support/docs/principles/details/p028-test-failure-paths.md +133 -0
  39. package/skills/_support/docs/principles/details/p029-generalize-error-policy-preserve-specific-cause.md +131 -0
  40. package/skills/_support/docs/principles/details/p030-nearest-responsible-error-boundary.md +133 -0
  41. package/skills/_support/docs/principles/details/p031-propagate-rather-than-swallow.md +131 -0
  42. package/skills/_support/docs/principles/details/p032-handle-once-preserve-causality.md +137 -0
  43. package/skills/_support/docs/principles/details/p033-state-safe-failure-semantics.md +140 -0
  44. package/skills/_support/docs/principles/details/p034-fail-fast.md +132 -0
  45. package/skills/_support/docs/principles/details/p035-fail-secure-fail-closed.md +137 -0
  46. package/skills/_support/docs/principles/details/p036-graceful-degradation.md +137 -0
  47. package/skills/_support/docs/principles/details/p037-idempotency-before-retry.md +139 -0
  48. package/skills/_support/docs/principles/details/p038-bounded-retry.md +145 -0
  49. package/skills/_support/docs/principles/details/p039-bounded-waiting.md +151 -0
  50. package/skills/_support/docs/principles/details/p040-bounded-resources.md +138 -0
  51. package/skills/_support/docs/principles/details/p041-backpressure-and-load-shedding.md +141 -0
  52. package/skills/_support/docs/principles/details/p042-fault-isolation-bulkheads.md +140 -0
  53. package/skills/_support/docs/principles/details/p043-circuit-breakers.md +148 -0
  54. package/skills/_support/docs/principles/details/p044-atomicity-where-possible.md +141 -0
  55. package/skills/_support/docs/principles/details/p045-compensation-where-atomicity-is-impossible.md +163 -0
  56. package/skills/_support/docs/principles/details/p046-resumability.md +138 -0
  57. package/skills/_support/docs/principles/details/p047-observability-is-part-of-correctness.md +134 -0
  58. package/skills/_support/docs/principles/details/p048-secure-by-design.md +132 -0
  59. package/skills/_support/docs/principles/details/p049-secure-by-default.md +126 -0
  60. package/skills/_support/docs/principles/details/p050-least-privilege.md +123 -0
  61. package/skills/_support/docs/principles/details/p051-complete-mediation.md +124 -0
  62. package/skills/_support/docs/principles/details/p052-separation-of-duties.md +129 -0
  63. package/skills/_support/docs/principles/details/p053-validate-at-trust-boundaries.md +126 -0
  64. package/skills/_support/docs/principles/details/p054-defense-in-depth.md +135 -0
  65. package/skills/_support/docs/principles/details/p055-minimize-attack-surface.md +133 -0
  66. package/skills/_support/docs/principles/details/p056-secrets-stay-out-of-code-and-context.md +137 -0
  67. package/skills/_support/docs/principles/details/p057-supply-chain-integrity.md +135 -0
  68. package/skills/_support/docs/principles/details/p058-bounded-agent-authority.md +137 -0
  69. package/skills/_support/docs/principles/details/p059-data-is-not-instruction.md +130 -0
  70. package/skills/_support/docs/principles/details/p060-constrain-sub-agents.md +136 -0
  71. package/skills/_support/docs/principles/details/p061-separate-decision-from-high-impact-execution.md +131 -0
  72. package/skills/_support/docs/principles/details/p062-human-approval-for-irreversible-or-high-risk-actions.md +129 -0
  73. package/skills/_support/docs/principles/details/p063-requirement-to-code-traceability.md +116 -0
  74. package/skills/_support/docs/principles/details/p064-requirement-to-test-traceability.md +116 -0
  75. package/skills/_support/docs/principles/details/p065-verify-before-claiming-completion.md +131 -0
  76. package/skills/_support/docs/principles/details/p066-preserve-existing-work.md +114 -0
  77. package/skills/_support/docs/principles/details/p067-no-test-cheating.md +126 -0
  78. package/skills/_support/docs/principles/details/p068-no-validation-bypass.md +119 -0
  79. package/skills/_support/docs/principles/details/p069-independent-review-for-high-risk-changes.md +129 -0
  80. package/skills/_support/docs/principles/details/p070-code-health-must-not-regress.md +116 -0
  81. package/skills/_support/docs/principles/details/p071-consistency-over-personal-preference.md +117 -0
  82. package/skills/_support/docs/principles/details/p072-technical-evidence-over-preference.md +122 -0
  83. package/skills/_support/docs/principles/details/p073-optimize-only-with-evidence.md +123 -0
  84. package/skills/_support/docs/principles/details/p074-prefer-existing-mechanisms.md +121 -0
  85. package/skills/_support/docs/principles/details/p075-make-invalid-states-hard-to-represent.md +128 -0
  86. package/skills/_support/docs/principles/details/p076-parse-then-validate-then-operate.md +133 -0
  87. package/skills/_support/docs/principles/details/p077-separate-policy-from-mechanism.md +112 -0
  88. package/skills/_support/docs/principles/details/p078-single-source-of-truth.md +131 -0
  89. package/skills/_support/docs/principles/details/p079-explicit-ownership-and-lifetimes.md +124 -0
  90. package/skills/_support/docs/principles/details/p080-make-concurrency-deliberate.md +122 -0
  91. package/skills/_support/docs/principles/details/p081-forward-progress-with-safety.md +125 -0
  92. package/skills/_support/docs/principles/details/p082-design-for-cancellation.md +133 -0
  93. package/skills/_support/docs/principles/details/p083-irreversible-actions-last.md +124 -0
  94. package/skills/_support/docs/principles/details/p084-prefer-local-reasoning.md +131 -0
  95. package/skills/_support/docs/principles/details/p085-explicit-is-better-than-implicit.md +123 -0
  96. package/skills/_support/docs/principles/details/p086-readability-counts.md +113 -0
  97. package/skills/_support/docs/principles/details/p087-comments-explain-why-code-explains-what.md +120 -0
  98. package/skills/_support/docs/principles/details/p088-delete-dead-code.md +125 -0
  99. package/skills/_support/docs/principles/details/p089-delete-obsolete-configuration-and-dependencies.md +125 -0
  100. package/skills/_support/docs/principles/details/p090-prefer-negative-code.md +134 -0
  101. package/skills/_support/docs/principles/details/p091-test-driven-development.md +149 -0
  102. package/skills/_support/docs/review/README.md +63 -0
  103. package/skills/_support/docs/review/behavior-first-testing.md +78 -0
  104. package/skills/_support/docs/review/common.md +400 -0
  105. package/skills/_support/docs/review/design-docs.md +74 -0
  106. package/skills/_support/docs/review/issue-planning.md +247 -0
  107. package/skills/_support/docs/review/language-routing.md +141 -0
  108. package/skills/_support/docs/review/repository-scorecard.md +170 -0
  109. package/skills/advise/SKILL.md +108 -74
  110. package/skills/advise/scripts/list_retrievable_skills.py +20 -8
  111. package/skills/advise/scripts/resolve_knowledge_checkout.py +533 -0
  112. package/skills/brainstorm/SKILL.md +163 -127
  113. package/skills/change-review/SKILL.md +91 -71
  114. package/skills/change-review/references/scope-resolution.md +69 -46
  115. package/skills/change-review/scripts/resolve_scope.py +144 -84
  116. package/skills/finalize-plan/SKILL.md +205 -139
  117. package/skills/git-worktrees/SKILL.md +100 -80
  118. package/skills/git-worktrees/scripts/prepare_worktree.py +34 -15
  119. package/skills/issue-review/SKILL.md +136 -79
  120. package/skills/learn/SKILL.md +359 -192
  121. package/skills/myrmidon-swarm/SKILL.md +126 -86
  122. package/skills/plan-issue/SKILL.md +122 -81
  123. package/skills/pr-review/SKILL.md +184 -116
  124. package/skills/pr-review/references/criteria.md +61 -37
  125. package/skills/pr-review/references/delivery.md +277 -101
  126. package/skills/pr-review/references/evidence.md +346 -149
  127. package/skills/pr-review/references/prevalidated.md +93 -61
  128. package/skills/pr-review/scripts/collect_evidence.py +312 -162
  129. package/skills/pr-review/scripts/deliver_go.py +701 -0
  130. package/skills/pr-review/scripts/diff_context.py +34 -15
  131. package/skills/pr-review/scripts/materialize_snapshot.py +141 -130
  132. package/skills/pr-review/scripts/pr_identity.py +27 -15
  133. package/skills/pr-review/scripts/resolve_pr.py +77 -41
  134. package/skills/realign/SKILL.md +516 -0
  135. package/skills/realign/references/aislop-integration.md +215 -0
  136. package/skills/realign/references/architecture-and-structure.md +271 -0
  137. package/skills/realign/references/control-flow-and-errors.md +344 -0
  138. package/skills/realign/references/tests-dependencies-and-security.md +261 -0
  139. package/skills/realign/scripts/resolve_assessment.py +1525 -0
  140. package/skills/repo-review/SKILL.md +202 -131
  141. package/skills/simplify/SKILL.md +174 -0
  142. package/skills/systematic-debugging/SKILL.md +212 -192
  143. package/skills/systematic-debugging/scripts/repository_evidence.py +26 -8
  144. package/skills/test-driven-development/SKILL.md +126 -96
  145. package/skills/tidy/SKILL.md +104 -59
  146. package/skills/tidy/scripts/run_tidy.py +54 -6
@@ -0,0 +1,163 @@
1
+ # P045 — Compensation Where Atomicity Is Impossible
2
+
3
+ ## Definition
4
+
5
+ If an operation uses different systems or cannot complete in one safe transaction, record each
6
+ completed step. Record its recovery data.
7
+
8
+ If forward work cannot continue, use domain-specific compensation until the system has a
9
+ specified correct state. Use idempotent forward steps. Each compensation step must be a safe step,
10
+ a resumable step, and an idempotent step. Find irreversible effects.
11
+
12
+ **Aliases:** compensating transaction, saga recovery, semantic undo
13
+
14
+ ## Provenance
15
+
16
+ **Classification:** established principle.
17
+
18
+ Garcia-Molina and Salem wrote the 1987 paper that gives the saga model for long-duration
19
+ transactions. Compensation also occurs in other workflow practices. Not all compensation workflows are formal sagas.
20
+
21
+ ## Decision rule
22
+
23
+ When a supported atomic boundary safely contains the operation, use it. If no boundary can contain
24
+ the operation, use durable forward, compensation, reconciliation, and manual recovery paths.
25
+ Before the first side effect, record these paths.
26
+
27
+ ## How to apply
28
+
29
+ - Model the workflow as named steps with durable status, correlation, and ownership.
30
+ - Record the success criteria, idempotency key, compensation step, and retry policy for each step.
31
+ - Before or with each effect, record sufficient context. This context must contain data for recovery
32
+ after a process failure or a response that the system did not receive.
33
+ - Use business invariants to set the compensation sequence. Many workflows use the opposite
34
+ sequence. Some workflows use a different sequence.
35
+ - When the system does compensation again, use a safe compensation step that is also a resumable
36
+ step. Record an observable result.
37
+ - Find each irreversible point. After validation and reversible work, do irreversible steps.
38
+ - Escalate compensation that is not clear or that fails. Include state information and a supported
39
+ manual procedure.
40
+
41
+ ## Diagram
42
+
43
+ ```mermaid
44
+ flowchart TD
45
+ A["Record workflow context"] --> B["Do one idempotent forward step"]
46
+ B --> C["Record the completed step"]
47
+ C --> D{"Did the workflow complete all forward steps?"}
48
+ D -- Yes --> E["Record success"]
49
+ D -- No --> F{"Can forward work continue?"}
50
+ F -- Yes --> B
51
+ F -- No --> G["Select compensation from durable state"]
52
+ G --> H["Do idempotent compensation"]
53
+ H --> I{"Did compensation succeed?"}
54
+ I -- Yes --> J["Record a correct business-equivalent state"]
55
+ I -- No --> K["Record recovery-required state and error context"]
56
+ ```
57
+
58
+ ## Language examples
59
+
60
+ The examples use equivalent confirmation, failure, cancellation, and recovery-required outcomes.
61
+
62
+ ### Python
63
+
64
+ ```python
65
+ def book_trip(workflow) -> Outcome:
66
+ flight = workflow.step("flight", reserve_flight, cancel_flight)
67
+ if flight.is_error:
68
+ return Outcome.failed(flight.error)
69
+ hotel = workflow.step("hotel", reserve_hotel, cancel_hotel)
70
+ if not hotel.is_error:
71
+ return Outcome.confirmed()
72
+ compensation = workflow.compensate()
73
+ if compensation.is_error:
74
+ context = workflow.recovery_context()
75
+ return Outcome.recovery_required(hotel.error, compensation.error, context)
76
+ return Outcome.canceled(hotel.error)
77
+ ```
78
+
79
+ ### Rust
80
+
81
+ ```rust
82
+ fn book_trip(workflow: &mut Workflow) -> Outcome {
83
+ let flight = workflow.step("flight", reserve_flight, cancel_flight);
84
+ if let Err(error) = flight {
85
+ return Outcome::failed(error);
86
+ }
87
+ let hotel = workflow.step("hotel", reserve_hotel, cancel_hotel);
88
+ let Err(original) = hotel else { return Outcome::confirmed() };
89
+ match workflow.compensate() {
90
+ Ok(()) => Outcome::canceled(original),
91
+ Err(error) => Outcome::recovery_required(original, error, workflow.recovery_context()),
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## Boundaries and tensions
97
+
98
+ After compensation, the state can be different from the previous state. Concurrent work can cause
99
+ an incorrect state before compensation. The correct result is a specified business-equivalent state.
100
+
101
+ For example, a refund does not remove the historical charge from records.
102
+
103
+ When [P044](p044-atomicity-where-possible.md) gives a supported transaction with less complexity,
104
+ do not use compensation. If effects operate independently, do not identify them as one atomic operation.
105
+
106
+ Each retry must satisfy [P037](p037-idempotency-before-retry.md). Each between-step workflow state
107
+ must satisfy [P033](p033-state-safe-failure-semantics.md).
108
+
109
+ ## Examples
110
+
111
+ ### Positive application
112
+
113
+ A travel workflow records flight and hotel reservations as two durable steps. The hotel
114
+ reservation fails, and there is no approved alternative.
115
+
116
+ The workflow sends idempotent cancellation commands for completed reservations. It records each
117
+ compensation result for resumption.
118
+
119
+ ### Misuse or counterexample
120
+
121
+ A workflow calls three services. After the third call fails, it sends non-durable “undo” calls from
122
+ memory. After a process failure, the workflow has no completed-step record.
123
+
124
+ More than one compensation call can cause new side effects.
125
+
126
+ ### Athena or agent workflow
127
+
128
+ Before a multistep public workflow, Athena records reversible steps and steps with specified
129
+ approval requirements. If a step fails after approved effects occur, Athena records completed effects.
130
+
131
+ It uses only approved compensation that it specified before failure. It does not add a destructive
132
+ cleanup step during the failure.
133
+
134
+ ## Related principles
135
+
136
+ - [P033 — State-Safe Failure Semantics](p033-state-safe-failure-semantics.md)
137
+ - [P037 — Idempotency Before Retry](p037-idempotency-before-retry.md)
138
+ - [P044 — Atomicity Where Possible](p044-atomicity-where-possible.md)
139
+ - [P046 — Resumability](p046-resumability.md)
140
+
141
+ ## References
142
+
143
+ ### Source information
144
+
145
+ - [Garcia-Molina and Salem, “Sagas” (1987)](https://doi.org/10.1145/38714.38742)
146
+ — a paper that models a long-duration transaction as a sequence. Compensation transactions
147
+ repair execution of only some steps.
148
+
149
+ ### Applicable information
150
+
151
+ - [Microsoft Azure, Compensating Transaction pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction)
152
+ — applicable guidance for durable completed-step data, application-specific reversal, idempotent
153
+ compensation, concurrency, and irreversible points.
154
+ - [AWS Prescriptive Guidance, Saga patterns](https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/saga-patterns.html)
155
+ — applicable guidance for forward recovery, recovery in the opposite sequence, choreography,
156
+ and orchestration.
157
+
158
+ ### More information
159
+
160
+ - [Microsoft Azure, Design for self-healing](https://learn.microsoft.com/en-us/azure/architecture/guide/design-principles/self-healing)
161
+ — connects compensation with checkpoints, recovery, and resumable long-duration work.
162
+
163
+ [Back to the engineering principles catalog](../README.md#p045)
@@ -0,0 +1,138 @@
1
+ # P046 — Resumability
2
+
3
+ ## Definition
4
+
5
+ Resumability lets an interrupted long operation continue from durable, verified progress. The saved
6
+ checkpoint records committed work, uncommitted work, and work with an uncertain result.
7
+
8
+ **Aliases:** checkpoint/restart, durable progress, restartable workflow.
9
+
10
+ ## Provenance
11
+
12
+ **Classification:** established principle.
13
+
14
+ Engineers applied checkpoint and restart methods before workflow engines. Subsequent systems applied
15
+ these methods to durable application milestones and operation resources, not only process state.
16
+ No one source gives the full principle.
17
+
18
+ ## Decision rule
19
+
20
+ If an interruption can occur, examine restart cost and safety. If restart has high cost or is not
21
+ safe, record progress at correct recovery boundaries. If token data does not agree with the operation
22
+ identity or position is not in range, reject the resume token. If token data agrees with the
23
+ operation identity and position is in range, accept the token. Do not let completed work cause
24
+ effects again.
25
+
26
+ ## How to apply
27
+
28
+ - Give the operation a stable identity. Classify terminal, retryable, and indeterminate states.
29
+ - After the related state transition has a durable commit, save a checkpoint.
30
+ - Record version, input, and owner data that shows stale or incompatible checkpoints.
31
+ - Each resumed step must be idempotent. If a step is not idempotent, deduplicate it or reconcile it
32
+ with authoritative state.
33
+ - Give progress and failure reports. Record checkpoint retention and removal rules.
34
+ - Do tests before, during, and after each external effect.
35
+
36
+ ## Diagram
37
+
38
+ ```mermaid
39
+ flowchart TD
40
+ A["Receive operation and checkpoint"] --> B{"Is a checkpoint available?"}
41
+ B -- "No" --> C["Start from a safe initial state"]
42
+ B -- "Yes" --> D{"Operation identity correct and position in range?"}
43
+ D -- "No" --> E["Reject the resume request"]
44
+ D -- "Yes" --> F["Reconcile the last recorded effect"]
45
+ C --> G["Do the next idempotent step"]
46
+ F --> G
47
+ G --> H["Commit the state transition"]
48
+ H --> I["Save the next checkpoint"]
49
+ ```
50
+
51
+ ## Language examples
52
+
53
+ The two examples bind checkpoints to operation, input, owner, and schema identity, apply each batch
54
+ one time, and save only committed progress.
55
+
56
+ ### Python
57
+
58
+ ```python
59
+ def resume(checkpoint: Checkpoint | None, batches, operation):
60
+ identity = (operation.id, operation.input_digest, operation.owner_id, operation.schema_version)
61
+ start = verify_checkpoint(checkpoint, identity, len(batches))
62
+ for position, batch in enumerate(batches[start:], start=start):
63
+ apply_once(batch.id, batch.items)
64
+ save_checkpoint(identity, position + 1)
65
+ ```
66
+
67
+ ### Rust
68
+
69
+ ```rust
70
+ fn resume(checkpoint: Option<&Checkpoint>, batches: &[Batch], operation: &Operation) -> Result<(), Error> {
71
+ let identity = ResumeIdentity::new(
72
+ &operation.id, &operation.input_digest, &operation.owner_id, operation.schema_version);
73
+ let start = verify_checkpoint(checkpoint, &identity, batches.len())?;
74
+ for (offset, batch) in batches[start..].iter().enumerate() {
75
+ apply_once(batch.id, &batch.items)?;
76
+ save_checkpoint(&identity, start + offset + 1)?;
77
+ }
78
+ Ok(())
79
+ }
80
+ ```
81
+
82
+ ## Boundaries and tensions
83
+
84
+ Resumability is not an automatic retry without a check. A checkpoint can keep corrupt or obsolete
85
+ state. Before the system accepts a checkpoint, validate checkpoint integrity and compatibility.
86
+
87
+ A restart can be correct for a short, low-cost operation without side effects. If one boundary can
88
+ contain the operation, use an atomic transaction. Distributed work can make compensation necessary.
89
+
90
+ A resumed operation must use authority that applies at resume time. It must not use expired
91
+ credentials or approvals again.
92
+
93
+ ## Examples
94
+
95
+ ### Positive
96
+
97
+ A migration records the committed position, schema version, input digest, and operation ID. After
98
+ an interruption, it verifies those fields and reconciles the batch at the saved position. It then
99
+ continues at the saved position.
100
+
101
+ ### Misuse
102
+
103
+ A worker stores only `step = 4`. It stops after a payment but before the next checkpoint. A restart
104
+ sends the payment again because the checkpoint does not record the uncertain effect.
105
+
106
+ ### Athena and agent workflows
107
+
108
+ A coordinator records completed task IDs, accepted artifact hashes, and dependencies that are not
109
+ satisfied. After a host interruption, it validates the checkout again. It resumes only tasks that
110
+ are not completed.
111
+
112
+ ## Related principles
113
+
114
+ - [P044 — Atomicity Where Possible](p044-atomicity-where-possible.md)
115
+ - [P045 — Compensation Where Atomicity Is Impossible](p045-compensation-where-atomicity-is-impossible.md)
116
+ - [P047 — Observability Is Part of Correctness](p047-observability-is-part-of-correctness.md)
117
+ - [P053 — Validate at Trust Boundaries](p053-validate-at-trust-boundaries.md)
118
+
119
+ ## References
120
+
121
+ ### Source information
122
+
123
+ - [USENIX: *Libckpt: Transparent Checkpointing under UNIX* (1995)](https://www.usenix.org/conference/usenix-1995-technical-conference/libckpt-transparent-checkpointing-under-unix)
124
+ gives information about checkpoint and restart methods for interrupted long computations.
125
+
126
+ ### Applicable information
127
+
128
+ - [Google AIP-151: Long-running operations](https://google.aip.dev/151) gives a durable operation
129
+ resource that lets clients monitor progress and retrieve a result.
130
+ - [AWS Step Functions redrive guidance](https://docs.aws.amazon.com/step-functions/latest/dg/redrive-executions.html)
131
+ gives information about restart from workflow steps with failures and retention of results.
132
+
133
+ ### More information
134
+
135
+ - [USENIX: *Transparent Checkpoint-Restart of Multiple Processes*](https://www.usenix.org/legacy/event/usenix07/tech/full_papers/laadan/laadan_html/paper.html)
136
+ gives consistency requirements for checkpoints in cooperative processes with shared state.
137
+
138
+ [Back to the principles catalog](../README.md#p046)
@@ -0,0 +1,134 @@
1
+ # P047 — Observability Is Part of Correctness
2
+
3
+ ## Definition
4
+
5
+ Observability lets operators use structured logs, metrics, and traces to find system state and
6
+ operation outcomes. When operators must find failure, find completed work and work not completed,
7
+ and restore service safely, observability is part of correctness.
8
+
9
+ **Aliases:** operational diagnosability, production visibility, telemetry-by-design.
10
+
11
+ ## Provenance
12
+
13
+ **Classification:** Athena synthesis.
14
+
15
+ Observability practice is evidence for this synthesis. Distributed tracing and
16
+ production monitoring have long histories. No one source gives this Athena rule.
17
+
18
+ ## Decision rule
19
+
20
+ For important behavior, emit sufficient correlated and non-sensitive evidence that shows the event,
21
+ location, time, operation, and cause. If operators cannot find an important failure in the specified
22
+ response period, the operational contract does not have sufficient information.
23
+
24
+ ## How to apply
25
+
26
+ - Select signals from user outcomes and operational questions. Do not select signals only
27
+ because data is available.
28
+ - Use stable request, trace, or operation identifiers to correlate work at all boundaries.
29
+ - Record structured status, reason, duration, and dependency context at the responsible boundary.
30
+ - Use metrics for trends and alerting, traces for causal paths, and logs for discrete evidence.
31
+ - Before production starts, set data retention, sampling, cardinality, access, and redaction
32
+ policies.
33
+ - Do telemetry tests for important success, failure, cancellation, completed work, and work not
34
+ completed.
35
+
36
+ ## Diagram
37
+
38
+ ```mermaid
39
+ flowchart LR
40
+ A["Important operation"] --> B["Emit correlated safe signals"]
41
+ B --> C["Logs record discrete evidence"]
42
+ B --> D["Metrics show trends and alerts"]
43
+ B --> E["Traces show causal paths"]
44
+ C --> F["Find the outcome and cause"]
45
+ D --> F
46
+ E --> F
47
+ ```
48
+
49
+ ## Language examples
50
+
51
+ The two examples record a duration metric and a structured outcome event that contains the request
52
+ identifier.
53
+
54
+ ### Python
55
+
56
+ ```python
57
+ def transfer(request_id, amount):
58
+ started = clock.now()
59
+ result = ledger.try_transfer(amount)
60
+ metrics.observe("transfer_ms", clock.now() - started)
61
+ log.info("transfer_complete", request_id=request_id, status=result.status)
62
+ return result
63
+ ```
64
+
65
+ ### Rust
66
+
67
+ ```rust
68
+ fn transfer(request_id: &str, amount: Money) -> Result<Receipt, Error> {
69
+ let started = clock::now();
70
+ let result = ledger::try_transfer(amount);
71
+ let status = match &result {
72
+ Ok(_) => "ok",
73
+ Err(_) => "error",
74
+ };
75
+ metrics::observe("transfer_ms", clock::now() - started);
76
+ log::info("transfer_complete", request_id, status);
77
+ result
78
+ }
79
+ ```
80
+
81
+ ## Boundaries and tensions
82
+
83
+ Telemetry cannot correct incorrect behavior. High signal volume is not observability. A large signal
84
+ volume or high cardinality can prevent incident detection and can consume all resources.
85
+
86
+ Logs are a data store and an attack surface. Do not emit secrets for diagnosis. Use safe identifiers
87
+ that do not contain raw customer content. Samples must keep evidence for important security and
88
+ failure events.
89
+
90
+ ## Examples
91
+
92
+ ### Positive
93
+
94
+ One trace ID identifies a request in all services. Each boundary records a structured outcome and
95
+ latency. Dashboards report errors that users see. Traces show the dependency with the failure.
96
+
97
+ ### Misuse
98
+
99
+ A service writes free-form debug messages that contain access tokens. It has no request correlation,
100
+ outcome metric, or alert. The messages are not safe and cannot give a clear diagnosis.
101
+
102
+ ### Athena and agent workflows
103
+
104
+ A delegated task reports its task ID, bounded outcome, validation evidence, and specified failure
105
+ reason.
106
+ The report does not contain credentials or file content that does not apply. The coordinator can
107
+ find a completed task, a timed-out task, or a task that stopped before all work ended.
108
+
109
+ ## Related principles
110
+
111
+ - [P046 — Resumability](p046-resumability.md)
112
+ - [P053 — Validate at Trust Boundaries](p053-validate-at-trust-boundaries.md)
113
+ - [P056 — Secrets Stay Out of Code and Context](p056-secrets-stay-out-of-code-and-context.md)
114
+
115
+ ## References
116
+
117
+ ### Source information
118
+
119
+ - [Google Research: *Dapper, a Large-Scale Distributed Systems Tracing Infrastructure*](https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/)
120
+ gives an important production trace design and its diagnostic goals.
121
+
122
+ ### Applicable information
123
+
124
+ - [OpenTelemetry observability primer](https://opentelemetry.io/docs/concepts/observability-primer/)
125
+ gives information about logs, metrics, traces, correlation, and service reliability.
126
+ - [OpenTelemetry Specification 1.60.0](https://opentelemetry.io/docs/specs/otel/) gives
127
+ vendor-neutral telemetry and instrumentation contracts.
128
+
129
+ ### More information
130
+
131
+ - [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)
132
+ gives information about event design, sanitization, sensitive data exclusion, and log protection.
133
+
134
+ [Back to the principles catalog](../README.md#p047)
@@ -0,0 +1,132 @@
1
+ # P048 — Secure by Design
2
+
3
+ ## Definition
4
+
5
+ Secure by Design makes security a requirement for architecture, implementation, delivery, and
6
+ operation from the start. Each design includes controls for threats to trust boundaries, data flows,
7
+ privileges, dependencies, and execution capabilities.
8
+
9
+ **Aliases:** security by design, built-in security, security during the full life cycle.
10
+
11
+ ## Provenance
12
+
13
+ **Classification:** established principle.
14
+
15
+ Security design principles have a long history. Standards organizations and public security agencies
16
+ give the *Secure by Design* formulation in software life cycle guidance.
17
+
18
+ ## Decision rule
19
+
20
+ Before a capability changes trust, record the assets, actors, and boundaries. Then find the threats,
21
+ failure modes, and necessary controls. Before the cost of changes is high, make the controls part of
22
+ the architecture and acceptance criteria.
23
+
24
+ ## How to apply
25
+
26
+ - Classify protected assets. Map each new or changed trust boundary and data flow.
27
+ - Model threats to entry points, identities, privileges, dependencies, and abuse cases.
28
+ - Select safe contracts, isolation, validation, and authorization before implementation details.
29
+ - Include security tests, evidence, operational data, update paths, and incident response in
30
+ delivery.
31
+ - If permissions, integrations, dependencies, or operational assumptions change, do the threat
32
+ model again.
33
+ - Give the product owner responsibility for security outcomes. Do not give all risk to users.
34
+
35
+ ## Diagram
36
+
37
+ ```mermaid
38
+ flowchart TD
39
+ A["New capability"] --> B["Record assets and actors"]
40
+ B --> C["Map trust boundaries and find threats"]
41
+ C --> D["Select architecture controls"]
42
+ D --> E["Give security acceptance criteria"]
43
+ E --> F["Implement and verify"]
44
+ F --> G{"Threat model changed?"}
45
+ G -- "Yes" --> B
46
+ G -- "No" --> H["Operate with evidence"]
47
+ ```
48
+
49
+ ## Language examples
50
+
51
+ The two examples verify a signature for the canonical body and nonce before replay checks,
52
+ validation, authorization, and queue insertion.
53
+
54
+ ### Python
55
+
56
+ ```python
57
+ def accept_webhook(request):
58
+ signed = canonicalize(request.body, request.nonce)
59
+ sender = verify_signature(request.signature, signed)
60
+ reject_replay(request.nonce)
61
+ event = validate_payload(request.body)
62
+ authorize(sender, event.tenant)
63
+ queue.put(AuthenticatedEvent(sender, event))
64
+ ```
65
+
66
+ ### Rust
67
+
68
+ ```rust
69
+ fn accept_webhook(request: Request) -> Result<(), Error> {
70
+ let signed = canonicalize(&request.body, &request.nonce);
71
+ let sender = verify_signature(&request.signature, &signed)?;
72
+ reject_replay(&request.nonce)?;
73
+ let event = validate_payload(&request.body)?;
74
+ authorize(&sender, &event.tenant)?;
75
+ queue::put(AuthenticatedEvent::new(sender, event))
76
+ }
77
+ ```
78
+
79
+ ## Boundaries and tensions
80
+
81
+ Secure by Design does not mean that all locations must have maximum controls. Controls must be
82
+ correct for the assets, threats, and impact. Controls must not prevent necessary operations.
83
+
84
+ Compliance evidence cannot replace threat analysis. Penetration tests after implementation can find
85
+ security defects. They cannot repair a trust model that is not safe at low cost. This principle
86
+ applies to the full life cycle. Secure by Default applies to the initial product configuration.
87
+
88
+ ## Examples
89
+
90
+ ### Positive
91
+
92
+ Before implementation, a new webhook integration has requirements for authenticated senders,
93
+ replay resistance, payload limits, secret rotation, failure control, and audit events.
94
+
95
+ ### Misuse
96
+
97
+ A team ships an administrative API with more credentials than necessary. After customers start to
98
+ use the API, the team plans authorization and audit logs.
99
+
100
+ ### Athena and agent workflows
101
+
102
+ Before a new tool becomes available, an Athena workflow records the data, calls, authority, output
103
+ checks, and failure reports for that tool.
104
+
105
+ ## Related principles
106
+
107
+ - [P049 — Secure by Default](p049-secure-by-default.md)
108
+ - [P050 — Least Privilege](p050-least-privilege.md)
109
+ - [P053 — Validate at Trust Boundaries](p053-validate-at-trust-boundaries.md)
110
+ - [P054 — Defense in Depth](p054-defense-in-depth.md)
111
+
112
+ ## References
113
+
114
+ ### Source information
115
+
116
+ - [Saltzer and Schroeder, *The Protection of Information in Computer Systems*](https://doi.org/10.1109/PROC.1975.9939)
117
+ is a primary source for secure system design principles. It was published before the *Secure by
118
+ Design* term.
119
+
120
+ ### Applicable information
121
+
122
+ - [CISA, *Shifting the Balance of Cybersecurity Risk*](https://www.cisa.gov/sites/default/files/2023-06/principles_approaches_for_security-by-design-default_508c.pdf)
123
+ gives Secure by Design and Secure by Default expectations for software producers.
124
+ - [NIST SP 800-218, SSDF Version 1.1](https://doi.org/10.6028/NIST.SP.800-218) gives secure
125
+ practices during the full life cycle for software development.
126
+
127
+ ### More information
128
+
129
+ - [CISA Secure by Demand Guide](https://www.cisa.gov/sites/default/files/2024-08/SecureByDemandGuide_080624_508c.pdf)
130
+ gives software customers questions to examine producer security practices.
131
+
132
+ [Back to the principles catalog](../README.md#p048)
@@ -0,0 +1,126 @@
1
+ # P049 — Secure by Default
2
+
3
+ ## Definition
4
+
5
+ Secure by Default means that the initial configuration and easiest supported path give sufficient
6
+ protection. Users can use necessary controls without an activation step. A user must make a clear
7
+ selection to use a weaker configuration.
8
+
9
+ **Aliases:** safe defaults, security out of the box, default-deny configuration.
10
+
11
+ ## Provenance
12
+
13
+ **Classification:** established principle.
14
+
15
+ Fail-safe defaults came before this principle. CISA guidance gives a product-level formulation. The
16
+ two formulations are related, but they are different.
17
+
18
+ ## Decision rule
19
+
20
+ Select defaults that decrease possible damage for a new installation. Apply these defaults to
21
+ authentication, authorization, network exposure, data protection, and telemetry. If an insecure
22
+ compatibility mode is necessary, give clear risk information and a different activation step.
23
+
24
+ ## How to apply
25
+
26
+ - After a user or policy records permissions, grant the permissions. Do not ship access that users
27
+ must remove.
28
+ - Disable endpoints, accounts, tools, and network listeners that are not necessary.
29
+ - Use secure protocol, cryptographic, privacy, and update settings as defaults.
30
+ - Make high-risk configuration changes clear, auditable, and reversible.
31
+ - Do tests with a clean installation and the primary initial path. Do not do tests only with an
32
+ expert configuration.
33
+ - Give migration guidance for stronger defaults in installed systems.
34
+
35
+ ## Diagram
36
+
37
+ ```mermaid
38
+ flowchart TD
39
+ A["Clean installation"] --> B["Apply secure initial configuration"]
40
+ B --> C["Limit exposure and use identity checks"]
41
+ C --> D{"User selects a weaker mode?"}
42
+ D -- "No" --> E["Keep secure configuration"]
43
+ D -- "Yes" --> F["Show risk and get clear user consent"]
44
+ F --> G["Record the configuration change"]
45
+ ```
46
+
47
+ ## Language examples
48
+
49
+ The two examples default to local access, authentication on, and no administrative interface.
50
+
51
+ ### Python
52
+
53
+ ```python
54
+ @dataclass
55
+ class Config:
56
+ bind: str = "127.0.0.1"
57
+ require_auth: bool = True
58
+ admin_enabled: bool = False
59
+ ```
60
+
61
+ ### Rust
62
+
63
+ ```rust
64
+ impl Default for Config {
65
+ fn default() -> Self {
66
+ Self {
67
+ bind: "127.0.0.1".into(),
68
+ require_auth: true,
69
+ admin_enabled: false,
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ## Boundaries and tensions
76
+
77
+ A default must work in its specified context. A control that all users disable does not give
78
+ sufficient security.
79
+
80
+ Deployed systems can have compatibility constraints. Those constraints do not make insecure
81
+ defaults correct for new deployments. Secure by Default applies to the initial configuration. Fail
82
+ Closed applies to a runtime security decision that is not completed.
83
+
84
+ ## Examples
85
+
86
+ ### Positive
87
+
88
+ A service listens only on loopback and uses authentication. It creates no shared default
89
+ password. An operator must select and configure administrative access.
90
+
91
+ ### Misuse
92
+
93
+ A dashboard binds to a public interface with anonymous administrator access. The documentation
94
+ tells users to add authentication subsequently.
95
+
96
+ ### Athena and agent workflows
97
+
98
+ A new tool starts with read-only repository scope. It gets write access only for a task that grants
99
+ that access. Installation does not expand agent authority.
100
+
101
+ ## Related principles
102
+
103
+ - [P048 — Secure by Design](p048-secure-by-design.md)
104
+ - [P050 — Least Privilege](p050-least-privilege.md)
105
+ - [P051 — Complete Mediation](p051-complete-mediation.md)
106
+ - [P054 — Defense in Depth](p054-defense-in-depth.md)
107
+
108
+ ## References
109
+
110
+ ### Source information
111
+
112
+ - [Saltzer and Schroeder, *The Protection of Information in Computer Systems*](https://doi.org/10.1109/PROC.1975.9939)
113
+ gives information about access decisions that use permission, not exclusion. This fail-safe
114
+ default is a historical source for this product-configuration principle.
115
+
116
+ ### Applicable information
117
+
118
+ - [CISA, *Shifting the Balance of Cybersecurity Risk*](https://www.cisa.gov/sites/default/files/2023-06/principles_approaches_for_security-by-design-default_508c.pdf)
119
+ makes security part of the default product experience and gives producers responsibility.
120
+
121
+ ### More information
122
+
123
+ - [OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)
124
+ uses denial as the default authorization policy and gives authorization-policy tests.
125
+
126
+ [Back to the principles catalog](../README.md#p049)