recall-os 0.1.1 → 0.2.1

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-application-structure.md

@@ -0,0 +1,30 @@
+# Proposed ADR: Keep controllers thin with Action and Service classes
+
+## Status
+
+Proposed
+
+## Context
+
+Business logic tends to accumulate in controllers and models, which makes it hard to test and reuse.
+
+## Decision
+
+Consider thin controllers that delegate to single-purpose Action or Service classes, with outbound
+payloads shaped by API Resources (or typed Inertia props). This is not accepted until a human
+accepts it.
+
+## Alternatives Considered
+
+- Fat controllers.
+- Fat models holding business logic.
+
+## Consequences
+
+- Reusable, unit-testable business logic and consistent response shapes.
+- More classes and a convention the team must follow.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-auth-sanctum.md

@@ -0,0 +1,30 @@
+# Proposed ADR: Use Laravel Sanctum for authentication
+
+## Status
+
+Proposed
+
+## Context
+
+The application needs authentication for first-party clients (a separate SPA and mobile apps).
+
+## Decision
+
+Consider Laravel Sanctum: the cookie-based guard for first-party SPAs and API tokens for mobile or
+scripted clients. This is not accepted until a human reviews and accepts it.
+
+## Alternatives Considered
+
+- Laravel Passport for full OAuth2 (third-party delegated access).
+- A managed identity provider.
+
+## Consequences
+
+- Lightweight first-party auth without standing up a full OAuth2 server.
+- If third-party delegated access is ever required, revisit with Passport.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.
+- `docs/20-security/SECURITY_MODEL.md` — record the accepted auth and session model here.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-database-eloquent.md

@@ -0,0 +1,31 @@
+# Proposed ADR: Use Eloquent and migrations on PostgreSQL
+
+## Status
+
+Proposed
+
+## Context
+
+The application needs a relational database and a schema workflow.
+
+## Decision
+
+Consider PostgreSQL (MySQL as the alternative) accessed through Eloquent and versioned migrations,
+awaiting human acceptance.
+
+## Alternatives Considered
+
+- MySQL or MariaDB.
+- The query builder or raw SQL without Eloquent.
+
+## Consequences
+
+- Expressive models, relationships, and reproducible schema migrations.
+- Requires discipline against N+1 queries and unbounded result sets.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.
+- `docs/50-quality/TESTING_STRATEGY.md` — how database tests use factories and a disposable
+  database.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-framework.md

@@ -0,0 +1,29 @@
+# Proposed ADR: Use Laravel
+
+## Status
+
+Proposed
+
+## Context
+
+The team needs a productive, batteries-included PHP framework for a production web application.
+
+## Decision
+
+Consider Laravel 12 on PHP 8.3+ as the application framework, following its standard conventions and
+directory structure. This is not accepted until a human reviews and accepts it.
+
+## Alternatives Considered
+
+- Symfony for a more component-assembled approach.
+- A different language or framework entirely.
+
+## Consequences
+
+- A mature ecosystem (Eloquent, queues, Sanctum, Horizon) and strong conventions.
+- Couples the application to Laravel's conventions and release cadence.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-queues-horizon.md

@@ -0,0 +1,29 @@
+# Proposed ADR: Run slow work on queues
+
+## Status
+
+Proposed
+
+## Context
+
+Email, exports, and third-party calls slow down requests and can fail independently.
+
+## Decision
+
+Consider queued jobs for slow or failure-prone work, using the database driver early and Redis with
+Laravel Horizon as throughput grows. This is not accepted until a human reviews and accepts it.
+
+## Alternatives Considered
+
+- Doing the work synchronously in the request.
+- An external task queue or serverless functions.
+
+## Consequences
+
+- Faster responses and isolated, retryable background work.
+- Adds a worker process and queue infrastructure to operate and monitor.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-testing-pest.md

@@ -0,0 +1,30 @@
+# Proposed ADR: Use Pest for testing
+
+## Status
+
+Proposed
+
+## Context
+
+The application needs a fast, readable testing workflow.
+
+## Decision
+
+Consider Pest with model factories and feature tests that exercise real routes against a disposable
+database, awaiting human acceptance.
+
+## Alternatives Considered
+
+- PHPUnit directly.
+- A thinner test suite focused only on unit tests.
+
+## Consequences
+
+- Concise, expressive tests that cover routes, validation, and authorization.
+- The team standardizes on Pest's syntax and plugins.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.
+- `docs/50-quality/TESTING_STRATEGY.md` — record the accepted testing approach here.

