Can an AI academic-planning conversation make its evidence, missing information, next actions, and access boundaries visible enough for a student to inspect and correct?

This is not a claim that a language model becomes an academic adviser. It is a claim about workflow design. Academic planning is rarely one lookup. A student may need to combine a course prerequisite, a professor's review evidence, a major requirement, a change-of-major rule, a calendar deadline, a current section, a registration appointment, and personal constraints. If those pieces are mixed together in an ordinary chat, it is hard to tell which sentence is a confirmed fact and which sentence is a guess.

Pathfinder tries to make that distinction operational.

The public project is here: github.com/richisblog/Pathfinder-UCD. The authoritative implementation notes are the repository's architecture guide, feature guide, and prompt composition guide.

First, an important boundary: this is not hidden chain-of-thought

When people ask “how does it think?”, there are two different things they may mean:

1. The observable workflow: which tool was called, what evidence came back, what remains unknown, what Todo item is next, and why the answer is blocked or ready.

2. The model's private internal reasoning: hidden token-by-token reasoning that should not be treated as a product transcript.

Pathfinder documents and displays the first. It does not claim to expose the second. The visible progress state is a compact, bounded consultation record; it is not a dump of private model reasoning. That distinction is important for both safety and intellectual honesty.

The complete request lifecycle

At a high level, one student message travels through the following stages:

The host-observable consultation loop. It is not a visualization of private chain-of-thought.

This is a description of the host-controlled workflow and the prompt contract, not a promise that a model can never make a mistake. The design makes a mistake easier to find: a reviewer can ask which tool result supported the sentence, which fact is still unknown, or which source was unavailable.

1. A question arrives

Consider a generic question:

“I am considering changing my major to Psychology. What should I take next quarter, which professors are a good fit, and when can I register?”

That sentence contains several dependent problems:

• eligibility and change-of-major requirements;

• completed prerequisites and the student's current record;

• course catalog facts for the next quarter;

• professor and review evidence;

• current sections and availability;

• the student's registration appointment;

• personal preferences such as workload or meeting times.

The application does not need to call every tool immediately. The Pathfinder prompt tells the agent to distinguish a direct answer from a managed consultation. Greetings, capability questions, and one obvious lookup can stay direct. Comparisons, change-of-major eligibility, multi-quarter planning, and professor selection with several constraints should begin a managed consultation with two to six student-facing outcomes.

That classification is a workflow decision, not an accuracy score. It prevents the UI from showing a theatrical plan for “hello”, while making dependencies explicit for a real planning question.

2. The Todo state becomes the public plan

For the example above, a managed consultation might create this visible list:

1. Compare Psychology change-of-major requirements      in_progress
2. Confirm completed prerequisite courses               pending
3. Identify next-quarter courses that fit the goal      pending
4. Check professor and live section evidence            pending
5. Verify registration appointment and time zone        pending

The exact text is generated for the current student question; the important property is the state contract. The Pathfinder prompt asks for a full todo_write snapshot after relevant user answers, successful tool results, empty results, failed results, and Todo status changes. At most one item should be in_progress in a managed academic consultation.

The React desktop reads the latest successful top-level Todo snapshot. The Todo rail shows a completion count, pending/in-progress/completed labels, and the current active item. New incomplete work opens by default. When everything is completed, the rail collapses to a reviewable summary; the student can expand or dismiss it. The companion Known and Unknown sections are derived from the same full snapshot.

The host also keeps a canonical Todo state across turns. This matters when a student answers a clarification question later: the application can resume the same consultation instead of relying only on whatever the model happens to remember in a shortened prompt.

Source links:

• TodoRail.tsx

• todoSnapshot.ts

• internal/campus/native/tools.go

3. Known and Unknown are evidence states, not confidence vibes

Pathfinder treats Known and Unknown as a strict evidence distinction.

Known

A Known item must come from one of two places:

• an explicit fact the student provided in the conversation; or

• a successful result from a registered evidence tool.

For example, “the student prefers a light workload” can be Known if the student said it. “The course requires ECS 036A” can be Known if the local course reader returned that prerequisite successfully.

Unknown

An Unknown item is a missing fact or access condition that can still change the answer. Examples include:

• completed prerequisites were not supplied;

• the student said “summer” without naming Session 1, Special Session, Session 2, or Summer Quarter;

• the local major database is not present;

• Schedule Builder is not open or the extension is not paired;

• personal schedule consent has not been granted.

The rules deliberately reject several tempting shortcuts. A failed query is not Known. An empty result is not proof that a policy does not exist. General model knowledge is not a UC Davis-specific database row. A login blocker is not a student fact. The system keeps these conditions visible instead of smoothing them into a confident paragraph.

Todo

Todo is the action layer: what outcome still needs to be produced. Known and Unknown explain the evidence state; Todo explains the work state. A Todo item can be completed only after the relevant evidence and student-owned facts are resolved enough for the current goal.

The result is a small, inspectable ledger:

