Orient: Project Orientation Workflow

Predicate is project-centric: /orient is its first contact with a project. It engages this repository concretely — installs predicate's enforcement, maps the repo, learns its goal, and authors the persistent conditioning layer (the AGENTS.md goal-hierarchy) so every subsequent walk is anchored and gated. Not an idealized formula imposed from outside; a boundary fitted to the actual project.

Quickstart: install predicate into your harness → target a project → run /orient.

---

Phases (state machine; halts at the two human seams)

The eight phases execute in order. Two are human seams — the walk halts and awaits human input before continuing. The others are mechanical or agent-automated.

Phase 0 — BOUND (compose /boundary — do not rush)

Before touching the repo, invoke /boundary to draft an IBC for the orientation work itself: what is this project, what is known vs unknown going in, what is the desired end state of onboarding it.

/boundary is also the authority for the AGENTS.md contract the AUTHOR phase (phase 6) conforms to — composed here, not duplicated. The required content (Goal, Requirements/Invariants/Constraints, Unknowns, Operational entrypoint, Structure, Alignment-to-parent) and the soundness invariants are defined in /boundary §AGENTS.md.

Phase 1 — ESTABLISH (mechanical, automated — no human input)

Run bootstrap/install.sh init --project <dir>: install git hooks into .git/hooks (untracked, auditable, removable), initialize the .ledger sub-repository, wire project config. Idempotent — safe to re-run on an already-oriented project.

Phase 2 — MAP (domain — outward→structure; cheapest tier; hunt-to-dry)

Fan out a multi-modal sweep over the repository:

• Structure — git ls-files for the file tree; directory layout.
• Semantics — what each component does; package/module roles.
• History — git log shape; maturity signals; areas of churn.
• Docs — stated purpose in READMEs, existing AGENTS.md files, or architectural docs.

Scale to the repo: a small project needs one pass; a large one warrants the full sweep. Stop when no new approach-relevant structure surfaces. This phase carries no goal-fit judgment and routes to cheap agents.

Phase 3 — SURVEY (arsenal — outward→environment; cheapest tier)

Enumerate predicate's own skills plus the host harness's installed skills, tools, and MCP servers available to this project. Project each for relevance to the discovered structure; do not enumerate exhaustively into context.

Phase 4 — ELICIT (goal — HUMAN SEAM, halt)

This phase halts. The walk does not proceed until the human confirms the goal.

From the MAP, extract a candidate goal + requirements / invariants / constraints / known-unknowns. Present the candidate to the human with:

• the extracted goal statement (desired end state, not status);
• the requirements, invariants, and constraints identified;
• the known-unknowns with signposts (what would resolve each);
• any conflicting signals in the docs or history that affect goal-fit.

Halt and await confirmation. Goal-fit is not self-attestable — an agent is least calibrated exactly here; the human is the goal authority. Do not proceed to NEST or AUTHOR until the goal is confirmed or corrected.

Phase 5 — NEST (structure decision)

Decide which directories have a goal genuinely distinct from and in service of the root goal, and therefore warrant their own AGENTS.md.

Default: root only. Add a component AGENTS.md only when a real sub-goal exists. Every additional file is a staleness surface: it must be kept true, linked correctly, and synced at every refresh. The alignment-to-parent requirement (from the AGENTS.md contract) is the defeater substrate — a component whose goal does not serve the root is a structural fault.

Phase 6 — AUTHOR (draft against the contract — authority: /boundary)

Draft the root AGENTS.md and any component files decided in NEST. Each draft MUST conform to the AGENTS.md contract in /boundary §AGENTS.md:

• Self-contained entrypoint. Every pointer resolves in-repo or carries a URL. No assumed external knowledge.
• Goal = desired end state, not a status report. Marked WIP where the end state is not yet reached.
• Single source. Reference authorities (rules.md, ambient.md, specs); never copy their text.
• Agent-guiding only. If removing a line changes no agent action, cut it.
• Unknowns are first-class, treated like requirements, each with a signpost.
• Minimal surface area. Every line is a liability kept true; brevity is anti-drift.