package/examples/generated-laravel-api/docs/adrs/proposed/ADR-PROPOSED-laravel-api-validation-authorization.md

@@ -0,0 +1,30 @@
+# Proposed ADR: Validate with Form Requests and authorize with Policies
+
+## Status
+
+Proposed
+
+## Context
+
+Input validation and authorization must be consistent and centralized, not scattered across
+controllers.
+
+## Decision
+
+Consider Form Requests for validation (and request-level authorization) plus Policies and Gates for
+per-model and per-action permission checks, awaiting human acceptance.
+
+## Alternatives Considered
+
+- Inline validation and authorization in controllers.
+- A third-party permissions package layered on top.
+
+## Consequences
+
+- Controllers stay thin; validation and authorization are testable in isolation.
+- Every state-changing action must have an explicit authorization path.
+
+## Related Documents
+
+- `docs/ai/presets/laravel-api-guidance.md` — the proposed Laravel stack guidance.
+- `docs/10-architecture/ARCHITECTURE.md` — record the accepted architecture here once promoted.

package/examples/generated-laravel-api/docs/ai/AI_AGENTS_SKILLS_MCP_STRATEGY.md

@@ -0,0 +1,7 @@
+# AI Agents, Skills, And MCP Strategy
+
+Root agent files are entry points, not guarantees.
+
+Durable memory lives in `docs/`.
+
+MCP is optional external context and does not override accepted repository memory.

package/examples/generated-laravel-api/docs/ai/MCP_STRATEGY.md

@@ -0,0 +1,6 @@
+# MCP Strategy
+
+MCP is not required for this repository.
+
+If MCP is introduced later, document trusted servers, data accessed, permissions, risks, and
+source-of-truth rules.

package/examples/generated-laravel-api/docs/ai/RECALL_COMMANDS.md

@@ -0,0 +1,133 @@
+# Recall OS Commands
+
+This document records the Recall OS commands available to humans and AI agents.
+
+## Completion Gate
+
+Before claiming implementation work is complete, run:
+
+```txt
+pnpm test:run
+pnpm typecheck
+recall doctor
+```
+
+If `recall doctor` reports errors, fix them or report why they cannot be fixed. If it reports
+warnings, address them or record why they are acceptable.
+
+Package binary behavior is covered by binary integration tests.
+
+## Commands
+
+### `recall init`
+
+Initialize neutral repository memory.
+
+Options:
+
+- `--preset <id>`: apply optional preset guidance and proposed decisions.
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+- `--reinit`: required with `--force` to overwrite an existing Recall OS installation (a directory
+  that already has `.recall/config.json`). Without it, `--force` refuses, protecting existing
+  repository memory.
+
+Init also generates a tracked pre-commit hook at `.recall/hooks/pre-commit` that runs
+`recall doctor` plus any `preCommitGates` in `.recall/config.json`. Init proposes, but does not run,
+the activation command `git config core.hooksPath .recall/hooks`.
+
+### `recall adopt`
+
+Inspect an existing repository through read-only manifest and marker files, then write a proposed
+adoption report and proposed framework ADRs for human review. Adopt never executes repository code
+and never produces accepted memory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall skill create <name>`
+
+Generate a portable AI agent skill as `SKILL.md` for both Claude Code (`.claude/skills/`) and the
+portable Agent Skills target (`.agents/skills/`). Known names use the built-in catalog; unknown
+names produce a valid skeleton. Generated skills contain no scripts.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall skill list`
+
+List the built-in catalog skills.
+
+### `recall mcp add <server>`
+
+Generate offline, proposed memory for an MCP server (for example `figma`) as
+`docs/ai/mcp/<server>.md` plus a proposed adoption ADR. Recall OS never connects to the MCP server
+or makes network calls; the agent records durable MCP-derived context into the generated memory for
+human review. It also installs a `capture-mcp-context` agent skill that prompts the agent to record
+that context.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall preset list`
+
+List built-in presets.
+
+### `recall feature create <name>`
+
+Create feature memory docs under the configured features directory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall adr create <title>`
+
+Create a proposed ADR under the configured ADR directory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall adr accept <name>`
+
+Promote a proposed ADR to accepted repository memory. A proposal under
+`docs/adrs/proposed/ADR-PROPOSED-<slug>.md` becomes a numbered, accepted `ADR-####-<slug>.md` and
+the proposal is removed; an existing numbered Proposed ADR is accepted in place.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall module create <name>`
+
+Create module memory docs under the configured modules directory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall doctor`
+
+Check whether repository memory is structurally healthy enough for AI-assisted work, whether basic
+engineering evidence is present, and whether memory references decisions that exist and are
+accepted.
+
+Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
+is an error, and memory that references a not-yet-accepted ADR is a warning.
+
+Exit codes:
+
+- `0`: healthy
+- `1`: warnings only
+- `2`: errors

