joycraft-add-fact

At skill entry, run node docs/.joycraft/check.mjs check --json --session <session-id> once, reusing JOYCRAFT_SESSION_ID if supplied or one ID chosen for this conversation. If the checker is missing or fails, continue the requested skill quietly without retrying setup. Offer updates only for display: true; current, postponed, off, and unknown stay quiet. If automaticUpdate is present, finish this skill, then run its exact command once from the project root: the candidate must verify every safety gate before applying. Other updates require approval. After an offer or automatic attempt, record it with node docs/.joycraft/check.mjs acknowledge <available-version> --session <session-id>. Apply updates only at this workflow boundary; after success, reinvoke the skill or restart the session to load changed instructions.

Add Fact

The user has a fact to capture. Your job is to escalate it to a check where one is possible, otherwise classify it, route it to the correct context document, and append it in the right format.

Step 1: Get the Fact

If the user already provided the fact (e.g., $joycraft-add-fact the staging DB resets every Sunday), use it directly.

If not, ask: "What fact do you want to capture?" -- then wait for their response.

If the user provides multiple facts at once, process each one separately through all the steps below, then give a combined confirmation at the end.

Step 1b: Escalate to a Check First (Harden-First)

Before choosing a doc, apply the intervention-elimination hierarchy: can this fact be enforced as architecture, a deny pattern, or a CI check? A fact that is ALWAYS/NEVER-shaped, could cause real damage if violated, and applies across all work belongs in AGENTS.md's behavioral boundaries with teeth — invoke $joycraft-harden to convert it (rule + deny pattern stamped together) and stop; prose is the residue after checks fail, not the default destination. Advisory, never blocking: if the human declines, or harden is not installed (note it), continue to Step 2. A check-eligible fact whose why deserves prose can still land in the decision log per Step 2's rubric. Purely informational facts, one-time decisions, and diagnostic tips are not escalation candidates — classify them below.