Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions .agents/skills/ln-consult/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Start the assessment with 2-4 bullets naming:
- the active frontier item or nearby priority
- volatile state or manual follow-up from handoff
- the main open risk
- the cheapest tracer bullet that would score on proof of life, invariants, or uncertainty retirement (see `docs/praxis/ln-skills.md` §Tracer-bullet sequencing)
- the inherited **certainty posture** for the active frontier (see `docs/praxis/ln-skills.md` §Operating posture). Under `proving`, also name the cheapest tracer bullet that would score on proof of life, invariants, or uncertainty retirement. Under `earned`, name the closure target (what dual shape, ambiguity, or open decision does the next move close?).

## Work-type classification

Expand Down Expand Up @@ -77,11 +77,15 @@ Only recommend the bounded or direct-build exceptions when all of these are true

Only recommend the bounded serial exception when those same conditions hold and the next several commit-sized steps are obvious enough to queue without fresh planning.

## Tracer-bullet override
## Posture-aware route override

When several routes fit the work, prefer the one that fires the **tracer bullet that tells you the most**. A tracer-bullet slice scores on three convergent axes (see `docs/praxis/ln-skills.md` §Tracer-bullet sequencing): proof of life, invariants, uncertainty. The best next slice scores on more than one.
When several routes fit the work, the preferred route depends on the active frontier's certainty posture (see `docs/praxis/ln-skills.md` §Operating posture).

Given the repo's pre-release posture, attack uncertainty by building. Recommend a non-build route only when no buildable tracer bullet can carry the proof:
**Proving posture.** Prefer the route that fires the **tracer bullet that tells you the most**. A tracer-bullet slice scores on three convergent axes: proof of life, invariants, uncertainty. The best next slice scores on more than one.

**Earned posture.** Prefer the route that lands the **closure that the recent slices have been deferring**. Closure slices answer: what dual shape closes, what topology materializes, what name canonicalizes, what carrier retires, what shape locks in. If the closure target is named and a single slice can land it, route directly to `ln-scope` / `ln-build` rather than to further planning.

Under proving posture, attack uncertainty by building. Recommend a non-build route only when no buildable tracer bullet can carry the proof:

- `ln-design` — module shape itself is uncertain and any slice would lock in the wrong seam
- `ln-oracles` — verification is too uncertain to distinguish a passing slice from a wrong one
Expand Down
46 changes: 23 additions & 23 deletions .agents/skills/ln-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,23 @@ Archive deeper history to `docs/archive/PLAN_HISTORY.md` instead of keeping it l

Treat frontier items as branch-sized work, not commit-sized work. If one frontier item will unfold as several consecutive verified slices, keep that chain in a `Mode: chain` scope file under `memory/cards/` or in session context instead of fragmenting `memory/PLAN.md` into a commit ledger. `memory/PLAN.md` may carry at most a lightweight pointer such as `current execution pointer: memory/cards/<frontier-id>--<slug>.md`; detailed discretionary sub-slicing belongs in the scope file itself.

## Operating posture

Sequencing pressure depends on the active frontier's **certainty posture**. Read `.pi/POSTURE.md` (if present) for the project default, then check each `Active` / `Next` frontier definition for an explicit `Certainty:` override.

| Certainty | Ask | Optimize for | Reference |
| --- | --- | --- | --- |
| `proving` | What does landing this *tell us*? | information gain | [`references/proving.md`](references/proving.md) |
| `earned` | What does landing this *close*? | closure gain | [`references/earned.md`](references/earned.md) |

The posture is **per frontier**, not per project. A mostly-earned repo can carry a fresh proving seam; a settled seam can regress to proving on a new unknown. The project posture in `.pi/POSTURE.md` is only the default — annotate the frontier when it diverges.

Posture annotations are **required** on every `Active` / `Next` frontier (see the matching reference for the field set). If no posture-specific annotation applies, the frontier is not earning its slot — reshape, reclassify, or demote it.

When implementation later reveals the posture was wrong, treat that as a state transition (downgrade earned → proving, reshape the slice, route back through `ln-plan` if the frontier itself splits). Do not invent a third permanent posture.

Defensive parsing: depend primarily on `.pi/POSTURE.md`'s `certainty:` field; tolerate extra or mismatched fields rather than failing on schema drift.

