Projects

Manage the user's project registry. Each project lives at ~/.pal/memory/projects/{slug}/ISA.md. Frontmatter holds operational state (next steps, blockers, handoff); the body holds ISA spec sections (Problem, Goal, Criteria, Context, Decisions, etc.). The Stop hook auto-touches updated whenever the cwd resolves into a registered project — just being in the project keeps it warm.

CLI

All operations go through the canonical CLI:

pal cli project <command> [args]

Output is JSON.

ISA Sections

The body of each ISA.md holds spec sections. Use update-section to set them:

ISC archive model. complete-isc does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. list-isc <name> shows open ISCs by default; pass --closed (archived only) or --all (open + archived) to read finished ones. reopen-isc pulls an archived or retired ISC back into the open set. edit-isc <name> <id> "new text" rewrites an ISC's wording in place, keeping its id and state — use it to sharpen a vague criterion instead of closing and refiling. retire-isc <name> <id> [--by <id>] closes an ISC that stopped being valid: it files under a ### Retired heading as [~] rather than claiming the work was done, and --by records the superseding ISC. A retired ISC counts as neither open nor done, is listed with --retired, and keeps its id reserved so no future ISC can reuse it. prune-isc <name> backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.

Routing

Proactive registration

When SessionStart context flags the current cwd as unregistered (e.g. 💡 cwd <path> is not yet registered; suggest registering if substantive work begins) and the user starts substantive work (not just "hi"), surface the suggestion conversationally before the second tool call:

"I see we're in <basename> and it's not registered yet — want me to add it as a project?"

• Default name = the FULL last path segment of cwd, lowercased. For /repos/portable-agent-layer → portable-agent-layer. Never split on -.
• Confirm before creating. Never auto-create without explicit user approval ("yes", "do it", "register").
• Capture context in conversation. If the user accepts but doesn't volunteer a goal, ask one short question, or infer from the last few messages and confirm.
• Ask what it serves. One question, at registration: is this moving a stated goal forward, a way the work could pay, or kept for its own sake? Pass the answer as --serves goal|revenue|fun with a six-word --serves-note. It is the only thing that ranks the project against the others, and PAL will guess it later if you skip it — a guess the user then has to correct.

When NOT to suggest registration

• cwd has no project marker (.git, package.json, pyproject.toml, Cargo.toml, go.mod, etc.) — it's a notes folder, not a project.
• The user is clearly browsing or doing a one-off task.
• An ancestor of multiple registered projects is the cwd (e.g. a generic dev root) — that's browse mode by design.
• You're unsure. Err toward not registering.

Append-as-you-go

When the user describes next steps, blockers, or decisions during normal work, invoke the relevant subcommand to keep state current — that's the dynamism this system is built for. Don't invoke for fleeting comments, hypotheticals, or things the user is just thinking through. Wait for a clear declarative ("let's add X", "Z is blocking us"), not a question or musing.

Examples

Storing a reference under an existing project

User: "store under <project> that a reference implementation exists in this repo"
→ Identify the project from `list` (or by name)
→ Durable reference, not a task → update-section
→ pal cli project update-section <slug> context "Reference implementation lives in this repo"

Registering the current repo

User: "track this project"
→ Default name from cwd basename, confirm with user
→ Ask what it serves: a goal, a way it could pay, or fun
→ pal cli project create --path "$(pwd)" --objectives "first objective; second objective" --serves revenue --serves-note "could be sold as a service"

Correcting what a project is for

User: "<project> isn't a toy, it's the thing I'd actually sell"
→ pal cli project serves <slug> revenue "the one I would sell"

Logging a decision

User: "we decided <decision> because <reason>"
→ pal cli project add-decision <slug> "<decision>" "<reason>"

Setting the goal and criteria

User: "set the goal for pal to 'ship ISA support with full test coverage'"
→ pal cli project update-section pal goal "ship ISA support with full test coverage"

Completing a project

User: "mark <project> as complete"
→ Confirm
→ pal cli project complete <slug>

Anti-patterns

• Don't dump the full ISA.md. Summarize. The user can ask for the raw payload.
• Don't write without confirming the field choice on ambiguous "store" requests. A context fact sticks forever; a next step implies follow-up — these are different commitments.
• Don't edit ISA.md files directly. Always use the CLI — it timestamps updated and keeps the schema valid.

Rules

• Always check list (or resume <name>) before writing — match an existing project rather than spawning a near-duplicate.
• Slugs are [a-z0-9_-]+. Never rename a slug; if the display name needs to change, that's a code-side concern, not a slug change.
• The Stop hook handles updated automatically when cwd matches path — no manual touch needed just to mark a project alive.
• Always announce a new ISC with the 🎟️ emoji — every single time, no exceptions. Whenever you open an ISC (add-isc), report it back to the user on its own line prefixed with the ticket emoji and the ISC number, e.g. 🎟️ ISC #71 — <title>. This holds in every response mode and context (ALGORITHM, NATIVE, or a bare reply); opening an ISC without the 🎟️ marker is a defect.