Component AGENTS.md files MUST include the alignment-to-parent section (how this component serves the root goal).

AGENTS.md as R/I/U Hierarchy — the P-TRACK persistent anchor

Each AGENTS.md (root and component) MUST include a Requirements / Invariants / Unknowns hierarchy for the construct it governs (P-TRACK I-T1–I-T2, primitives-spec.md §P-TRACK §"The AGENTS.md fusion"). This makes AGENTS.md the persistent anchor that every subsequent walk hydrates its live tracker from, rather than reconstructing from scratch.

Required sections per construct AGENTS.md:

## Requirements
Each item: statement, grounding (source/evidence), signpost (what defeats it).
Pruned to the minimal bounding set — requirement bloat is drift surface.

## Invariants
Each item: statement, grounding, signpost (what would violate it).
Constraints that must hold throughout; distinguished from requirements by
"must hold" vs "must be satisfied."

## Unknowns
Each item: statement, grounding (why it is not yet resolved), signpost
(the observable that would resolve or invalidate it).
Treated first-class like requirements — filed with a signpost, never
merely noted.

## Spec Pointers
Pointers to full specification sources for this construct: doc paths,
ADR links, contract file paths. Kept minimal — one pointer per
authoritative source, never prose summaries of the specs themselves.

Authoring discipline:

• Items MUST carry grounding and signpost (mirrors the context_map.ncl Item contract; last_validated is filled in by the walk that hydrates, not the orient author).
• The Unknowns section tracks known-unknowns with signposts; when a walk surfaces an unknown-unknown, it files it here (promoting it to a known-unknown with a signpost) via the promotion combinator.
• Do not copy spec text into AGENTS.md — point to the spec. The pointer is durable; the prose diverges and must be cut.

Nest depth: add an R/I/U hierarchy to a component AGENTS.md only when the component has a genuinely distinct sub-goal (Phase 5 NEST criterion). A root-only project has one R/I/U hierarchy in its root AGENTS.md covering all constructs.

Phase 7 — RECONCILE (HUMAN SEAM — the sync gate)

This phase halts. The persistent layer mutates only through this reconciliation — never silently.

Present each draft AGENTS.md to the human. The human reconciles (the volatile draft → persistent sync). On approval, land files at their target paths (root /AGENTS.md; component <dir>/AGENTS.md).

Unanswered questions from the known-unknown registry that were not resolved during ELICIT are re-presented here for prioritization, so a topic-change does not lose them.

---

Re-run = Refresh (anti-rot)

On an already-oriented project, /orient is the sync/refresh pass. Run it whenever the AGENTS.md hierarchy may have drifted from reality.

The refresh pass re-executes the same eight phases but MAP and SURVEY are diff-scoped (what changed since the last orientation). ELICIT surfaces drift candidates: stale claims, dead links, a parent goal a child no longer serves (a defeater), requirements that became constraints or vice versa.

RECONCILE on a refresh presents only the changed sections, not the full file. Surfaced-but-unanswered known-unknowns from prior orientations are re-presented so they are never silently dropped.

---

Hydration Protocol — live tracker hydrates from AGENTS.md

When a walk begins on an oriented project (AGENTS.md hierarchy exists), it MUST hydrate its live context_map tracker from the relevant construct's AGENTS.md, not from scratch. (P-TRACK I-T1–I-T2; primitives-spec.md §P-TRACK §"The AGENTS.md fusion".)

Hydration steps:

1. Locate the governing construct AGENTS.md. For a root-scoped task: the root AGENTS.md. For a component-scoped task: the component AGENTS.md (if it exists) plus the root for alignment.
2. Read the R/I/U sections. Extract each item from the Requirements, Invariants, and Unknowns sections.
3. Populate the context-map items. For each extracted item, set:
   • id: a stable identifier (e.g. R1, I2, U3)
   • statement: the item text
   • kind: 'requirement, 'invariant, or 'unknown
   • grounding: the grounding from AGENTS.md (or the AGENTS.md pointer itself if none is recorded: "AGENTS.md#requirements")
   • last_validated: today's date (ISO 8601) — the hydration date
   • signpost: the signpost from AGENTS.md
   • hydration_source: "<path>#<section>" (e.g. "AGENTS.md#requirements") — records that this item came from the persistent anchor