Known:   Psychology target major; student prefers a light workload
Unknown: completed prerequisites; current term section availability
Todo:    compare requirements; verify courses; check live schedule

This does not prove the answer is correct. It makes the answer's dependencies visible enough to challenge.

4. Clarification is a first-class workflow action

When a required value can only come from the student, Pathfinder should ask one narrow question and stop that turn. It preserves the current Todo state so the next answer can continue the same work.

Examples:

• “Which Summer term do you mean: Session 1, Special Session, Session 2, or Summer Quarter?”

• “Which courses have you already completed?”

• “Should I include your registered courses, your waitlist, or only public availability?”

• “Which target major should I compare with your current major?”

Why one question? A long questionnaire creates a new planning problem and makes it unclear which missing field is actually blocking the next evidence lookup. The implementation prefers the smallest student-owned fact that unlocks the next tool.

If the blocker is a source or access step rather than a student fact, the assistant reports a recoverable workflow status: open the browser, sign in, pair the extension, grant consent, provide a local dataset, or retry after a rate limit. These statuses are instructions, not evidence.

5. What “RAG” means in this repository

Pathfinder has a separate Campus UI RAG service and a main desktop agent path. Both use named read-only tools, but the control loops are different.

Campus UI RAG loop

The Campus UI builds a request containing:

1. a dedicated Pathfinder system prompt;

2. the current Pacific time in America/Los_Angeles;

3. up to the last eight stored user/assistant messages;

4. the new user message;

5. the available tool schemas.

The configured provider either returns a final answer or requests one or more tools. The service executes the tool calls, emits tool_start and tool_result events for the UI, appends bounded JSON results, and repeats for at most eight tool rounds. When the provider returns a message with no tool calls, the answer is stored in the local Campus UI store.

This path is tool-mediated RAG. The public snapshot does not claim to use a vector database, embeddings, or a learned semantic retriever in this path.

Main desktop path

The general Reasonix controller adds the Pathfinder academic prompt when campus data or a live schedule client is available. For managed work, it appends a bounded <consultation-progress> context containing the goal, Todo items, successful observations, next action, and completion criteria. The model then chooses the next read-only tool, and the host records the result in the conversation and evidence ledger.

The tools and their sources

The database files are read locally. The provider receives only the prompt, conversation context, and selected evidence for the current request. It does not receive the entire SQLite file by default.

6. How relevant results are selected

“Most relevant” needs to be described precisely because it is easy to imply a more advanced retrieval system than the code actually contains.

Structured SQLite tools

The structured tools expose bounded arguments such as course code, major name, department, filters, search fields, sort order, and result limits. The runner maps those arguments to allow-listed columns and query shapes. Several services use case-insensitive LIKE matching and explicit ranking rules. The major catalog comparison tool can rank exact major-name matches before broader filename/text matches. The tool returns a bounded set of rows or cards for the model to compare.

The model's tool choice is part of relevance: it should not use a professor review query to answer a calendar question, and it should prefer compare_change_major_requirements before separate narrow lookups when the question compares majors.

Local TXT/Markdown search

search_txt_context tokenizes the query, ignores one-character tokens, searches each .txt and .md file, counts case-insensitive term occurrences, sorts matches by score (then source name), and returns a bounded excerpt. This is a transparent lexical scorer, not embedding similarity. It is intentionally simple enough to inspect and test.

Live Schedule Builder results

The browser adapter does not rank a global web index. It requests a specific term/course from the supported Schedule Builder page, normalizes the returned sections, and includes source URL, provider version, fetch time, and freshness. The model then combines that live evidence with stable local catalog facts.

So the honest description is: relevance comes from a combination of query planning, allow-listed structured filters, deterministic local scoring, bounded limits, and the model's evidence comparison. It is not a claim of a universal semantic ranking engine.

7. Evidence returns to the consultation loop

After a tool result, the agent must distinguish three cases:

1. Success: evidence can support a Known item or complete a Todo.

2. Empty evidence: the query returned no matching rows; this is a gap, not proof of nonexistence.

3. Failure or blocked access: preserve a concise Unknown condition and ask for a recovery step.

The prompt tells the model to update the full Todo/Known/Unknown snapshot after material changes, then choose exactly one next action. It should not call a tool merely to create visible activity, and it should not repeat an identical successful query. The main campus runner may reuse identical successful results from an in-memory cache, but cached evidence remains an observation tied to the same tool and arguments.

The final answer should include:

• the practical conclusion;

• which campus facts were grounded by tools;

• what remains student-owned or source-owned Unknown information;

• caveats about freshness, access, or interpretation;

• a concrete next action.

That structure is designed to make an answer useful even when the correct answer is “we need one more fact before deciding.”

8. Schedule Builder and the official UC Davis page

The Schedule Bridge is a read-only, user-controlled adapter. It does not pretend to be an official UC Davis API and it never submits enrollment forms.

Only normalized academic evidence returns; sensitive page-session material stays inside the university page boundary.

Public section search

