objective-refresh

objective-refresh

Rebaseline active Objective records against ground truth. Read the objective umbrella skill first for shared vocabulary, storage layout, required headings, and Semantic Update rules; this skill does not restate them.

One absolute governs every run:

• Never commit. No git commit, no staging. Edits stay uncommitted in the worktree and the report says what changed; the user decides how to land it.

Closure is the default when done — step 10 owns the inline-close mechanics and the single hold-back condition (closure-ready).

Select targets

Selection is mechanical — never ask a scope question:

• Explicit slug(s) or path(s) → refresh exactly those. Paths must resolve under .ns/objectives/<slug>/. On a feature branch, a named slug with no branch evidence is reported not-owned rather than silently rebaselined against trunk state — unless the user clearly asked for a trunk-style rebaseline of that slug.

• No slug, feature branch → the union of slugs with committed or uncommitted Objective evidence:

  git -C "$WT" diff --name-only <trunk>...HEAD -- .ns/objectives/
  git -C "$WT" status --porcelain -- .ns/objectives/
  

  Reduce paths to slugs. Empty union → report that the branch evidences no Objective records and stop without writing.

• No slug, trunk → every active open Objective from ns objective list --names.

WT is the current working directory unless the caller names another worktree. Every git operation uses git -C "$WT"; never check out another branch. Stop if HEAD is detached (git -C "$WT" symbolic-ref --quiet --short HEAD fails). Trunk is gt trunk when available, else the repo's configured default branch; if the sources disagree, stop and ask.

Baseline. On a feature branch the baseline is git -C "$WT" merge-base <trunk> HEAD and the evidence window is <baseline>..HEAD plus uncommitted worktree state; a slug is also in scope when the user points at branch changes that contradict its claims. On trunk there is no baseline — verify against HEAD. There are no refresh commits and no commit-message markers anywhere: due-ness is content-level, so a record that already matches its verified contract yields no write.

Refresh loop

Process one slug at a time. The authoring move is a from-scratch rewrite driven by a contract — extract, verify, rewrite, diff — never paragraph patching. Frame each slug as: on a feature branch, "if this branch landed now, what should this record say on trunk?"; on trunk, "what should this record say about landed ground truth?". Use objective-update's landed-state writing semantics as the content model.

Uncommitted Objective edits are input, not a stop: worktree content, committed plus uncommitted, is the current record. Note which slugs were already dirty, for the report.

Write invariants, in addition to the never-commit absolute:

• Edit only the selected Objective directories, except for the shared Objective exceptions: mirrored edge mutations may edit counterpart frontmatter, and closing a slug inline (step 10) must propagate semantic impact to every affected edge-connected Objective per objective-close, including counterpart durable tracking and new counterpart-local Semantic Updates when warranted.
• For updates/, follow the objective umbrella skill's immutable Semantic Update rule: refreshes may add new update files, not change old ones.
• Never move, delete, rename, or recreate an Objective slug directory.

Per slug:

1. Read the record. ns objective exec read-objective <slug> --format md for deterministic inventory and closed-marker state; read objective.md, roadmap.md, and recent updates/ as source material.

2. Gather evidence over the window:

   git -C "$WT" log --oneline <baseline>..HEAD -- .ns/objectives/<slug>/
   git -C "$WT" diff <baseline>..HEAD -- .ns/objectives/<slug>/
   git -C "$WT" diff -- .ns/objectives/<slug>/
   

   On trunk, skip the range probes and verify against HEAD plus worktree state.

3. Extract the contract: durable purpose, boundaries, completion criteria, assumptions/risks, open questions; progress (done, active, parked, closure-adjacent, remaining roadmap shape); every material claim by category; and stale or suspect text that must not be carried forward as fact.

4. Verify the contract claim by claim, per Verify claims below.

5. Classify: verified (contract supported, or weakened into assumptions/open questions), stale-rebaselined (a false claim was corrected, parked, or narrowed), or skipped-unverified (important claims remain unverifiable and unsafe to rewrite without the user).

6. Rewrite objective.md from scratch when the verified contract changes durable narrative, scope, criteria, assumptions/risks, or open questions, or shows existing prose stale. Never preserve old wording by inertia.

   • Blocked Sentence is in scope (open records; step 10 owns the closure case). When the record's blocked: sentence gates on a condition the verified contract shows resolved — most commonly a named Objective that is verifiably closed — clear or reword the sentence as part of the rewrite and carry the decisive evidence into the Semantic Update. Leave it verbatim only when the evidence is ambiguous, and then say so explicitly in the report instead of silently deferring. Edges stay in place either way.

