MANDATORY: call this at session start. The instructions describe the
workflow rules you MUST follow while working in this project — they
are not advisory.

Read-only; does not modify memory.

MANDATORY: call this BEFORE answering ANY question about the project.

Do NOT answer from conversation history alone.
Do NOT re-scan source files (package.json, README, src/) to understand
the project — `summary.md` is the distilled authoritative source and
costs ~500 tokens versus ~5,000 to re-derive.

Your prior assumptions about this project may be stale. Call this
cheaply at session start (and again before ending) to verify your
work is recorded.

Read-only; does not modify memory or trigger event logging.

Call this at session start when structure matters (file layout,
entry points, ownership). Cheaper than scanning the filesystem.

Read-only. Returns 'No project map found.' if PROJECT_MAP.md hasn't
been initialized — run `pjm init` first if so.

Call this at session start alongside get_summary(). plan.md records what
the team MEANS to do (ideas, active plans, next steps) — distinct from
the event log, which records what HAPPENED. When the user shares an idea
or a plan, edit plan.md directly (add a bullet, check items off, move
done work to Shipped); do NOT log plans as events.

Read-only. Returns 'No plan found.' if plan.md hasn't been initialized.

MANDATORY: call this BEFORE proposing any change to a file.
Surfaces failed past approaches, unresolved issues, and high churn
so you don't repeat known dead-ends. Cheap (~100 tokens) and prevents
expensive re-debugging cycles.

Read-only; does not modify memory.

Use this when you only need one issue's context instead of the whole
summary. Example: get_issue('0042').

Read-only.

Token-efficient alternative to get_summary when you only need events
matching a keyword. Returns matching event summaries with type and
timestamp.

Read-only. Case-insensitive substring matching against each event's
summary and notes. Empty result returns a friendly message, not an
error.

Returns an A+→F grade with concrete ROI numbers: debugging hours
saved, tokens prevented, dollars protected. Use when the user asks
about progress or value.

Read-only; computes the score from events.jsonl on each call.

Use when you don't want to read the full summary. ``focus`` (e.g.
'src/auth/') biases the context toward a specific area.

Read-only; assembles a freshly-budgeted context block from
events.jsonl.

Returns lessons learned in past projects that apply to the libraries
you're about to use. Call whenever working with an unfamiliar library
or starting a new feature.

Read-only. Reads from ~/.projectmem/global/ (cross-project memory,
not this repo's .projectmem/).

MANDATORY: call this IMMEDIATELY when you encounter a bug, regression,
or unexpected behavior — BEFORE writing fix code. Logging up-front
means the issue survives interruptions and session boundaries.

Side effects: appends an `issue` event to .projectmem/events.jsonl,
creates an issue file in .projectmem/issues/, updates summary.md,
and marks this issue as the active one for subsequent
record_attempt calls.

MANDATORY: call IMMEDIATELY after each distinct fix attempt — do NOT
batch multiple attempts into one call.

`outcome` must be 'worked', 'failed', or 'partial'. Pass `issue_id`
explicitly to attach to a specific issue; otherwise the attempt
attaches to the active issue. If no active issue exists, an implicit
parent issue is auto-created from this attempt's text (L-008).

Side effects: appends an `attempt` event and updates the issue file.
Does NOT close the issue — call record_fix for that.

Only call AFTER you have evidence the fix works: test passes, error is gone,
or the user confirmed.

If `issue_id` is provided, the fix is attached to that specific issue.
If `issue_id` is omitted, the active issue is closed.

Side effects: appends a `fix` event and updates summary.md. The active-issue
marker is cleared only when the active issue is the issue being fixed.

Call when you make a choice that future sessions or contributors
should know about. Decisions show up in `summary.md` and in
`pjm wrap` context blocks.

Side effects: appends a `decision` event and updates summary.md.
Decisions are append-only — to revise, pass `supersedes` with the old
decision's event id instead of editing history.

Use when you discover something important that doesn't fit as an
issue or decision. Notes survive across sessions and appear in
wrap context blocks.

Side effects: appends a `note` event. Notes prefixed `gotcha:`,
`lesson:`, or `warning:` are eligible for auto-promotion to
~/.projectmem/global/ for cross-project recall (L-046).

Call this when a tool answers "No project selected", or when you need the
exact name to pass as `project`. Read-only; touches no project memory.