@solaqua/ghosts 0.3.1 → 0.4.1

package/engineering/skills/loop-plan/SKILL.md

@@ -1,220 +0,0 @@
----
-name: ghosts:loop-plan
-description: Planning-only loop for complex development and design problems, adaptable to other domains; uses evidence, alternatives, counterarguments, and premortems to resolve material uncertainty or costly tradeoffs. Skip routine implementation planning.
-disable-model-invocation: true
----
-# Loop Plan
-
-Create a plan another person or agent can execute without rediscovering key
-decisions. Inspect context and write planning artifacts only; stop before
-implementation or invoking an execution skill. Scale depth to uncertainty and
-the cost of a wrong decision, not the number of tasks or document length. For
-other domains, replace files, interfaces, and tests with the relevant
-deliverables, dependencies, and verification; omit software-only checks.
-Write responses and the plan in plain, natural English, or in Korean when the
-user writes in Korean, including template headings.
-
-## Runtime loop
-
-Before acting, create `/tmp/loop-plan-<safe-task-slug>.md` with a unique slug
-or timestamp, `Current state: Pass 1 / Next: Understand`, the checklist below,
-and an empty append-only `Repair log:`. Process items in order, finish each
-before moving on, record a short outcome, and update `Current state`. Mark
-`[x]` only after completion and `[-]` only with a reason; never erase or
-uncheck historical rows. After a repair, append a numbered `[ ] Recheck P2: ...`
-row for the earliest affected item and record the trigger, change, rechecked
-items, and result in the repair log. Finish only after final validation.
-
-```text
-- [ ] Understand the outcome, constraints, and relevant evidence
-- [ ] Resolve research and user-decision dependencies before framing
-- [ ] Frame success, scope, principles, and decision drivers
-- [ ] Set the review budget from uncertainty, impact, and reversibility
-- [ ] Compare viable approaches and choose a provisional direction
-- [ ] Draft ordered work packages and validation
-- [ ] Challenge the design and run a premortem
-- [ ] Any unsupported assumption, unresolved decision, or stronger alternative that changes the plan?
-- [ ] Any unaddressed failure, dependency, or unverifiable completion criterion?
-- [ ] Any unnecessary scope, complexity, or detail?
-- [ ] Final validation and delivery of the plan
-```
-
-Answer every `Any ...?` row Yes or No. On Yes, repair the smallest material
-issue and return to the earliest affected step before repeating the review. If
-progress depends on missing evidence or a user decision, identify the exact
-blocker instead of repeating the review or claiming readiness.
-
-## Adaptive review
-
-Do not make the user choose a mode. After framing, keep a decision ledger with
-each material decision's impact, uncertainty, reversibility, and needed
-evidence. Use qualitative `low`, `medium`, or `high` values and states such as
-`open`, `investigating`, `supported`, `disputed`, `gated`, and `closed`.
-Require at least one independent targeted review for a decision with high
-impact and high uncertainty, low reversibility, or cross-component effects. A
-request for `ralplan` or subagents raises the review budget without imposing a
-fixed ceremony.
-
-```text
-[Understand] → [Route unknowns]
-                  ├─ evidence → [$ghosts:loop-research]┐
-                  ├─ user decision → [$ghosts:grill-me] ├→ [Frame + ledger] → [Draft]
-                  └─ known →──────────────────────────┘              ↓
-                                                     [Any high-impact uncertainty?]
-                                                       ├─ No → [Self challenge]
-                                                       └─ Yes → [Targeted subagent questions]
-                                                                   → [Synthesize] → [Revise] ↺
-                                                         → [Premortem] → [Any material issue?]
-                                                         → [Validate + deliver]
-```
-
-For each unresolved ledger item, record a question ID, covered decision IDs,
-capability, required inputs, `depends_on` question IDs, decision criterion,
-and required evidence. Dispatch only ready questions; run independent ones in
-parallel and refresh the snapshot after upstream results.
-
-Choose a narrow capability rather than a permanent role:
-
-- **Investigation:** establish a missing fact, constraint, dependency, or
-  feasibility signal.
-- **Design challenge:** test boundaries, responsibilities, dependency
-  direction, and the strongest case against the chosen approach.
-- **Execution challenge:** test prerequisites, rollout, recovery,
-  observability, and demonstrable completion.
-- **Adversarial challenge:** identify a credible failure or attack path when
-  relevant.
-
-Give each subagent the exact question, context snapshot, candidate options,
-decision criterion, and required evidence. Keep it read-only and request
-`finding`, `evidence`, `consequence`, and `recommendation`. Record each call as
-`complete`, `failed`, `timed_out`, or `invalid`. Retry or reassign once when
-useful, counting that attempt against the single follow-up budget; then use
-self-review only when the risk permits. An unresolved high-impact item stays
-`conditional` or `blocked`.
-
-When two independent reviews are warranted, give them the same snapshot without
-either review's findings, then record disagreements and their resolution. The
-primary agent alone synthesizes the findings, records which decision changed
-and why, and revises the draft.
-
-When a finding changes a material decision, scope, or acceptance criterion,
-send the revised delta to the relevant completed reviewer for one confirmation
-pass. Ask whether the original concern is resolved, what new consequence the
-revision creates, and whether a material objection remains. Record the response
-and any objection in the question record and decision ledger. Skip the pass
-when no material change occurred; when used, it counts against the single
-follow-up budget and is review evidence, not user approval.
-Preserve blind independence for reviews that have not run. If confirmation is
-unavailable or a material objection remains, keep the item `conditional` or
-`blocked`.
-
-Set a bounded budget at delegation: one initial question per high-impact item,
-one follow-up per item for conflicting, insufficient, or materially changed
-evidence or drafts (including retry, reassignment, or confirmation), and at
-most five synthesis passes. Repeat only while a material item lacks support or
-a credible objection remains. Stop when high-impact decisions have evidence or
-explicit gates, no unresolved objection changes the recommendation, and
-acceptance and verification criteria are concrete. If the budget is exhausted
-or the same material objection survives two revisions, deliver `conditional`
-or `blocked` with the exact reason. If delegation is unavailable, perform the
-same questions as self-review and state that no independent review occurred.
-Subagent findings are review evidence, never user approval or authorization to
-implement.
-
-For high-risk work, deepen relevant challenges with three premortem scenarios
-and the verification levels the problem needs. Do not add irrelevant test
-layers to a design-only problem.
-
-## Understand and frame
-
-Inspect relevant code, documents, existing plans, and constraints before asking
-questions that inspection can answer. Distinguish observed facts, inferences,
-and assumptions; cite supporting files or sources. Identify the observable
-outcome, non-goals, affected users or systems, and material constraints.
-
-Route unresolved inputs before making design decisions. Use `$ghosts:loop-research`
-for repository or document investigation, current or contested evidence,
-comparisons, feasibility checks, or source citations; it returns verified
-claims, provenance, uncertainty, and leads that could change the plan. Use
-`$ghosts:grill-me` for choices only the user can make, such as outcome, scope,
-priority, risk tolerance, or external action. It asks the whole ready frontier
-in each round and returns a short, grouped decision summary. Wait for the user
-to confirm the shared understanding before carrying its decisions into the plan.
-Do not
-ask the user for facts that inspection or research can establish, or infer a
-material preference. Carry both outputs into the decision ledger.
-
-Resolve material user choices through the interview's dependency-aware rounds;
-continue independent inspection while waiting. State ordinary assumptions only
-when they do not replace a material user decision. If feasibility remains
-unestablished, put the cheapest useful investigation first with a decision
-criterion and keep dependent work conditional rather than inventing certainty.
-State task-specific principles, rank decision drivers, resolve conflicts
-explicitly, and define observable success before choosing.
-
-## Compare and draft
-
-Compare at least two genuinely viable approaches against the same principles
-and drivers, including a smaller change or no change when viable. Give each its
-strongest case, cost, and downside. If only one survives the constraints,
-explain why the alternatives fail. Recommend a direction, name the accepted
-tradeoff, and state what evidence would reverse it.
-
-Break the direction into dependency-ordered, independently verifiable work
-packages. For each, name the outcome, affected components or files, important
-interfaces, prerequisites, and completion evidence. Prefer end-to-end slices;
-mark proposed paths as new and verify existing references. Specify correctness
-contracts and ordering without prescribing incidental implementation details.
-Do not invent precise estimates or parallelism without a basis.
-
-Map success criteria to concrete checks, including material failure paths and
-relevant existing tests. Add tests only for meaningful behavior. Include
-rollout, observability, recovery, or stop conditions when operational
-consequences require them.
-
-## Challenge and repair
-
-Review a fixed draft in two separate self-review passes before revising:
-
-1. **Design challenge:** make the strongest case against the recommendation;
-   check principle violations, responsibility boundaries, dependency direction,
-   and whether a simpler alternative achieves the outcome. Resolve a real
-   tension through evidence or an explicit tradeoff.
-2. **Execution challenge:** walk through representative work packages as an
-   implementer, including a failure path; check prerequisites, missing
-   decisions, feasibility, and demonstrable completion.
-
-These are not independent agent consensus. If the user requests separate
-reviewers, give them the same draft and source context without the other
-review's conclusions, combine findings only after both finish, and do not claim
-independent review unless it occurred.
-
-Run a premortem: assume failure at a meaningful milestone and trace the most
-consequential plausible failures to plan details. For each, capture the causal
-sequence, enabling assumption, likelihood and impact separately, earliest
-warning, check time, mitigation, and revision or stop trigger. Label unverified
-scenarios as hypotheses and thresholds as provisional; do not invent numerical
-probabilities or promise to eliminate every risk. Include an adversary's
-response only when adversarial behavior is relevant to the actual problem.
-
-Use findings to change the plan and give a short reason for each material
-revision. Put cheap checks of critical assumptions before expensive dependent
-work. Resolve material objections or expose them as blockers; do not bury them
-in a risk list. Recheck affected decisions and packages after each repair.
-
-## Deliver
-
-Save the plan to the user-specified path if one is given; otherwise use
-`/tmp/loop-plan-<safe-task-slug>-result.md` (append a timestamp when a collision
-is possible). Keep the runtime log separate. Make the plan understandable
-without the preceding conversation. Follow
-[templates/plan.md](templates/plan.md), replacing each placeholder or omitting
-the section as it directs.
-
-Before delivery, verify references are accurate, critical assumptions are
-validated or explicitly gated, acceptance checks cover intended behavior, and
-another implementer can proceed without hidden design decisions.
-Readiness describes the plan; it is not user approval or evidence that planned
-checks passed. If handing the document to `ghosts:loop-coding`, preserve explicit
-approval of that plan and let its implementation workflow own execution. End
-with the plan path, chosen direction, and remaining decisions.