7. Rewrite roadmap.md from scratch when active work shape changes: ordered guidance, checkbox state ([ ], [~], [x] only), row notes, completion evidence, parked work.

8. Contract-diff. Compare the rewrite against the extracted contract line by line: every verified purpose, boundary, progress fact, roadmap item, assumption, open question, and parked item is present or intentionally omitted with a stated reason, and the umbrella's required headings survive. Dropped or softened meaning is a bug — fix it before moving on.

9. Re-derive orientation.md when one exists, per the umbrella's re-derivation rule; add one when the verified contract shows the Objective became orienting (its direction now binds unrelated agents). Never drop one.

10. Close when finished. If the verified contract shows the completion criteria met and no material open work, close inline per the full objective-close semantics. The closure evidence goes in the selected Objective's Semantic Update below. Report closure-ready without closing only when the Objective explicitly requires a final evidence-gathering step this refresh has not run.

    • Closing inline carries objective-close's connected-Objective propagation, not just its file mechanics. Run that skill's per-counterpart disposition procedure against each edge-connected Objective. After any frontmatter edit, run ns objective check --all and fix every structural error before continuing.

11. Append at most one timestamped Semantic Update per changed Objective when the refresh or close propagation records a meaningful finding, decision, blocker, risk change, completion event, plan change, follow-up, closure, or rebaseline. The selected Objective's update carries the decisive evidence and provenance breadcrumb below; each affected counterpart gets its own update describing only that counterpart's impact. Existing updates remain immutable.

    Provenance: objective-refresh basis target=<target-sha-or-ref> from=<merge-base-or-trunk-HEAD>
    

    No meaningful durable change, or a contract you cannot trust? No filler: leave the slug unchanged and report skipped-ambiguous / skipped-unverified.

Verify claims

Verification is forensic: presume every material claim false until evidence proves it.

Material claims: source paths, symbols, commands, packages, workflows, PRs, branches, tests, docs, ADRs, Objective slugs, status words, scope boundaries, non-goals, dependencies, risks, assumptions, completion evidence, roadmap rationale. Status words include "exists", "gone", "current", "already", "now", "still", "remaining", "implemented", "deleted", "covered", "tested", "passing", "legacy", "core", "salvaged", "owned", and "deferred".

Match each claim to a probe:

• paths/files: git -C "$WT" ls-files, test -e, or find scoped to the claimed directory;
• symbols/commands/types: rg --fixed-strings or a narrow regex, --help/schema output;
• negative claims ("deleted", "no X"): scoped absence evidence — a search showing X is gone;
• "implemented"/"covered"/"tested": source plus test probes; run targeted tests only when the claim depends on passing behavior;
• PR/CI/review state: gh/Graphite evidence;
• ownership/deferral: git diff/log/Objective evidence that the named owner or deferred target exists.

PR evidence is a material claim: verify numbers, review/CI status, and merge state before carrying it forward, wording status per the umbrella skill's Objective PR evidence convention. Keep PR bullets to material Objective PRs; do not normalize unrelated historical PR mentions just to satisfy it.

A claim that cannot be verified cheaply never stays as fact: convert it to an explicit assumption/open question with the missing-evidence scope, park or narrow the roadmap item, or classify the slug skipped-unverified. When evidence contradicts the record, correct the contract before rewriting and say so in the Semantic Update. Never let a Semantic Update vouch for unverified prose.

Report

Return a compact report: worktree, branch, trunk, target SHA; per slug — baseline, action (wrote, closed, noop, skipped-ambiguous, skipped-unverified, closure-ready, not-owned), key claims verified/corrected/still-assumed, files edited and new Semantic Update filenames; for every edge-connected Objective of a closed slug, its propagation disposition, reason, files changed, and any newly closure-ready state; slugs that were already dirty; confirmation that the never-commit absolute and all write invariants held, and that any closure-ready (rather than closed) cites the Objective's explicit final evidence-gathering requirement.

Done when an immediate rerun would modify nothing — every refreshed record already matches its verified contract.