package/examples/generated-laravel-api/docs/ai/presets/laravel-api-guidance.md

@@ -0,0 +1,62 @@
+# Laravel Preset Guidance (API / SPA backend)
+
+This is proposed guidance, not accepted. Convert any architecture choice into a proposed ADR, then
+an accepted ADR, before treating it as repository truth. Repository rules override model preference.
+
+## The stack (proposed)
+
+- Laravel 12 on PHP 8.3+, using the official conventions and directory layout.
+- No server-rendered frontend: Laravel is an HTTP JSON API consumed by a separate SPA or mobile app.
+- Database: PostgreSQL (MySQL is the alternative) through Eloquent and migrations.
+- Auth: Laravel Sanctum for first-party SPA and mobile clients (Passport only if you need
+  third-party OAuth2).
+- Background work: queues, with Redis and Laravel Horizon when throughput grows.
+- Tests: Pest, with database factories and feature tests over real routes.
+
+Controllers return JSON via API Resources; first-party SPAs authenticate with Sanctum cookies,
+mobile clients with Sanctum tokens.
+
+## Decision forks this stack forces
+
+- Frontend delivery: Inertia (server-driven SPA) vs a decoupled API + separate SPA vs Blade +
+  Livewire.
+- Auth: Sanctum (first-party SPA and mobile) vs Passport (third-party OAuth2) vs a managed identity
+  provider.
+- Database: PostgreSQL vs MySQL, and where read scaling and queues live (Redis vs database driver).
+- Authorization: Policies and Gates vs ad-hoc checks; validation via Form Requests vs inline.
+- Business logic: thin controllers with Action/Service classes vs fat controllers and models.
+- Testing: Pest vs PHPUnit.
+
+## Recommended structure (proposed)
+
+- Keep controllers thin: they validate, authorize, delegate, and return a response — nothing more.
+- Put request validation **and** authorization in Form Requests (`authorize()` + `rules()`).
+- Put per-model and per-action permission logic in Policies and Gates, not in controllers.
+- Put business logic in single-purpose Action or Service classes, not in controllers or models.
+- Shape every outbound payload with API Resources (or typed Inertia props), never raw models.
+- Declare `$fillable` (or `$guarded`) explicitly on every Eloquent model to stop mass assignment.
+
+## Data and performance (proposed)
+
+- Eager-load relationships (`with(...)`) to avoid N+1 queries; enable `Model::preventLazyLoading()`
+  in local and CI.
+- Wrap multi-write operations in database transactions.
+- Paginate list endpoints; never return unbounded collections.
+- Move email, exports, third-party calls, and other slow work into queued jobs.
+- Cache expensive reads deliberately, with explicit invalidation.
+
+## Testing (proposed)
+
+- Write Pest feature tests that exercise real routes end to end, using `RefreshDatabase`.
+- Build state with model factories, not hand-rolled fixtures.
+- Test authorization explicitly: a forbidden action must assert a 403, not just a happy path.
+- Cover validation failures, not only the success case.
+
+## Security considerations (proposed)
+
+- Validate every inbound request through Form Requests; persist only validated data.
+- Authorize every state-changing action through a Policy or Gate.
+- Keep secrets in `.env`; never commit `.env` or hardcode credentials.
+- Apply rate limiting to auth and write endpoints.
+- Keep mass assignment locked down and never trust client-supplied IDs without an ownership check.
+- Scope Sanctum tokens to least privilege; SPA clients use the cookie guard with CSRF protection.