package/engineering/skills/loop-plan/templates/plan.md

@@ -1,39 +0,0 @@
-# <Plan title>
-
-**Readiness:** <ready for approval | conditional | blocked> — <reason>
-**Direction:** <Chosen approach in one sentence>
-**Alternative:** <Strongest alternative and the tradeoff that ruled it out; omit when none is viable>
-
-## Outcome
-- <Observable outcome and success criteria>
-- **Out of scope:** <Explicit non-goals>
-
-## Work packages
-1. **<Outcome of the package>**
-   - `<path>` — <What changes and why, without implementation details; mark new files>
-   - **Depends on:** <Earlier package or decision; omit when none>
-   - **Done when:** <Completion evidence>
-
-## Validation
-- <Check to run and what it proves>
-
----
-
-## Details
-Supporting context for reviewers; omit any subsection with nothing material to add.
-
-### Open decisions
-- <Decision only the user can make, with options and a recommendation>
-
-### Constraints and assumptions
-- <Constraint, or assumption with its source or the check that will verify it>
-
-### Alternatives
-- **<Alternative>** — <Its strongest case, and why it lost>
-- **Would change if:** <Evidence that would reverse the chosen direction>
-
-### Risks
-- **<Plausible failure>** — <Early signal>; <mitigation>; <stop or revise trigger>
-
-### Decision ledger
-- **<ID> <Decision>** (<status>) — <Evidence and review call IDs>; <unresolved disagreement, only if any>