## Input

The feature or project area: $ARGUMENTS
Expand Down Expand Up @@ -98,35 +115,18 @@ When the meaning, acceptance, verification, traceability, or design-doc referenc

When a frontier completes, remove it from `Sequencing`, add a terse `Recently Completed` entry, and archive older completion history if needed. Keep the definition only if it still carries live rationale for nearby work; otherwise archive/retire it.

### Epistemic horizon

If live low-confidence assumptions block downstream work, stop the plan at that boundary. Plan spikes or thinner proving frontier items, not fantasy certainty.

### Tracer-bullet sequencing

Sequencing is not only seam-driven. A good tracer-bullet frontier scores on three convergent axes (see `docs/praxis/ln-skills.md` §Tracer-bullet sequencing): **proof of life**, **invariants**, **uncertainty**. The strongest next frontier scores on more than one.

When ranking candidates, weigh:

- **blast radius** if a load-bearing assumption turns out false
- **reversibility cost** if discovered late vs early
- **validation cost** (cheap slice vs expensive end-to-end rework)
- **load-bearingness** (how many active/next frontiers depend on it)

Annotate each `Active` / `Next` frontier definition with the relevant axes when they are in play:
### Posture-dependent sequencing

- `Retires: <SPEC assumption id(s)>` — collapses the assumption by landing
- `Depends on: <SPEC assumption id(s)> (validated enough)` — assumption must be settled first
- `Blocked by: <SPEC assumption id(s)>` — load-bearing; do not start until retired
- `Lights up: <pipeline / seam>` — establishes a new end-to-end path
- `Stabilizes: <invariant id(s) or seam>` — locates or fixes structure others will aim from
Sequencing pressures and required annotation fields depend on the active frontier's posture:

**Spike exception.** Use `ln-spike` only when no buildable frontier could carry the proof. Do not insert ceremonial spikes when a tracer-bullet frontier exists.
- **Proving frontiers** → load [`references/proving.md`](references/proving.md). Covers tracer-bullet axes (proof of life, invariants, uncertainty), epistemic horizon, spike exception, reshape-don't-defer, and the `Retires` / `Depends on` / `Blocked by` / `Lights up` / `Stabilizes` annotation set.
- **Earned frontiers** → load [`references/earned.md`](references/earned.md). Covers the closure move-set (materialize, consolidate, name canonically, delete-as-progress, retire bridges, take-the-bigger-step), the "circling" recognition heuristic, sprawl guardrails, regression handling, and the `Closes` / `Materializes` / `Canonicalizes` / `Deletes/retires` / `Locks in` annotation set.

This sequencing pressure is distinct from "Epistemic horizon": that rule tells the planner to *stop* at fog; this rule tells the planner to **fire the tracer that tells you the most**.
A plan may contain a mix of postures across its `Active` / `Next` frontiers. Load both references when planning a mixed plan.

## Procedure

0. Read `.pi/POSTURE.md` if present for the project's default certainty posture. For each `Active` / `Next` frontier, check for an explicit `Certainty:` override and load the matching reference (`references/proving.md` or `references/earned.md`). Load both when the plan is mixed.
1. Read `memory/PLAN.md` if it exists. Identify existing frontier ids and retire/archive stale completed material into `docs/archive/PLAN_HISTORY.md`.
2. Read `memory/SPEC.md` if it exists. Pull only the live requirements, assumptions, decisions, and invariants that still constrain forward work.
3. Explore the codebase enough to understand real boundaries.
Expand Down
4 changes: 4 additions & 0 deletions .agents/skills/ln-plan/assets/plan-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,9 +40,13 @@
- **Name:** [Human-readable frontier name]
- **Linear:** [FE-XXX if known, or `unassigned`]
- **Kind:** [structural | bounded feature | hardening | bugfix | refactor]
- **Certainty:** [proving | earned — default inherits from `.pi/POSTURE.md`; annotate when this frontier diverges]
- **Status:** [not-started | in-progress | branch-complete | blocked | done]
- **Objective:** [what this frontier changes]
- **Why now / unlocks:** [why this belongs on the frontier and what it unlocks]
- **Posture annotations:** [required — use the field set from the matching posture reference]
- Proving: one or more of `Retires:`, `Depends on:`, `Blocked by:`, `Lights up:`, `Stabilizes:`
- Earned: one or more of `Closes:`, `Materializes:`, `Canonicalizes:`, `Deletes / retires:`, `Locks in:`
- **Acceptance:** [observable frontier-level outcome]
- **Verification:** [inner / middle / outer summary]
- **Cross-cutting obligations:** [optional: subsystem / invariant / verification-layer obligations this frontier must preserve or establish]
Expand Down
69 changes: 69 additions & 0 deletions .agents/skills/ln-plan/references/earned.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Planning posture: earned

