Internal Workspace and Project Memory

Overview

The workspace/ folder is the repository’s long-lived operating memory. It is split into four durable document types: mission and norms in SOUL.md, dated observations in MEMORIES.md, stable architectural or product commitments in DECISIONS.md, and follow-up work in TASKS.md. workspace/README.md explains how those files work together and defines the update rule that keeps them aligned with code changes.

This workspace discipline is part of the repo’s change-management process, not an optional documentation sidecar. When you make a meaningful docs or code change, you are expected to update at least one workspace memory file in the same commit, and scripts/check-workspace-memory.mjs enforces that rule through pnpm workspace:check-memory.

Architecture Overview

flowchart TD
    Change[Meaningful code or docs change] --> Diff[Collect changed files]
    Diff --> Check[scripts/check-workspace-memory.mjs]
    Check --> Meaningful{Touches tracked paths for enforcement}
    Meaningful -->|No| Skip[Exit 0 skip]
    Meaningful -->|Yes| Memory{Touches workspace memory files}
    Memory -->|Yes| Pass[Exit 0 pass]
    Memory -->|No| Fail[Exit 1 fail]

    subgraph WorkspaceMemory[Workspace memory files]
        Readme[workspace README]
        Soul[workspace SOUL]
        Memories[workspace MEMORIES]
        Decisions[workspace DECISIONS]
        Tasks[workspace TASKS]
    end

    Check -.-> Readme
    Check -.-> Soul
    Check -.-> Memories
    Check -.-> Decisions
    Check -.-> Tasks

Workspace Files

README.md

[!NOTE] scripts/check-workspace-memory.mjs treats workspace/README.md as a valid memory file alongside SOUL.md, MEMORIES.md, DECISIONS.md, and TASKS.md.

workspace/README.md

README.md is the entry point for the workspace memory folder. It explains the folder’s purpose, names each memory file, and states the update rule that keeps the repository’s operating memory current.

  • Defines the workspace as the repo’s long-lived operating memory, described as the project’s “second employee.”
  • Names the purpose of each file:
    • SOUL.md for mission and principles
    • MEMORIES.md for dated observations
    • DECISIONS.md for durable decisions
    • TASKS.md for follow-up work
  • States the update rule:
    • every meaningful docs or code change should update at least one workspace file
    • the update should happen in the same commit
  • Links that rule to pnpm workspace:check-memory and scripts/check-workspace-memory.mjs

SOUL.md

workspace/SOUL.md

SOUL.md captures the project’s mission and working principles. It is the most stable memory file for documentation intent and scoping norms.

  • Mission
    • Keep API docs clear for integrators
    • Prefer explicit scoping language for all user/applicant-bound data
    • Reduce ambiguity between tenant-level and applicant-level behavior
  • Working principles
    • Write docs in second person and active voice
    • Call out security and data-scope constraints near endpoint descriptions
    • When scope is token-derived, say so directly and state whether caller-supplied IDs are accepted
    • Treat workspace memory updates as part of done criteria for each meaningful change
  • Update cadence
    • Update this file when the mission or documentation principles change
    • Update at least one workspace file on each meaningful change so project context compounds over time

MEMORIES.md

workspace/MEMORIES.md

MEMORIES.md is the dated observation log. It is meant for short notes that should influence future edits and keep context from being lost across changes.

  • Purpose
    • Append short dated notes
    • Record observations that should affect later edits
  • Entry template
    • Date
    • Context
    • What changed
    • Why it matters next time
  • Recorded memories
    • 2026-03-24
      • Clarified that balances and transactions endpoints are applicant-scoped by consent token
      • Documented that those endpoints do not accept applicant_id query params
      • Corrected US and JP regional namespace examples to avoid ambiguous /api/v1/-only paths
      • Added the enforcement check (pnpm workspace:check-memory) so workspace memory is updated with future meaningful changes
    • 2026-03-31
      • Added a dedicated sandbox seeding script that creates a tenant, API client, credit profiles, decisions, and US/JP consent evidence fixtures
      • Added pnpm seed:sandbox as the canonical shortcut and documented environment variable overrides in the root README
      • Tightened sandbox fixtures to be deterministic and idempotent
      • Aligned decision outcomes with profile and evidence metrics so credit reviewers see coherent outputs
      • Added JSON and CSV export output for seeded fixtures so reviewers can inspect dummy data directly without querying the database

DECISIONS.md

workspace/DECISIONS.md

DECISIONS.md is the durable decision log. It captures stable architectural or product choices that should continue to shape documentation and implementation.

Decision ID Status Date Decision Consequence
ADR-0001 Accepted 2026-03-24 GET /data/balances and GET /data/transactions identify the applicant from the Bearer access token’s consent context. Docs must explicitly state that no applicant_id parameter is required or accepted for these reads.

TASKS.md

workspace/TASKS.md

TASKS.md is the follow-up queue. It records open work that should stay visible until it is addressed or consciously retired.

Status Item
Backlog Add similar token-scope clarification to income/account summary pages
Backlog Add one cross-link from data endpoints to consent creation docs (applicant_id origin)
Backlog Define ownership/process for updating workspace memory files during PR reviews