For a six-digit term code and a course identifier, the extension uses the supported Schedule Builder search endpoint through the page's own origin. It normalizes fields including CRN, section, title, units, instructors, meeting times, enrollment/waitlist counts, prerequisites, general-education notes, drop rules, final-exam dates, and notes.

The request handler uses a queue with a minimum delay and jitter between course requests, caches public live results for the session, and returns source_url, provider_version, fetched_at, and freshness: "live".

Personal context

Registered courses, waitlisted courses, and Pass 1/Pass 2 appointments are personal categories. They require explicit consent for the current Pathfinder conversation. Pass appointments are parsed into a Pacific instant with PST or PDT and an explicit UTC offset. The prompt warns that an appointment is not automatically a registration deadline or an open-registration period.

The page adapter runs in the MAIN world because the university page owns the authenticated same-origin session. The returned object is deliberately narrow: PIDM, cookies, request headers, raw HTML, browser profiles, and HAR/session exports stay inside the page boundary. The extension never uploads a browser profile or changes enrollment.

Fail-closed behavior

The bridge uses a short-lived pairing code and binds the connection to the extension ID. It listens on loopback only. If the browser is not open, the user is not signed in, pairing is missing, consent is absent, the site rate-limits a request, or the response format changes, the result is a named recoverable status such as BROWSER_REQUIRED, LOGIN_REQUIRED, PAIRING_REQUIRED, CONSENT_REQUIRED, RATE_LIMITED, or SITE_VERSION_UNSUPPORTED.

The last status is especially important: if the school's page changes, the adapter stops instead of guessing where the fields moved.

9. Where memory enters the context

There are two different kinds of “memory” in this codebase, and conflating them would make the architecture sound more magical than it is.

Campus UI conversation history

The dedicated Campus UI stores its local threads and messages in the private pathfinder.db runtime store. For a new RAG request, the service reads the last eight user/assistant messages from that thread and sends them with the current question, the RAG prompt, current Pacific time, and tool schemas. It does not send the entire database file to the provider.

Reasonix sessions and context compaction

The general Reasonix agent maintains a session message list. As a prompt approaches the provider context window, the kernel can compact older middle history while preserving a bounded recent tail and archiving originals under private runtime state. This protects token limits without putting a session export into the public repository.

Memory v5 execution compiler

The inherited Reasonix kernel also contains a local Memory v5 execution compiler. Its lifecycle is more specific than “the AI remembers everything”:

1. At boot, the compiler runtime is created under a project-scoped private user state directory when the configuration enables it.

2. On a new agent turn, a task classifier decides whether the input is an actionable task or ordinary chat. Greetings and small conversational turns can skip the compiler.

3. For an eligible task, StartTurn loads prior compiler state, summarizes the goal, builds a bounded Planner IR containing constraints, strategy selection, memory references, steps, and risk notes, and creates a turn trace.

4. Depending on the configured injection mode and throttling gate, the compiled execution contract may replace the visible user turn sent to the provider. Otherwise the compiler still observes and records the turn without injecting that contract.

5. Tool calls and results are recorded against the turn. On completion, the runtime writes bounded local trace and learning files and updates strategy or memory state for future tasks.

6. The UI can expose local memory citations and content-free metrics when the compiler actually influenced a turn.

The compiler does not rewrite the stable system prompt or tool schemas. It does not turn the model's private reasoning into a public transcript. It is a local, rule-driven execution-memory layer that can learn from task traces, successful and failed tool outcomes, and reusable strategies.

Most importantly for Pathfinder: the academic <consultation-progress> block is a separate feature. It is built from the current academic goal, Todo state, bounded successful campus observations, and the next action. It is not the same thing as Memory v5, and the separate Campus UI RAG path uses its own recent history/tool loop rather than the full desktop agent compiler path.

10. The final answer is a handoff, not a verdict

For the example major-planning question, a responsible final response might look structurally like this:

Recommendation
  The local change-of-major evidence supports checking A and B next.

Evidence used
  - change-major comparison: successful local query
  - course prerequisite: successful catalog query
  - current section: live Schedule Builder result, fetched at [time]

Still unknown
  - completed prerequisite course list was not supplied
  - the student's personal pass time was not requested / consented

Next action
  Send the completed prerequisite list, then verify the live section again
  before treating the plan as registration-ready.

The wording will vary by model and language preference, but the contract is stable: do not invent a campus fact after an empty or failed lookup, state the remaining unknown, and give the student a concrete next step.

What this project does not claim

Pathfinder UCD is a research and educational application, not official university advising and not a commercial decision system. It does not claim benchmark performance, perfect freshness, institutional approval, or universal semantic retrieval. The public snapshot excludes chat transcripts, provider key values, runtime databases, personal records, papers, and private research material. The source still contains reusable DeepSeek-Reasonix kernel code; the academic support promise is limited to the documented Pathfinder surface.

That restraint is part of the design. A project meant to help students make real decisions should make it easy to see where its evidence ends.