Load this reference when the active frontier item declares `Certainty: earned`, or when the project's `.pi/POSTURE.md` declares `certainty: earned` and the frontier inherits.

## Objective function

Optimize for **closure gain**. The next frontier should *land and lock in* something the codebase has already proved out. Landing is valuable when it eliminates a dual shape, hardens a settled decision into topology, consolidates the lexicon, or retires an obsolete carrier.

This is not "proving-posture sequencing with bigger steps." The decision kernel changes. The planner is no longer asking *"what does landing this tell us?"* — it is asking *"what does landing this close?"*

## Closure move-set

- **Materialize** — make a settled architectural decision visible in topology: file or directory placement, sub-tree split per [AGENTS.md](../../../../AGENTS.md) §fractal sub-tree pattern, or a topology README that locks a SPEC decision to a directory.
- **Consolidate** — bring scattered cognates of the same concept into one canonical site.
- **Name canonically** — collapse aliases, near-synonyms, or drift terms to one term; update callers, docs, and tests in the same slice.
- **Delete-as-progress** — retire obsolete code paths, fixtures, dummy data, compatibility shims, and superseded docs. Deletion is a first-class closure outcome, not janitorial overflow.
- **Retire bridges / aliases / dual paths** — under `migration: free-rewrite`, eliminate adapters, shims, and expand/contract scaffolds that have outlived their crossing. The migration scheme is not the system. (See `~/.pi/agent/APPEND_SYSTEM.md` §bridge-as-permanence.)
- **Take the bigger step** — landing a multi-file or multi-layer closure in one slice when the thinness instinct is producing redundant proof rather than closure.

## Required annotation fields

Every `Active` / `Next` frontier under earned posture must carry at least one of:

- `Closes: <ambiguity / dual shape / open decision>` — what becomes no-longer-open after landing
- `Materializes: <decision id / invariant / sub-tree>` — what gets embedded into topology
- `Canonicalizes: <term / API / location>` — what becomes the single canonical site
- `Deletes / retires: <code path / fixture / doc / bridge>` — what goes away
- `Locks in: <invariant / contract / shape>` — completion test for the closure

`Locks in` is the completion test, not the action: it answers *"what is true after this lands that was previously open?"*

## Recognition heuristic: circling

You are circling, not landing, when:

- Each new slice attaches an incremental proof to changes whose meaning is already established.
- The slice's tests rephrase what previous slices already showed.
- The planner is still maximizing tracer axes (`Lights up`, `Stabilizes`, `Retires`) on a seam where nothing material is unknown.
- "Caution" is the planner's stated reason, but no specific risk can be named that would shift the next move.

When this pattern appears, switch posture on the frontier and plan the closure move that the proving slices have been deferring.

## Guardrails

The earned posture is not a license for sprawl. Closure expands the slice *within* a defined scope; it does not expand the scope.

- **Stay inside one named seam or frontier.** "Take the bigger step" widens the work within a defined boundary; it does not redraw the boundary.
- **Name the specific closure target** in the frontier definition. "Tidy up X" is not a closure target; "collapse the dual `Foo` shapes to the `Foo` defined at `src/.../foo.ts`" is.
- **Declare touched paths** at the scope-card layer with the same discipline as proving-mode slices. Bigger does not mean undeclared.
- **Do not auto-implement adjacent work** because it would be "symmetric." Name adjacent work in the plan; let it earn its own frontier.
- **Materialization is not ritual.** Topology READMEs and fractal sub-tree splits only fire when (a) the seam is already understood, (b) the structure carries real architectural meaning, and (c) the change reduces ambiguity or drift. Otherwise it is structural theatre.