Change-Management Enforcement

check-workspace-memory.mjs

scripts/check-workspace-memory.mjs

This script enforces the workspace update rule. It inspects changed files, decides whether the change is meaningful for documentation or code, and fails the run if no workspace memory file changed alongside that work.

Script behavior

Function / Constant Description
memoryFiles Set of files that satisfy the workspace memory rule: workspace/SOUL.md, workspace/MEMORIES.md, workspace/DECISIONS.md, workspace/TASKS.md, and workspace/README.md
lines(text) Splits command output into trimmed, non-empty lines
sh(cmd) Executes a shell command with execSync and returns trimmed stdout
changed Combined list of modified, staged, and untracked files considered by the script
meaningfulTouched Boolean that becomes true when touched files match apps/, packages/, docs/, documents/, scripts/, or package.json
memoryTouched Boolean that becomes true when any changed file is in memoryFiles

File discovery flow

  1. Reads changed files from git diff --name-only HEAD.
  2. Adds untracked files from git ls-files --others --exclude-standard so local edits count before staging.
  3. Falls back to git diff-tree --no-commit-id --name-only -r HEAD if no changes were found.
  4. Checks whether any changed file matches the meaningful-change rule.
  5. If the change is meaningful, checks whether at least one workspace memory file changed.
  6. Exits with a failure message if the rule was violated.

Runtime outcomes

Outcome Condition Exit behavior
Skip No tracked code or docs changes are detected Logs workspace-memory-check: no tracked code/docs changes; skipping. and exits 0
Pass A meaningful change includes at least one workspace memory file Logs workspace-memory-check: passed. and exits 0
Fail A meaningful change does not include a workspace memory file Logs workspace-memory-check: failed. Update at least one workspace memory file (SOUL/MEMORIES/DECISIONS/TASKS/README) alongside meaningful changes. and exits 1

Change Flow

Meaningful change with workspace update

sequenceDiagram
    participant Dev as Contributor
    participant Git as Git status and diff
    participant Check as scripts/check-workspace-memory.mjs
    participant Memory as Workspace memory files

    Dev->>Git: Make code or docs changes
    Dev->>Check: Run pnpm workspace:check-memory
    Check->>Git: Read diff and untracked files
    Check->>Check: Classify meaningful touched paths
    alt No meaningful tracked changes
        Check-->>Dev: Skip and exit 0
    else Meaningful change detected
        Check->>Memory: Verify at least one memory file changed
        alt Memory file changed
            Check-->>Dev: Passed and exit 0
        else No memory file changed
            Check-->>Dev: Failed and exit 1
        end
    end

Workspace memory update cycle

stateDiagram-v2
    [*] --> Idle
    Idle --> Skipped: no meaningful touched
    Idle --> Validating: meaningful touched
    Validating --> Passed: memoryTouched
    Validating --> Failed: !memoryTouched
    Passed --> [*]
    Failed --> [*]
    Skipped --> [*]

Repository Norms Captured by the Workspace

The workspace files encode the repo’s documentation and change-management norms in a way that survives individual code changes.

  • SOUL.md is the mission and style anchor for documentation authors.
  • DECISIONS.md records durable commitments, so later edits preserve previously accepted scoping rules.
  • MEMORIES.md captures short-lived but important observations that should influence future edits.
  • TASKS.md keeps unresolved follow-up work visible.
  • README.md defines the system and links the files together.
  • scripts/check-workspace-memory.mjs enforces that this memory layer evolves with meaningful repository change.

Error Handling

The enforcement script has a single hard failure mode: meaningful code or docs changes without a workspace memory update. In that case, the process exits with code 1 and prints a clear remediation message.

workspace-memory-check: failed. Update at least one workspace memory file (SOUL/MEMORIES/DECISIONS/TASKS/README) alongside meaningful changes.

When no tracked code or docs changes are detected, the script intentionally skips enforcement and exits successfully.

Dependencies

  • git command-line output for change detection
  • pnpm workspace:check-memory as the documented invocation path
  • Node.js node:child_process for execSync
  • Workspace documentation files:
    • workspace/README.md
    • workspace/SOUL.md
    • workspace/MEMORIES.md
    • workspace/DECISIONS.md
    • workspace/TASKS.md

Testing Considerations

Use these scenarios to validate the change-management rule:

  • Touch apps/, packages/, docs/, documents/, scripts/, or package.json without updating a workspace file: the script should fail.
  • Touch one of the workspace memory files alongside a meaningful change: the script should pass.
  • Make only non-meaningful changes outside the enforced path set: the script should skip.
  • Create an untracked workspace memory file locally: the script should count it because untracked files are included in the scan.
  • Update workspace/README.md only: the script should treat it as a valid memory-file update.

Key Classes Reference

Class Responsibility
README.md Defines the workspace memory folder and the same-commit update rule
SOUL.md Stores mission, scoping principles, and documentation norms
MEMORIES.md Captures dated observations that should influence future edits
DECISIONS.md Records durable architectural and product decisions
TASKS.md Tracks follow-up work and open process items
check-workspace-memory.mjs Enforces workspace memory updates for meaningful code and docs changes