Validate Package: $ARGUMENTS

Run this checklist after building a package to ensure it conforms to the spec and project patterns.

1. Structure Check

Verify the package directory matches the spec's Package Structure section:

find packages/$ARGUMENTS/src -type f -name "*.ts" | sort

Compare the output against the file list in the spec. Every file listed in the spec must exist.

2. Dependency Check

Read packages/$ARGUMENTS/package.json and verify:

• "type": "module" is set
• "effect": "^3.10.0" is in dependencies
• All internal dependencies use "workspace:*" (e.g., "@reactive-agents/core": "workspace:*")
• Dependencies match what the spec lists
• No unnecessary dependencies (e.g., no lancedb, no nomic)
• tsconfig.json extends ../../tsconfig.json

3. Pattern Compliance

Search the package source for anti-patterns:

# Should find ZERO matches for these anti-patterns:
grep -rn "throw new" packages/$ARGUMENTS/src/ || echo "✅ No throw"
grep -rn "^interface " packages/$ARGUMENTS/src/ | grep -v "Input\b" || echo "✅ No plain interfaces (note: interface is acceptable for strategy input types like ReactiveInput, PlanExecuteInput, etc. that carry Effect types)"
grep -rn "let " packages/$ARGUMENTS/src/ || echo "✅ No let declarations"
grep -rn "new Error" packages/$ARGUMENTS/src/ || echo "✅ No new Error"
grep -rn "await " packages/$ARGUMENTS/src/ || echo "✅ No raw await"
grep -rn "Promise<" packages/$ARGUMENTS/src/ | grep -v "runPromise\|test" || echo "✅ No raw Promises"

# Should find matches for required patterns:
grep -rn "Schema.Struct" packages/$ARGUMENTS/src/ && echo "✅ Uses Schema.Struct"
grep -rn "Data.TaggedError" packages/$ARGUMENTS/src/ && echo "✅ Uses Data.TaggedError"
grep -rn "Context.Tag" packages/$ARGUMENTS/src/ && echo "✅ Uses Context.Tag"
grep -rn "Layer.effect\|Layer.scoped" packages/$ARGUMENTS/src/ && echo "✅ Uses Layer.effect/scoped"
grep -rn "Ref.make\|Ref.get\|Ref.update" packages/$ARGUMENTS/src/ && echo "✅ Uses Ref for state"

4. Kernel Extension Compliance (if package touches reasoning/kernel)

If changes are in packages/reasoning/src/kernel/, run:

# Phases must follow the exact type signature — no extra arguments
grep -n "export const.*Phase" packages/reasoning/src/kernel/capabilities/ -r
# Guards must return GuardOutcome — not boolean, not void
grep -n "export const.*Guard\b" packages/reasoning/src/kernel/capabilities/act/guard.ts
# MetaTool registry entries must be in act.ts only
grep -n "metaToolRegistry" packages/reasoning/src/kernel/ -r

FAIL if:

• A new phase function has a signature other than (state: KernelState, context: KernelContext) => Effect<KernelState, never, LLMService>
• A guard returns anything other than { allow: true } or { block: true; reason: string }
• kernel-runner.ts main loop was modified to add per-turn logic (use phases instead)
• context-engine.ts dead sections (buildDynamicContext, buildStaticContext) were modified or re-enabled

Dead code areas — never touch:

• buildDynamicContext / buildStaticContext in context-engine.ts (~560 LOC, disabled behind flag)
• context-engine.ts dead text-assembly functions (~690 LOC total)

5. Service Verification

For every service in the package, verify:

• Class extends Context.Tag("ServiceName")<...>()
• Tag string matches class name exactly
• All methods are readonly
• All methods return Effect.Effect<T, E>
• Live layer uses Layer.effect(Tag, Effect.gen(...))
• Dependencies resolved with yield* OtherService

6. Runtime Factory Check

Verify src/runtime.ts:

• Exports a createXxxLayer() function
• Uses Layer.mergeAll() to combine services
• Uses Layer.provide() to wire dependencies
• Takes configuration parameters if needed by the spec

7. Index.ts Exports

Verify src/index.ts exports:

• All public Schema types
• All Data.TaggedError classes
• All service Context.Tag classes
• All *Live layer implementations
• The createXxxLayer() factory function
• No internal/private implementation details

8. Test Coverage

Verify tests exist and pass:

bun test packages/$ARGUMENTS

Check:

• Test file exists for each service
• Tests cover happy path, error cases, and state management
• Tests use Effect.provide(testLayer) pattern
• Tests use mock layers for dependencies where appropriate
• All tests pass

9. TypeScript Compilation & Build

# Type checking
bun run --filter "@reactive-agents/$ARGUMENTS" typecheck

# Build with tsup (produces dist/ output)
cd packages/$ARGUMENTS && bun run build

Both must complete with zero errors.

10. Dist Output Verification

After building, verify that dist/ contains the expected output:

ls packages/$ARGUMENTS/dist/

Check:

• dist/ directory exists
• index.js (ESM bundle) is present
• index.d.ts (type declarations) is present
• No unexpected files or stale artifacts

11. Spec Fidelity

Read through the spec one final time and verify:

• Every type/schema in the spec is implemented
• Every error type in the spec is implemented
• Every service in the spec is implemented
• Every method on every service matches the spec's signature
• The build order was followed (files created in correct sequence)
• Any spec-specific notes or caveats are addressed

12. Integration Points

If this package is consumed by others:

• Downstream packages can import from @reactive-agents/$ARGUMENTS
• Types are usable in downstream service signatures
• Layer can be composed with Layer.provide() in downstream packages

Report

After completing all checks, summarize:

• Number of checks passed / total
• Any issues found with specific file paths and line numbers
• Recommended fixes for any failures