@sleepy_panda_srl/portulan 0.1.3 → 0.2.0

package/core/templates/handoff.md

@@ -1,25 +1,23 @@
 # Template — Handoff
 
-> A **handoff** records a decision and its *why*, so the next agent — or the next context window —
-> inherits the reasoning and not just the result. Write one **at the close of every session** — that part
-> is not conditional, and short is fine — and also when compacting, when hitting an iteration cap, or when
-> passing work across a persona boundary. Decisions without their why get silently re-litigated or
-> reversed. **Drop any section that has nothing to say** — the date and the decisions-with-why are the
-> only irreducible parts, and a handoff of five lines is a valid handoff. The date lives in the
-> **filename**, leading, in ISO form — `YYYY-MM-DD-{slug}.md` — not in a field inside the document: that
-> is what a gate checks and what makes the series sort chronologically. That is what keeps the
-> every-session rule from becoming ceremony: it scales down here, inside the artifact, rather than by
-> being skipped. _(Provenance: Cognition — handoffs record decisions and rationale. The every-session rule
-> and why it is binary rather than discretionary are in `../operating/loop.md`.)_
+> A **handoff** carries the work still open, so the next agent — or the next context window — starts
+> from where things stand rather than from the transcript. Write one when a session ends with work not
+> committed and pushed, when compacting, when hitting an iteration cap, or when passing work across a
+> persona boundary. Work that is committed carries its own why, in its commit message, so a handoff
+> says nothing the diff or a commit already says. **Drop any section with nothing to say**; five lines
+> is a valid handoff. The date leads the **filename**, in ISO form — `YYYY-MM-DD-{slug}.md` — because
+> that is what a gate checks and what sorts the series. _(Provenance: Cognition — handoffs record
+> decisions and their rationale. When one is owed, and why the commit carries the rest:
+> `../operating/loop.md`.)_
+>
+> **The commit a change lands in:** a subject that says what changed, in the present tense and under 72
+> characters; a blank line; a body of a few lines that says why, and what was rejected when that matters.
 
 ---
 
 # Handoff — {task / thread}
 
-**State.** {where things actually are right now — done, in-progress, blocked — in a few lines.}
-
-**Decisions + why.** {each decision taken and the reason it was taken; the reasons are the payload.}
-- {decision} — because {why}; alternatives considered: {…}.
+**State.** {where things stand: what is done and committed, what is in progress and uncommitted.}
 
 **Open questions.** {what is undecided, and who decides it — flag the human-owned ones.}
 
@@ -27,3 +25,18 @@
 
 **Recoverability.** {anything left in a partial state, and how to make it safe; see
 `../operating/safety.md`.}
+
+---
+
+_A filled one, for a session that stopped mid-change:_
+
+# Handoff — retry the flaky upload test
+
+**State.** The retry wrapper is written and its unit test passes; it is stashed, not committed, because
+the integration suite still fails once in about ten runs.
+
+**Open questions.** Whether three attempts is the right cap — the owner of the upload service decides.
+
+**Next action.** `git stash pop`, run the integration suite twenty times, and read the one failure's log.
+
+**Recoverability.** Nothing was pushed; dropping the stash loses only the wrapper.

package/core/templates/memory-entry.md

@@ -8,6 +8,7 @@
 ---
 
 **type:** rule | decision | reference | glossary
+**dated:** {YYYY-MM-DD — the day this record's text last changed; an edit re-dates it. The per-record cap binds by it where the workspace declares a cutoff}
 **scope:** {the persona / repo / workspace this belongs to — memory is per-agent, not global}
 **provenance:** {one of the two forms below — a rule carrying neither is taste, and `doctor` rejects it}