hcifootprint: Instructions file for Claude Code

hcifootprint — feature-work map

Turns a web app's interaction surface into a typed, traversable journey graph an LLM can plan over. You author actions and name journeys; a tool is what is served to a model. One authored sentence (does) is both the human's label and the model's tool description. Everything relational — routes between pages, which action unblocks which — is derived from declarations made for other reasons, never authored. Trust the code where any doc disagrees.

The vocabulary (1.10.0): you declare the JourneyMap; the session is the Walker; the recording carries both. defineJourneyMap/JourneyMap are permanent reference-equal aliases of buildNavigationGraph/NavigationGraph (tree/appmap.ts) — both names ship forever, neither is a rename, and there is deliberately NO Walker export: the walker is the session. Three movers move it — human (a real click, principal: 'user'), agent (the four served verbs whats_here / why / do_action / did_it_work), guard (your data: when/enabledWhen) — plus the world's own Cause.kind: 'stimulus'. Same pattern at three altitudes: footprintjs walks stages, agentfootprint (defineSkillMap) walks skills, this walks screens.

Fire-time verify evidence (1.12.0): Matching verify conditions are fire-time evidence, not an action result. When an action's declarative verify contract covers every key it declares it writes and already holds at fire time, the fire settles on its handler path rather than waiting for a state report and answers alreadyTrue. The rule lives in ONE small module (traverse/already-true.ts, five conditions) called from fire() before the record is minted; it flips exactly one boolean in the state-tap arm's guard, so an already-true fire falls through to the tapless block and waits on the HANDLER rail instead. Condition values come from verify, not writes — writes is key names only by stated law, so nothing here can know the value an action would set. The marker is alreadyTrue: FilterCondition[] on the fire result AND the row (presence is the mark, the value is the evidence: one field, not a boolean beside a list), served by modes.ts on the fire result and the settled did_it_work answer with one authored sentence. It records the earlier check, not success or an absence of writes; the handler may change state or fail. Read effectStatus, outcome, outcomeNow when present, and any error for the result. NOT stamped on an allowed-unmaterialized fire — that fate already has materialized: false.

Refusals teach, including the four that did not (1.12.0): TRANSITION_ID_REQUIRED, ACTION_REQUIRED, KEY_REQUIRED and JOURNEY_REQUIRED were raised as {ok:false, judgment:'error', reason} and nothing else — no why, no correction, no valid set, not even positionData(). They now meet the house standard: the argument named, the correction attached, the valid set carried where one exists (actions / journeys from the same doors UNKNOWN_ACTION / UNKNOWN_JOURNEY read; pending + awaitingSettlement + awaitingHuman from the same doors UNKNOWN_TRANSITION reads), and honest silence where none does (KEY_REQUIRED — why runs a slice and never refuses a key, so there IS no valid set). ADDITIVE: the four reason strings are unchanged, none grows a singular transitionId (consent-invariant.test.ts sweeps for that), and no openTransitions was minted — awaitingSettlement is already the word for fires still open, and a second name for one fact is what answer-grammar rule 3 forbids. One in-repo toEqual pin was loosened deliberately (one-journey-tool.test.ts) — it was the only exact-match assertion on the four.

Position has three tiers, one door each (1.11.0): page (sync) → container (observeFocus, new) → state (updateState, not position). Sync pages; observe the deeper place. sync() moves the walker and decides what is served; observeFocus() says which tab or area the reader is in. Declare containers, and report the deepest one on screen. The middle door had to exist: actions are served from the PAGE, so a cursor on a tab is served nothing (a container path to sync now syncs its page and warns, naming observeFocus — before 1.11.0 it went off-graph silently), and focus moved only on fire()/sync(), so a PERSON clicking a tab could never move it. observeFocus (traverse/nav-session.ts) sets focus + the new lookingAt getter (served beside youAreOn by modes.ts positionData), records a FocusMove, and touches NOTHING else — no transition, no version bump, no change to available(). It refuses BY NAME: undeclared node, or a node on another page. Three facts, three doors: show()/setVisible() = VISIBLE, observeFocus() = the READER, sync() = the WALKER. Authored half lintable (unevidenceable-tab, advisory); the runtime half no static check can see.