4. Export and verify. The populated context-map MUST pass nickel export against context_map.ncl (ContextMap contract) before the walk proceeds.
5. Start from scratch only when unoriented. An unoriented project (no AGENTS.md) initializes an empty context-map and populates it during the walk. This is the fallback, not the default.

Hydration is the first step of every walk on an oriented project, before any task work. A walk that skips hydration and starts from scratch on an oriented project violates I-T1 (absence = all-unknown-unknown). The tracker_fresh.sh gate enforces this: a stale last_validated on a hydration_source item signals the anchor has drifted.

---

Reorientation — ongoing disposition, triggered by staleness

Reorientation is not a scheduled re-run; it is a disposition triggered by staleness. (P-TRACK I-T3; primitives-spec.md §P-TRACK §"reorientation as an ONGOING disposition".)

A staleness trigger fires when:

• The tracker_fresh.sh gate reports STALE on any context-map item (a last_validated is behind the HEAD commit date).
• A landed change contradicts a tracked R/I in the context-map — a requirement is now wrong, an invariant is now broken, or a known-unknown has been resolved. This is premise-freshness lifted to the persistent tracker.
• A walk surfaces an unknown-unknown that, once filed, contradicts an existing Requirement or Invariant in AGENTS.md.

On a staleness trigger:

1. Run tracker_fresh.sh <context-map-instance.ncl> to identify stale items and their hydration_source pointers.
2. For each stale hydration_source: read the corresponding AGENTS.md section and compare against the current state.
3. If drift is tactical (the item's signpost has not fired; the item is still valid, just needs its last_validated updated): update last_validated in the context-map and continue.
4. If drift is strategic (the item's signpost HAS fired — a requirement is contradicted by reality, or an unknown is resolved): this is a Strategic Escalation (ambient.md §Planning Invariants). Emit an ESCALATION block, update the live tracker and the AGENTS.md persistent anchor via /orient refresh, and halt for human review.

Reorientation scope. A tactical re-validation (step 3) does not require re-running the full eight-phase workflow — it is a targeted tracker update. A strategic reorientation (step 4) re-runs at minimum MAP (diff-scoped) and ELICIT, and presents the corrected R/I/U sections at RECONCILE for human confirmation before writing back to AGENTS.md.

Staleness is not an error. A stale item is a signal, not a failure. The failure is ignoring the signal — carrying a stale, unverified requirement forward into task work (rules.md §7: reconstruct, don't recall).

---

Tier Economy

Phase	Tier	Rationale
0 BOUND	Architect	Bounding judgment; goal-fit stakes highest here
1 ESTABLISH	Mechanical	Pure bootstrap execution; no judgment
2 MAP	Cheap agents	Structure survey; no goal-fit judgment
3 SURVEY	Cheap agents	Enumeration and relevance projection
4 ELICIT	Architect + Human	Goal-fit is not self-attestable; human seam
5 NEST	Architect	Structural coupling judgment
6 AUTHOR	Architect	Contract-conformant draft
7 RECONCILE	Human	Persistent layer mutates only here

---

See Also

• /boundary — the authority for the IBC sufficiency conditions (phase 0) and the AGENTS.md contract (phase 6).
• /campaign — for multi-workstream orchestration after orientation is complete.
• rules.md — the governing Prime Invariants every AGENTS.md references.
• ambient.md — the always-on principles the AGENTS.md hierarchy anchors to.
• ledger/gate/tracker_fresh.sh — the freshness gate; checks whether context-map last_validated fields are current against HEAD. Fresh→0, Stale→1.
• ledger/contracts/context_map.ncl — the live tracker carrier contract; hydration_source field records the AGENTS.md anchor a hydrated item came from.
• skills/orient/tracker_freshness.ncl — the Nickel functional core: is_fresh and stale_items predicates.