package/engineering/skills/test-review/references/backend.md

@@ -1,145 +0,0 @@
-# Backend Testing Guide
-
-This guide adds backend-specific rules and examples to the shared standards in `common.md`.
-
-Repository structure, fixture names, and test commands may differ by repository. This guide focuses on shared judgment criteria for writing and reviewing backend tests, rather than repository-specific usage.
-
-## 1. Test Targets
-
-High-priority targets:
-
-- Business-critical flows such as payment, authentication, authorization, subscriptions, and event publishing
-- Tasks and workers that are expensive to recover from when they fail
-- Complex queries, pagination, cursors, ordering, locks, and idempotency
-- Logic that interprets external system responses and mutates local state
-- Edge-case-heavy logic such as dates, timezones, market holidays, exchange rates, decimals, and discounts
-
-## 2. Test Scope Strategy
-
-API, service, repository, DB, and cache integration tests can catch wiring, transaction, serialization, and dependency override issues.
-
-## 3. Test Naming And Grouping
-
-Basic rules:
-
-- Use `test_<situation>_<expected_outcome>` for test function names.
-- Every test should have a docstring.
-- Use `pytest.mark.parametrize` with readable `ids` for cases that share an execution flow.
-
-Example:
-
-```python
-async def test_expired_subscription_removes_user_role(...) -> None:
-    """An expired subscription removes the user's role."""
-```
-
-Avoid implementation-shaped names:
-
-```python
-async def test_calls_delete_role(...) -> None:
-    ...
-```
-
-### 3.1 Class Grouping
-
-Use classes when related tests are easier to read as one group. Standalone test functions are appropriate when grouping adds no clarity.
-
-- Group tests by feature or public entrypoint.
-- Do not use classes to hide important setup or build complex lifecycles.
-
-## 4. AAA Pattern
-
-Write test bodies in the `given / when / then` flow.
-
-- `given`: Data, fixtures, mocks, and fixed time required for the scenario
-- `when`: The behavior under test
-- `then`: Observable results of `when`, such as the response, DB state, events, and external calls
-
-Example:
-
-```python
-async def test_expired_subscription_removes_user_role(...) -> None:
-    """An expired subscription removes the user's role."""
-    # given
-    subscription = create_subscription(status="active", expired=True)
-
-    # when
-    await expire_subscriptions()
-
-    # then
-    assert not user_has_role(subscription.user_id, "premium")
-```
-
-## 5. Layer-Specific Guidelines
-
-Use the largest layer that still gives a clear signal.
-
-- API tests are a good default when behavior is observable through HTTP. Verify the response contract and important side effects.
-- Service or domain tests are useful when the business rule is the main concern and an API test would be too heavy.
-- Repository or DAO behavior is usually covered through a higher-level test. Test it directly only when the query contract itself is the main risk.
-- Task and worker tests should focus on operational concerns such as duplicate handling, retries, partial failures, and idempotency.
-- Avoid API loops for large setup. Insert data directly or use helpers/factories when setup is not the behavior under test.
-
-## 6. Fixture And Test Data
-
-Backend fixtures commonly provide DB sessions, clients, caches, repositories, and services; scenario factories can use names such as `create_expired_subscription` or `create_verified_user`.
-
-### 6.1 DB Setup
-
-- Isolate DB changes with transaction rollback whenever possible.
-- Use `flush` when DB-generated values or query-visible rows are needed.
-- Use `commit` only when verifying behavior that is visible only after commit, across separate transactions, or through task/worker entrypoints.
-- Do not clean tables manually in tests. Before adding cleanup fixtures, confirm why transaction rollback cannot solve the problem.
-- Prefer DB bulk inserts over API loops for large setup.
-
-### 6.2 Cache And External State
-
-- Isolate cache state and restore dependency overrides, monkeypatches, and environment overrides through the established fixture lifecycle.
-- Verify cache keys, TTLs, and session values directly when they are part of the contract.
-
-## 7. Test Double Policy
-
-Good targets for test doubles:
-
-- Payment providers, Google Play, Apple, Firebase, S3, Discord, email, and Kafka producers
-- Other servers or external HTTP clients
-- Very slow or nondeterministic library calls
-
-Avoid replacing when possible:
-
-- Services, repositories, and DAOs in the same process
-- Internal helpers called by the function under test
-- Private properties or private methods
-- The DB session itself
-- The entire service behind an endpoint
-
-Guidelines:
-
-- If a dependency is already mocked at an upper boundary, do not also mock the lower DAO unnecessarily.
-- Use `spec` or real-object-based `patch.object` for `Mock` and `AsyncMock` whenever possible.
-- Patch where the object is used, not where it is defined.
-
-Partial replacement can be better than replacing the whole object. For example, instead of replacing an entire external client, create the client through the real factory and patch only the failing method. This keeps more framework wiring intact.
-
-## 8. Time, Randomness, And Determinism
-
-For ordering-sensitive queries and pagination, make `created_at`, IDs, and cursor values explicit. Verify timezone conversion or epoch values when they form the storage or response contract.
-
-## 9. Assertions
-
-- In API tests, assert `status_code` first.
-- Verify DB side effects by reading them back through a repository or query.
-- Assert downstream contracts directly, such as event payloads, unique keys, and published flags.
-- Verify authentication and authorization failures at the server boundary, including rejected requests and the absence of unauthorized side effects.
-
-## 10. Snapshot Usage
-
-Response JSON and event payloads can be snapshot targets when their full shape is a stable backend contract.
-
-## 11. Review Checklist
-
-Check these backend-specific concerns:
-
-- Can DB, cache, and dependency overrides leak between tests?
-- Are server authentication and authorization enforced, including rejected requests and unauthorized side effects?
-- Are backend-specific concerns such as pagination, cursors, idempotency, and transactions covered?