## Regression: earned → proving

When implementation reveals a real unknown that the closure depended on, do **not** invent a third posture mode. Transition the frontier:

1. Downgrade the frontier (or the active slice within it) to `Certainty: proving`.
2. Reshape the slice as a tracer that retires the new unknown.
3. If the unknown forces the frontier itself to split or reorder, route back through `ln-plan`.

The transition is the honest move; carrying earned posture over fog is the dishonest one.

## Boundary with adjacent skills

`ln-plan` owns closure as **intent**: what must be closed, which dual shapes must disappear, where topology and lexicon must harden, which bridges retire.

`ln-refactor` owns closure as **safe mechanics**: when an earned frontier's execution is principally restructuring, the refactor plan sequences tiny behavior-preserving commits to land it.

`ln-sync` owns closure as **canonical garbage collection**: stale docs, exhausted scope cards, derivative artifacts the planner is already done with. Closure work that is part of a frontier's definition of done belongs in `ln-plan`; cleanup of finished artifacts belongs in `ln-sync`.
56 changes: 56 additions & 0 deletions .agents/skills/ln-plan/references/proving.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Planning posture: proving

Load this reference when the active frontier item declares `Certainty: proving`, or when the project's `.pi/POSTURE.md` declares `certainty: proving` and the frontier inherits.

## Objective function

Optimize for **information gain**. The next frontier should *tell you the most* about what is still unknown. Landing is valuable when it falsifies, retires, or locates a load-bearing belief — not when it merely produces visible output.

## Tracer-bullet sequencing

A good tracer-bullet frontier scores on at least one of three convergent axes:

- **Proof of life.** Landing it lights up an end-to-end path that did not exist.
- **Invariants.** Landing it locates or stabilizes a seam that future slices will aim from.
- **Uncertainty.** Landing it retires a load-bearing assumption from `memory/SPEC.md` §Assumptions.

The strongest next frontier scores on more than one axis. Prefer a slice that does several at once over one that maximizes a single axis.

When ranking candidates, weigh:

- **blast radius** if a load-bearing assumption turns out false
- **reversibility cost** if discovered late vs early
- **validation cost** (cheap slice vs expensive end-to-end rework)
- **load-bearingness** (how many active/next frontiers depend on it)

## Required annotation fields

Every `Active` / `Next` frontier under proving posture must carry at least one of:

- `Retires: <SPEC assumption id(s)>` — collapses the assumption by landing
- `Depends on: <SPEC assumption id(s)> (validated enough)` — assumption must be settled first
- `Blocked by: <SPEC assumption id(s)>` — load-bearing; do not start until retired
- `Lights up: <pipeline / seam>` — establishes a new end-to-end path
- `Stabilizes: <invariant id(s) or seam>` — locates or fixes structure others will aim from

If none of these apply, the frontier is not earning its slot under proving posture. Either reshape it, demote it to `Horizon`, or reclassify — it may actually be earned-posture work mislabelled as proving.

## Epistemic horizon

If live low-confidence assumptions block downstream work, **stop the plan at that boundary**. Plan spikes or thinner proving frontier items, not fantasy certainty. Sequencing past fog is the most expensive form of premature commitment.

## Reshape, don't defer

If an assumption blocks a slice, reshape the slice before switching to study. A tracer bullet that breaks when the assumption is wrong almost always beats a study step in this codebase.

"High-impact" means the assumption being false would force rework across more than the slice — invalidating queued cards, changing the chosen module shape from `ln-design`, or forcing a different frontier-level sequencing decision.

## Spike exception

Use `ln-spike` only when no buildable frontier could carry the proof more cheaply — a third-party API contract, vendor performance characteristic, or research-grade unknown. Do not insert ceremonial spikes when a tracer-bullet frontier exists.

## Fire the tracer that tells you the most

Under proving posture, attack uncertainty by building. Spikes, design passes, and prototypes are escape hatches; the default is a slice whose landing falsifies the load-bearing belief.

This sequencing pressure is distinct from the **Epistemic horizon** rule above. Horizon tells the planner to *stop* at fog; this rule tells the planner to **fire the tracer that retires the next fog patch**.
Loading
Loading