package/examples/generated-laravel-react/.recall/config.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.1.0",
+  "templateVersion": "0.1.0",
+  "preset": "laravel-react",
+  "memoryProfile": "standard",
+  "mode": "standard",
+  "aiTools": [
+    "claude",
+    "codex"
+  ],
+  "docsDir": "docs",
+  "featuresDir": "docs/40-features",
+  "modulesDir": "docs/30-modules",
+  "adrDir": "docs/adrs",
+  "writePolicy": "skip-existing",
+  "preCommitGates": []
+}

package/examples/generated-laravel-react/.recall/hooks/pre-commit

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Recall OS pre-commit hook.
+# Generated by `recall init`. Edit gates in .recall/config.json (preCommitGates),
+# then re-run `recall init --force` to regenerate this hook.
+# Enable once per clone with:
+#   git config core.hooksPath .recall/hooks
+set -e
+
+recall doctor

package/examples/generated-laravel-react/AGENTS.md

@@ -0,0 +1,15 @@
+# generated-laravel-react Agent Instructions
+
+This repository uses Recall OS repository memory.
+
+Start with durable source-of-truth docs under `docs/`.
+
+Required reading:
+
+- `docs/00-product/PRD.md`
+- `docs/10-architecture/ARCHITECTURE.md`
+- `docs/20-security/SECURITY_MODEL.md`
+- `docs/50-quality/QUALITY_GATES.md`
+- `docs/60-engineering/ENGINEERING_STANDARDS.md`
+
+Repository rules override model preferences. If instructions conflict, stop and report the conflict.

package/examples/generated-laravel-react/CLAUDE.md

@@ -0,0 +1,9 @@
+# generated-laravel-react Claude Instructions
+
+This file is loaded automatically every Claude session. The durable project memory lives in `docs/`;
+do not rely on chat history as source of truth, and repository rules override model preference.
+
+@AGENTS.md
+
+Read the docs that `AGENTS.md` routes to before changing code or repository memory. A SessionStart
+hook (`.claude/hooks/session-start.sh`) also injects a memory map at the start of each session.

package/examples/generated-laravel-react/README.md

@@ -0,0 +1,11 @@
+# Laravel + React Example
+
+This folder shows the repository memory generated by:
+
+```bash
+recall init --preset laravel-react
+```
+
+The Laravel + React preset adds Inertia + React (the official starter-kit stack) guidance and
+proposed decisions for the framework, Eloquent, Sanctum auth, Form Requests + Policies, queues, and
+Pest. Those decisions remain proposed until a human accepts them in repository memory.

package/examples/generated-laravel-react/docs/00-product/BRD.md

@@ -0,0 +1,9 @@
+# BRD: generated-laravel-react
+
+## Purpose
+
+Describe the business goal, target users, and success criteria for this repository.
+
+## Current Status
+
+Draft.

package/examples/generated-laravel-react/docs/00-product/PRD.md

@@ -0,0 +1,13 @@
+# PRD: generated-laravel-react
+
+## Purpose
+
+Describe what this repository is building and why.
+
+## Current Status
+
+Draft.
+
+## Notes
+
+Keep product intent durable here. Do not rely on chat history as source of truth.

package/examples/generated-laravel-react/docs/10-architecture/ARCHITECTURE.md

@@ -0,0 +1,11 @@
+# Architecture
+
+## Purpose
+
+Describe the accepted architecture for this repository.
+
+## Current Status
+
+No architecture decisions are accepted yet.
+
+Use ADRs to accept architecture choices.

package/examples/generated-laravel-react/docs/10-architecture/FILE_WRITE_POLICY.md

@@ -0,0 +1,8 @@
+# File Write Policy
+
+Default behavior:
+
+- Skip existing files.
+- Use dry run before risky writes.
+- Require explicit force to overwrite.
+- Never write outside the repository root.