package/engineering/skills/test-review/references/common.md

@@ -1,92 +0,0 @@
-# Common Testing Standards
-
-Apply these standards to every test review. Frontend and backend guides add stack-specific rules and examples.
-
-## Meaningful Failure
-
-Tests should fail when the behavior they protect is broken and make the broken requirement clear. Improve the name, setup, or assertions when a failure is hard to interpret. If a refactor breaks a test without changing observable behavior, reconsider its implementation coupling.
-
-## Test Target Value
-
-Do not try to test all code at the same density. Evaluate the protection each test adds to the existing suite against the cost of writing, reading, running, and maintaining it. The goal is reliable protection of important behavior, not the fewest tests or the highest coverage number.
-
-- Before adding or retaining a test, identify the important regression it catches that existing tests do not adequately cover.
-- When a new feature reuses shared behavior, check what existing tests already protect. Add tests for how the feature uses that behavior and for any differences in its contract, rather than copying all tests for the shared behavior.
-- When an integration test already protects a behavior, add narrower tests only when they provide independent protection or clearer checks of important edge cases.
-- Before removing a test, confirm that important requirements and failure cases remain protected.
-- Give lower priority to simple getters, setters, type declarations, and behavior already guaranteed by libraries or static analysis. Test application requirements those guarantees do not cover.
-
-## Test Scope
-
-Start from an existing public entrypoint and preserve the real collaboration needed to deliver the behavior. A test can involve several components while protecting one focused concern. Prefer integration tests when they give a clear signal; unit tests suit naturally small rules such as calculations, parsers, and validators.
-
-- Narrow the scope when setup obscures the scenario, failures are difficult to isolate, dependency replacement dominates the test, execution cost hurts feedback, or one rule needs many focused edge cases. Keep the reason clear and check what integration protection remains.
-- Replace external or unstable dependencies at the test boundary without replacing the behavior under test. If internal mocks keep increasing or make refactoring fragile, reconsider a larger scope.
-- Before changing production code for testability, check existing public interfaces. Do not expose private members or add abstractions solely for testing convenience; require a clear behavioral testing benefit for design changes.
-
-## Focused Scenarios
-
-Keep each scenario focused on its intended behavior. Combine multiple actions when their sequence is itself the requirement, not merely because they can be placed in one workflow. Do not extend an existing test with unrelated assertions for a new feature when that behavior belongs in another test.
-
-- Make each test understandable on its own, including when setup is shared. Names and descriptions should reveal the scenario and observable outcome; do not claim to verify behavior replaced by a test double.
-- Keep setup, action, and observable results in the Given / When / Then flow. Multiple assertions should describe results of the same behavior.
-- Parameterize cases of the same behavior with readable case names when they share an execution flow. Split cases when branches obscure their distinct scenarios.
-
-## Fixtures And Isolation
-
-- Reuse established setup for infrastructure outside the test's concern, while keeping scenario-specific conditions and actions visible.
-- Create only the data required for the scenario, with enough fields and variation to represent its edge cases.
-- Avoid helpers that create excessive data, accept many scenario-specific parameters, or hide conditions behind deep dependency chains.
-- Extract helpers for clarity; a little duplication is preferable to hiding the scenario. Use names that reveal the provided state, share helpers when multiple features reuse them, and keep feature-specific helpers near the feature.
-- Ensure mutable state and test overrides cannot leak between tests. Choose isolation or restoration appropriate to the resource; reuse established cleanup instead of repeating it when the environment already handles it.
-
-## Deterministic Inputs
-
-Control unstable inputs when they affect the behavior or assertions.
-
-- Use fixed or controlled time, randomness, and UUIDs when their values matter to the scenario.
-- For ordering-sensitive behavior, make sort inputs explicit and verify the required order.
-- When timezone behavior is contractual, verify the relevant timezone, conversion, or epoch values.
-
-## Assertions And Failure Cases
-
-- Derive expected outcomes from requirements, independently of production logic. Avoid tautological tests that repeat production logic or assert only mock setup.
-- Assert the observable results and outgoing interactions that form the contract. Check specific fields when only those fields matter, and exact objects when the whole payload is contractual.
-- For lists, verify length, order, and item identities when those properties are requirements.
-- Existence checks or mock call counts are sufficient only when existence or call count is itself the contract, such as preventing duplicate sends. Otherwise verify the intended result or payload.
-- Cover failure, permission, and authentication cases relevant to the changed behavior through observable outcomes at the tested boundary.
-
-## Snapshots
-
-Use snapshots when the full shape of a focused output is a stable contract and reviewers can understand its diff.
-
-- Stabilize volatile values and ordering using appropriate matchers or controlled inputs.
-- Update snapshots intentionally and review their changes with the code change.
-- Prefer explicit assertions when only a few fields matter. Avoid snapshots covering unrelated output or producing too much data to interpret.
-
-## Coverage
-
-Coverage is a signal for finding test gaps, not a quality goal. Protection of important branches and failure cases matters more than the percentage. Use uncovered code to identify candidate scenarios, explain protection elsewhere or low-value targets when relevant, and do not add meaningless tests to raise coverage.
-
-## Review Checklist
-
-Start with the test's purpose and contribution to the suite:
-
-1. What important behavior does this test protect beyond the protection already provided by other tests?
-2. Does it contain only the setup, actions, and assertions needed for that behavior?
-3. Can a reader immediately understand the conditions, action, and expected outcome?
-
-Then check:
-
-- Would this test actually fail if that behavior broke, or do its assertions merely repeat production logic or mock setup?
-- Does it preserve useful collaboration between real components while keeping its concern focused?
-- If the scope was narrowed, is the reason clear and is necessary integration protection retained?
-- Do the name and description accurately reflect the scenario and observable outcome, with a clear Given / When / Then flow?
-- Does the test verify externally observable behavior instead of internal implementation?
-- Do test doubles replace external or unstable dependencies without replacing the behavior under test?
-- Do fixtures expose the important conditions with only the necessary data, or should hidden setup move into the test body?
-- Can mutable state or test overrides leak between tests?
-- Are inputs that affect the result controlled, including time, UUIDs, randomness, and ordering?
-- Do assertions verify the required results, payloads, or interactions rather than incidental properties?
-- Are relevant failure, permission, and authentication cases covered?
-- If a snapshot is used, does it protect a focused contract with a readable diff?