package/examples/generated-laravel-react/docs/10-architecture/MEMORY_ENGINE.md

@@ -0,0 +1,16 @@
+# Repository Memory
+
+Repository memory is the durable source of truth for humans and AI agents.
+
+Source-of-truth order:
+
+1. Accepted ADRs and repository decisions
+2. Architecture docs
+3. Engineering standards
+4. Current PRD and accepted change requests
+5. Security and testing docs
+6. Module docs
+7. Feature plans
+8. Task files
+9. External context
+10. Chat history

package/examples/generated-laravel-react/docs/20-security/SECURITY_MODEL.md

@@ -0,0 +1,32 @@
+# Security Model
+
+## Status
+
+Draft — fill the prompted sections below with this repository's real model as it grows.
+`recall doctor` flags these as warnings once the repository has real work (a feature, module, or
+accepted decision).
+
+## Baseline Rules
+
+- Never commit secrets or credentials, and never read or copy `.env` files into docs.
+- Validate and authorize untrusted input at every trust boundary.
+- Do not add network, telemetry, cloud, MCP runtime, or AI API behavior without explicit review.
+
+## Authentication And Authorization
+
+Describe how this repository authenticates users or clients and how it authorizes actions, including
+where those checks live.
+
+## Secrets And Configuration
+
+Describe where secrets live, how they are injected, and how configuration is kept out of version
+control.
+
+## Sensitive Data
+
+Describe the sensitive or personal data this repository handles, and how it is protected at rest and
+in transit.
+
+## Dependencies And Supply Chain
+
+Describe how third-party dependencies are vetted, pinned, and updated.

package/examples/generated-laravel-react/docs/20-security/THREAT_MODEL.md

@@ -0,0 +1,39 @@
+# Threat Model
+
+## Status
+
+Draft — replace the prompts below with this repository's real analysis as it grows. `recall doctor`
+flags these as warnings once the repository has real work (a feature, module, or accepted decision).
+
+## Assets
+
+Describe what this repository must protect: user data, credentials, money, availability, or
+reputation.
+
+## Entry Points
+
+Describe where untrusted input enters: HTTP endpoints, webhooks, file uploads, queues, CLI input, or
+third-party callbacks.
+
+## Trust Boundaries
+
+Describe where trust changes: client to server, service to database, your code to third-party APIs.
+
+## Threats
+
+Describe the concrete threats that apply to this repository, by category:
+
+- Spoofing — how identities are faked or sessions stolen.
+- Tampering — how requests, data, or builds are altered (injection, mass assignment).
+- Repudiation — actions that must remain auditable.
+- Information disclosure — how sensitive data or secrets could leak.
+- Denial of service — how the system can be overwhelmed or abused.
+- Elevation of privilege — how a user could gain access they should not have.
+
+## Mitigations
+
+Describe the control in place or planned for each threat above.
+
+## Open Risks
+
+Describe accepted or unresolved risks and who owns them.

package/examples/generated-laravel-react/docs/30-modules/README.md

@@ -0,0 +1,17 @@
+# Module Memory
+
+Module memory records what each important module owns, how it should be tested, and which decisions
+affect it.
+
+Future module folders should use:
+
+```txt
+docs/30-modules/<module>/
+  MODULE.md
+  TASKS.md
+  TEST_PLAN.md
+  DECISIONS.md
+```
+
+Agents should update module memory when implementation changes responsibilities, boundaries, tests,
+risks, or decisions.

package/examples/generated-laravel-react/docs/40-features/README.md

@@ -0,0 +1,22 @@
+# Feature Memory
+
+Feature memory records requirements, acceptance criteria, plans, tests, reviews, and completion
+evidence.
+
+Future feature folders should use:
+
+```txt
+docs/40-features/F-###-<feature>/
+  PRD.md
+  ACCEPTANCE.md
+  ARCHITECTURE_IMPACT.md
+  CHANGE_REQUESTS.md
+  PLAN.md
+  TASKS.md
+  TEST_PLAN.md
+  REVIEW.md
+  COMPLETION_REPORT.md
+```
+
+Agents should not implement meaningful feature work without a feature plan or clear source-of-truth
+reference.