pcode 0.1.5__tar.gz → 0.1.7__tar.gz

{pcode-0.1.5 → pcode-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pcode
-Version: 0.1.5
+Version: 0.1.7
 Summary: Terminal-native AI coding agent with background jobs, parallel worktrees, forkable sessions, and multi-model support
 Project-URL: Homepage, https://github.com/cruxwell/pcode
 Project-URL: Documentation, https://cruxwell.github.io/pcode/

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/app.py

@@ -554,15 +554,15 @@ class PreviewApp:
         if self.runtime.session:
             self.replay()
             return
-        from pcode.diagnostics import redact
+        from pcode.diagnostics import strip_controls
 
         tree = self.runtime.tree
         with self.transcript.restore():
             for node_id in tree.path(tree.active):
                 node = tree.nodes[node_id]
-                self.transcript.user(redact(node.prompt))
+                self.transcript.user(strip_controls(node.prompt))
                 if node.response:
-                    self.transcript.events((Message(redact(node.response)),))
+                    self.transcript.events((Message(strip_controls(node.response)),))
         self.activity.plan = tree.nodes[tree.active].plan if tree.active else []
 
     def aside_changed(self, aside) -> None:
@@ -1227,14 +1227,24 @@ class PreviewApp:
         self.transcript.syntax_gallery()
 
     def theme(self, argument: str) -> None:
-        self.transcript.theme = argument or (
-            "light" if self.transcript.resolved_theme == "dark" else "dark"
-        )
-        self.persist_defaults(theme=self.transcript.theme)
-        selected = self.transcript.theme
-        if selected == "auto":
-            selected += f" ({self.transcript.resolved_theme})"
-        self.transcript.flash(f"Theme: {selected}.")
+        """Pick and save a palette; bare `/theme` flips it for this session only.
+
+        Saving the flip would pin every later session to it, and with it turn
+        off following the terminal's light/dark switches.
+        """
+        theme = argument or ("light" if self.transcript.resolved_theme == "dark" else "dark")
+        self.transcript.theme = theme
+        if not argument:
+            message = f"{theme} for this session; /theme {theme} saves it"
+        else:
+            self.persist_defaults(theme=theme)
+            message = theme
+        if theme == "auto":
+            message += f" ({self.transcript.resolved_theme})"
+            if self._appearance is not None:
+                # The detected value may be stale; the answer repaints if it differs.
+                self._appearance.refresh()
+        self.transcript.flash(f"Theme: {message}.")
         self.transcript.regenerate()
 
     def follow_appearance(self, detected: str) -> None:
@@ -1884,7 +1894,7 @@ class PreviewApp:
 
         `end` stops at that journal offset: a host sends the rest as it happened.
         """
-        from pcode.diagnostics import redact
+        from pcode.diagnostics import strip_controls
 
         saved = saved or self.runtime.session
         self.activity.plan = saved.latest_plan()
@@ -1898,9 +1908,9 @@ class PreviewApp:
             for record in saved.transcript_records(end):
                 kind = record["kind"]
                 if kind in ("turn_started", "steering"):
-                    self.transcript.user(redact(record["prompt"]))
+                    self.transcript.user(strip_controls(record["prompt"]))
                 elif kind in ("Thinking", "thinking_partial"):
-                    self.transcript.thinking(redact(record["text"]).rstrip("\n") + "\n\n")
+                    self.transcript.thinking(strip_controls(record["text"]).rstrip("\n") + "\n\n")
                 elif kind == "CacheBust":
                     continue  # Kept in the journal; live runs show it in the footer.
                 elif kind == "EditCompleted":
@@ -1912,21 +1922,21 @@ class PreviewApp:
                     self.transcript.tool_result(
                         ToolSummary(
                             record["name"],
-                            redact(record["detail"]),
+                            strip_controls(record["detail"]),
                             record.get("failed", False),
                             record.get("call_id", ""),
                             record.get("elapsed_seconds"),
-                            redact(record.get("error", "")),
-                            redact(record.get("command", "")),
-                            result=redact(result) if isinstance(result, str) else None,
+                            strip_controls(record.get("error", "")),
+                            strip_controls(record.get("command", "")),
+                            result=strip_controls(result) if isinstance(result, str) else None,
                             outcome=record.get("outcome", ""),
                             parent_call_id=record.get("parent_call_id", ""),
-                            purpose=redact(record.get("purpose", "")),
+                            purpose=strip_controls(record.get("purpose", "")),
                             execution=record.get("execution", ""),
                         )
                     )
                 elif kind in ("Message", "partial"):
-                    self.transcript.events((Message(redact(record["markdown"])),))
+                    self.transcript.events((Message(strip_controls(record["markdown"])),))
                     if kind == "partial":
                         self.transcript.warning("[Partial output from an interrupted run]")
 
@@ -2709,6 +2719,9 @@ def main() -> None:
         "hosts",
     )
     parser.add_argument("--hosts", action="store_true", help="List running session hosts and exit")
+    parser.add_argument(
+        "--json", action="store_true", help="With --hosts: one JSON array, for scripts and plugins"
+    )
     host_kinds = ("all", "stale", "idle")
     parser.add_argument(
         "--kill-hosts",
@@ -3179,6 +3192,8 @@ def _run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
         parser.error("--fork cannot be combined with --attach")
     if args.compact and not args.sessions:
         parser.error("--compact applies to --sessions")
+    if args.json and not args.hosts:
+        parser.error("--json applies to --hosts")
     if args.print:
         if args.theme_preview or args.sessions:
             parser.error("--print cannot be combined with --theme-preview or --sessions")
@@ -3225,6 +3240,13 @@ def _run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
         if args.kill_hosts:
             _kill_hosts(args.kill_hosts, entries, code)
             return
+        if args.json:
+            import json
+
+            # A contract for callers such as the Obsidian bridge: add keys, never rename.
+            keys = ("id", "session_id", "state", "workspace", "title", "last_prompt", "attached")
+            print(json.dumps([{key: getattr(entry, key) for key in keys} for entry in entries]))
+            return
         for entry in entries:
             print(f"{entry.id}  {host_row(entry, None, code=code).strip()}")
         if not entries:

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/appearance.py

@@ -144,6 +144,13 @@ class AppearanceWatch:
             self.suspended = False
             if enabled:
                 self.enabled = _write_all(self.fd, ENABLE_REPORTS)
+                # A switch while the other program had the terminal went unseen.
+                self.refresh()
+
+    def refresh(self) -> None:
+        """Ask for the background now; the answer arrives as input like any other."""
+        if self.enabled and not self.suspended:
+            _write_all(self.fd, QUERY_BACKGROUND)
 
     async def query(self) -> None:
         for delay in QUERY_DELAYS:
@@ -155,6 +162,9 @@ class AppearanceWatch:
         if self.fd is None or not _isatty(self.fd) or os.environ.get("TERM") == "dumb":
             return
         self.enabled = _write_all(self.fd, ENABLE_REPORTS)
+        # The startup probe is skipped when input is already waiting, leaving a
+        # guess from COLORFGBG that only a later switch would otherwise correct.
+        self.refresh()
         reader = self.reader if self.reader is not None else desktop_reader()
         pending = None
         try:

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/aside_ui.py

@@ -588,8 +588,7 @@ class AsideBrowser:
     def links(self) -> list[Link]:
         """URLs in the selected thread's questions and answers, oldest first.
 
-        From the raw text, as `/links` reads the conversation: redaction would
-        cut a URL holding a token short, and the browser would get the stub.
+        From the raw text, as `/links` reads the conversation.
         """
         found: dict[str, Link] = {}
         for aside in self.current():

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/controller.py

@@ -905,7 +905,7 @@ class SessionController:
         registry = getattr(self.runtime, "jobs", None)
         if registry is None:
             return []
-        from pcode.shell import REDUCED_SHELL_OUTPUT, result_projection
+        from pcode.shell import REDUCED_SHELL_OUTPUT
 
         finished = registry.take_announcements("ui", job_id)
         for job in finished:
@@ -919,7 +919,7 @@ class SessionController:
                 failed=job.stopped or job.exit_code != 0,
                 elapsed_seconds=job.elapsed,
                 command=command_text(job.command),
-                result=command_text(result_projection(result)),
+                result=command_text(result),
                 purpose=command_text(job.purpose),
             )
             saved = getattr(self.runtime, "session", None)
@@ -3451,7 +3451,7 @@ class SessionController:
 
     async def merge_thread(self, thread: str) -> None:
         """Add a side thread to the conversation tree where it was asked."""
-        from pcode.diagnostics import redact
+        from pcode.diagnostics import strip_controls
 
         follows = self.check_bridge(thread)
         asked = self.asides.thread(thread)
@@ -3468,8 +3468,8 @@ class SessionController:
         count = f"{len(steps)} side question{'s' if len(steps) > 1 else ''}"
         if moved:
             for question, answer, _ in steps:
-                self.view.user(redact(question))
-                self.view.show_events((Message(redact(answer)),))
+                self.view.user(strip_controls(question))
+                self.view.show_events((Message(strip_controls(answer)),))
             self.view.note(
                 f"Merged {count} into the conversation, which continues from the last answer."
             )
@@ -3481,7 +3481,7 @@ class SessionController:
 
     async def summarize_thread(self, follows: Aside, instructions: str) -> None:
         """Add a summary of `follows`'s thread to the conversation, and show it."""
-        from pcode.diagnostics import redact
+        from pcode.diagnostics import strip_controls
 
         asked = self.asides.thread(follows.thread)
         questions = [aside.question for aside, _ in exchanges(asked, follows.reply.messages)]
@@ -3489,8 +3489,8 @@ class SessionController:
         summary = await self.runtime.summarize_aside(follows.reply, request, instructions)
         follows.bridged = "summarized"
         self.view.aside_changed(follows)
-        self.view.user(redact(request))
-        self.view.show_events((Message(redact(summary)),))
+        self.view.user(strip_controls(request))
+        self.view.show_events((Message(strip_controls(summary)),))
 
     def aside_completions(self, argument: str):
         """Complete a `$MODEL` word in `/btw` arguments from the /model catalog.

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/conversation_tree.py

@@ -113,11 +113,11 @@ class ConversationTree:
 
     def rows(self) -> list[tuple[tuple[str | None, bool], str]]:
         """Depth-first user/edit and assistant/continue rows, with stable IDs."""
-        from pcode.diagnostics import redact
+        from pcode.diagnostics import strip_controls
         from pcode.ui import plain
 
         def excerpt(text):
-            return plain(redact(" ".join(text.split())), 100)
+            return plain(strip_controls(" ".join(text.split())), 100)
 
         rows = [
             ((None, False), "Conversation start" + (" ← active" if self.active is None else ""))

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/delegation.py

@@ -39,7 +39,6 @@ from pcode.planning import PlanSnapshot
 from pcode.preferences import SETTINGS, load_preferences
 from pcode.retries import RequestCheckpoint
 from pcode.runtime import ToolStarted, ToolSummary
-from pcode.shell import result_projection
 from pcode.tool_display import (
     COMMAND_TOOLS,
     assignment,
@@ -208,9 +207,6 @@ async def stream_child_activity(_ctx, events):
             detail, failed = result_detail(
                 name, args, event.part.content, outcome, stored_source(args, called)
             )
-            content = (
-                result_projection(event.part.content) if name == "shell" else event.part.content
-            )
             child = ToolSummary(
                 name,
                 detail,
@@ -219,8 +215,8 @@ async def stream_child_activity(_ctx, events):
                 elapsed_seconds=max(0, monotonic() - started),
                 command=invocation(name, args),
                 purpose=stated_purpose(args),
-                error=command_error(content) if failed and name in COMMAND_TOOLS else "",
-                result=capture(content),
+                error=command_error(event.part.content) if failed and name in COMMAND_TOOLS else "",
+                result=capture(event.part.content),
                 run_id=parent.run_id or "",
                 outcome=outcome,
                 parent_call_id=parent_id,

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/diagnostics.py

@@ -44,7 +44,17 @@ _ASSIGNMENT = re.compile(
 )
 
 
+def strip_controls(text: str) -> str:
+    """Drop control characters other than newline and tab."""
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+
+
 def redact(text: str) -> str:
+    """Best-effort credential removal for error reports and text sent off the machine.
+
+    Not for the screen: the model has already seen what pcode displays, and
+    keyword matching rewrites ordinary code.
+    """
     for name, value in os.environ.items():
         if len(value) >= 8 and re.search(r"TOKEN|SECRET|PASSWORD|API_KEY|ACCESS_KEY", name):
             text = text.replace(value, "[redacted]")
@@ -52,7 +62,7 @@ def redact(text: str) -> str:
     text = re.sub(r"(?i)(https?://)[^/\s@]+@", r"\1[redacted]@", text)
     text = _TOKEN.sub("[redacted]", text)
     text = _ASSIGNMENT.sub(r"\1[redacted]", text)
-    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+    return strip_controls(text)
 
 
 # Enough for a deep cause chain through the agent graph, small enough that a

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/edit_preview.py

@@ -15,7 +15,7 @@ from pydantic_ai.messages import (
 )
 from pydantic_core import from_json
 
-from pcode.edits import MAX_SOURCE, edit_text, sensitive_path
+from pcode.edits import MAX_SOURCE, edit_text
 from pcode.runtime import EditPreview
 
 
@@ -88,15 +88,11 @@ class StreamingEditPreview:
             return clear + self._code_preview(index, partial, complete)
         path = complete.get("path")
         # Never expose content until the complete path is known and checked.
-        permitted = isinstance(path, str) and not sensitive_path(path)
+        permitted = isinstance(path, str)
         if permitted:
             try:
                 resolved = (self.root / path).resolve()
-                permitted = (
-                    not Path(path).is_absolute()
-                    and resolved.is_relative_to(self.root)
-                    and not sensitive_path(str(resolved.relative_to(self.root)))
-                )
+                permitted = not Path(path).is_absolute() and resolved.is_relative_to(self.root)
             except OSError, ValueError, RuntimeError:
                 permitted = False
         if not permitted:

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/edit_transcript.py

@@ -74,7 +74,7 @@ MARKDOWN_SUFFIXES = (".md", ".markdown")
 
 
 def created_markdown(change: EditCompleted) -> str | None:
-    """A new Markdown file's redacted source, to show rendered rather than as a diff.
+    """A new Markdown file's sanitized source, to show rendered rather than as a diff.
 
     Every line of a created file is an addition, so the `+` column says
     nothing and the raw source buries the document. The patch is the only

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/edit_ui.py

@@ -747,7 +747,7 @@ class DiffBrowser:
         terms = self.terms()
         if self.scope == "paths":
             return all(fuzzy_match(term, change.path.casefold()) for term in terms)
-        # Match the redacted text, so redaction cannot hide the row a query matched.
+        # Match the text as shown, so sanitizing cannot hide the row a query matched.
         text = "\n".join([change_heading(change), patch_text(change.patch, dedent=self.dedent)])
         return not terms or bool(matching_rows(text, terms))
 

{pcode-0.1.5 → pcode-0.1.7}/src/pcode/edits.py

@@ -11,32 +11,10 @@ MAX_SOURCE = 256 * 1024
 MAX_LINES = 4000
 MAX_PATCH = 64 * 1024
 MAX_PATCH_LINES = 400
-_SENSITIVE = re.compile(
-    r"(?i)(secret|token|password|credential|api.?key|private.?key|\.env|kubeconfig|"
-    r"(?:^|/)\.kube/|(?:^|/)\.aws/|\.tfvars|\.pem$|\.key$|(?:^|/)id_(?:rsa|ed25519)(?:$|\.))"
-)
-_OPEN_SECRET = re.compile(
-    r"(?i)((?:password|passwd|secret|token|api[_-]?key|authorization)[\"']?\s*[:=]\s*)"
-    r"([\"'])(.*?)(?:(?<!\\)\2|\Z)",
-    re.DOTALL,
-)
-
-
-def sensitive_path(path: str) -> bool:
-    return bool(_SENSITIVE.search(path))
 
 
 def edit_text(text: str) -> str:
-    # Redact whole strings before adding diff prefixes or clipping. A credential
-    # can span lines, and a streamed quoted value may not have its closing quote.
-    text = _OPEN_SECRET.sub(r"\1\2[redacted]\2", text)
-    text = re.sub(
-        r"(?i)((?:password|passwd|secret|token|api[_-]?key|authorization)[\"']?\s*[:=]\s*)"
-        r"[^\s\"',;}]+",
-        r"\1[redacted]",
-        text,
-    )
-    text = re.sub(r"-----BEGIN [^-]*PRIVATE KEY-----.*", "[private key redacted]", text, flags=re.S)
+    """Edit content as shown: terminal controls removed, tabs expanded."""
     return command_text(text)
 
 
@@ -44,7 +22,7 @@ _HUNK = re.compile(r"@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@")
 
 
 def patch_text(patch: str, *, dedent: bool) -> str:
-    """A stored patch as it is displayed: redacted, and dedented if asked."""
+    """A stored patch as it is displayed: sanitized, and dedented if asked."""
     text = edit_text(patch)
     return dedent_patch(text) if dedent else text
 
@@ -124,8 +102,6 @@ def change_from_record(record: dict) -> EditCompleted:
 def completed_change(path, before, after, *, existed=True, call_id="", omitted=""):
     """Build display evidence while raw snapshots are still local to execution."""
     operation = "edited" if existed else "created"
-    if sensitive_path(path):
-        return EditCompleted(call_id, "[sensitive path]", operation, omitted="Sensitive file")
     path = plain(edit_text(path), limit=None)
     if omitted or before is None:
         return EditCompleted(
@@ -139,7 +115,7 @@ def completed_change(path, before, after, *, existed=True, call_id="", omitted="
         return EditCompleted(call_id, path, operation, omitted="File exceeds preview line limit")
     if before == after:
         return EditCompleted(call_id, path, "unchanged" if existed else "created")
-    # Count actual changed source lines, even where redaction hides a change.
+    # Count actual changed source lines, even where sanitizing hides a change.
     raw = list(difflib.unified_diff(source_lines(before), source_lines(after), n=3))
     added = sum(line.startswith("+") for line in raw[2:])
     removed = sum(line.startswith("-") for line in raw[2:])
@@ -158,5 +134,5 @@ def completed_change(path, before, after, *, existed=True, call_id="", omitted="
     truncated = len(lines) > MAX_PATCH_LINES or len(patch) > MAX_PATCH
     patch = patch[:MAX_PATCH]
     if not patch:
-        omitted = "Changes hidden by redaction or newline normalization"
+        omitted = "Changes hidden by control-character or newline normalization"
     return EditCompleted(call_id, path, operation, patch, added, removed, truncated, omitted)

pcode-0.1.7/src/pcode/extensions/basic_memory/Brief format.md

@@ -0,0 +1,91 @@
+---
+type: format
+tags: [brief]
+---
+# Brief format
+
+The model reads this note before it writes or updates a **brief** or a **plan**. Edit it to change how they're written; the next update follows your version.
+
+A **brief** explains one project as it is now: what it is, where it's at, how it works, what's wrong, what's next. A **plan** is a *proposed brief*: the same format, describing the project as it would be once the change is implemented.
+
+## The rules
+
+1. **One note answers the question.** Someone who missed every session (the newcomer test) must understand from the brief alone what the project is, what state it's in, how it works, what's broken and what to do next.
+2. **Rewrite, don't append.** The body is always the current truth. Only the *Log* is append-only.
+3. **Update when it matters.** A milestone, a decision, a new or fixed shortcoming, a changed next step. Not routine progress.
+4. **Evidence, not memory.** Check claims against the code, git and sessions. When they disagree with the brief, change the brief, and cite what you used in `sources`.
+5. **Change only what's out of date.** Edit the sections that are wrong and leave the rest exactly as it is. The user edits these notes too.
+6. **Never change `priority`** unless the user asks. Only create a brief when the user asks (`/brief new`).
+7. **No secrets.** Don't open files that hold credentials (`.env`, `*secret*`, token files, kubeconfigs), and never copy a token, key or password into a note. Name the file instead.
+
+## Where things live
+
+- Briefs: `briefs/<Name>.md`. The name is the project (`coder-pydantic`, `Repo onboarding`).
+- Plans: `briefs/Plan — <project> — <title>.md`, with `project:` linking the brief they change.
+- This vault holds one org. Never link notes in another org's vault.
+
+## Scope: briefs, sessions and code are many-to-many
+
+- A brief covers a **scope** you name: a repo, a subsystem, an initiative across repos. It's recorded in `scope:` (one line) and `dirs:` (org-relative directories).
+- One session can change several briefs, or none. Update every brief it materially changed, and name them in your reply. Ask only when it's unclear whether a change belongs in a brief at all.
+- To find a project's brief, match the current directory against the briefs' `dirs`.
+- A brief can be built from the code itself (README, layout, main modules, git history), from sessions, or from both.
+- When a brief outgrows its budgets, propose splitting it as a plan.
+
+## Properties
+
+| Key | Brief | Plan | Notes |
+|---|---|---|---|
+| `type` | `brief` | `plan` | |
+| `state` | `live` | `proposed` → `approved` → `implemented` (or `dropped`) | |
+| `cssclasses` | none | `[proposed]`, `[approved]` or `[implemented]`, matching `state` | Colours the note in Obsidian |
+| `project` | | link to the brief, e.g. `"[[briefs/coder-pydantic]]"` | None for a brand-new project |
+| `scope` | one line | one line | What the note covers |
+| `dirs` | org-relative directories the note covers | same | How a session finds its brief |
+| `health` | `on-track`, `at-risk` or `blocked` | same | |
+| `stage` | `idea`, `design`, `prototype`, `beta` or `shipped` | the stage after the change | |
+| `priority` | 1 (highest) to 5 | | Set by the user |
+| `tldr` | one sentence | one sentence | Shown on the dashboard |
+| `next` | the single next action | same | Shown on the dashboard |
+| `reviewed` | date the whole brief was last checked | | Briefs only |
+| `created` | | date the plan was written | Plans only |
+| `plans` | links to open plans | | |
+| `sources` | session IDs, plus code paths or commit ranges | same | |
+
+Properties are YAML, and one bad value breaks the whole block: Obsidian then shows it as raw red text instead of properties. Wrap every free-text value (`scope`, `tldr`, `next` and each `sources` item) in single quotes, doubling any `'` inside: `tldr: 'Checks the org''s code: once per ticket'`. Unquoted, a `: ` anywhere or a leading `` ` ``, `#`, `*`, `[`, `{`, `&`, `!`, `|`, `>`, `%` or `@` breaks it.
+
+## Sections
+
+| Section | Answers | Budget |
+|---|---|---|
+| **TL;DR** (`> [!abstract]`) | What · Where · Next (a plan adds the cost to build) | 3 lines |
+| **Where it's at** | Status line, then what changed since the last review. A plan says what's wrong with today and what's been decided. | ≤ 6 bullets |
+| **What it does** (*What it will do*) | What a user gets, in their terms | ≤ 6 bullets |
+| **How it works** (*How it will work*) | A Mermaid diagram, the pieces, key decisions each with *why* and *rejected* alternatives, and **How we know it works** | 1 diagram, ≤ 12 bullets |
+| **Shortcomings & risks** | A table: problem, evidence, impact (🔴 🟠 🟡). In a plan, a mitigation instead of evidence. | ≤ 8 rows |
+| **Next steps** | Ordered checkboxes, each with *done when* | ≤ 6 |
+| **Open questions** | `> [!question]` callouts, each with *My lean* and an empty `**Answer:**` line | ≤ 5 |
+| **Log** | Dated one-liners, newest first, linking sessions and plans | Append-only |
+| **Sources** | Collapsed `> [!info]-` callout | |
+
+Put retired decisions in a collapsed `> [!note]-` callout with the reason, not in the body. Briefs with open plans show them in a `> [!todo] Open plans` callout under the TL;DR.
+
+## Plans
+
+- A plan starts with a banner: `> [!todo] PROPOSED · not implemented`, saying it describes the project as it would be after the change.
+- For a change to an existing project, write only the sections that change. Other sections say *Unchanged, see [[brief]]*.
+- Transitions:
+
+| To | The plan | The brief |
+|---|---|---|
+| `proposed` | Banner, `cssclasses: [proposed]` | An *Open plans* line: 📝 proposed |
+| `approved` | `state: approved`, `cssclasses: [approved]`, banner `> [!info] APPROVED · being implemented` | ✅ approved |
+| `implemented` | `state: implemented`, `cssclasses: [implemented]`, banner `> [!success] IMPLEMENTED on <date>`, linking the brief. It stays as the record of why. | The changed sections rewritten in present tense, a *Log* line, and the plan removed from *Open plans* and `plans` |
+| `dropped` | `state: dropped`, with the reason in its *Log* | Removed from *Open plans*, with a *Log* line |
+
+## Feedback from the user
+
+The user answers open questions in place and adds `> [!comment]` callouts. Their edits arrive as a diff with their next message.
+
+- **An answer:** fold it into the right section (a plan records decisions under *Where it's at*; a brief, under *How it works*), remove the question, and log it.
+- **A comment:** act on it, remove the callout, and log what changed.

pcode-0.1.7/src/pcode/extensions/basic_memory/Briefs.base

@@ -0,0 +1,50 @@
+filters:
+  and:
+    - file.inFolder("briefs")
+formulas:
+  state: 'if(note.state == "proposed", "📝 proposed", if(note.state == "approved", "✅ approved", if(note.state == "implemented", "🏁 implemented", if(note.state == "dropped", "✖ dropped", "🟢 live"))))'
+  health: 'if(note.health == "on-track", "🟢 on track", if(note.health == "at-risk", "🟠 at risk", if(note.health == "blocked", "🔴 blocked", "⚪ unknown")))'
+properties:
+  formula.state:
+    displayName: State
+  formula.health:
+    displayName: Health
+  note.tldr:
+    displayName: TL;DR
+  note.next:
+    displayName: Next
+views:
+  - type: table
+    name: Projects
+    filters:
+      and:
+        - 'type == "brief"'
+    order:
+      - note.priority
+      - file.name
+      - formula.health
+      - note.stage
+      - note.tldr
+      - note.next
+      - note.reviewed
+    sort:
+      - property: note.priority
+        direction: ASC
+  - type: table
+    name: Plans
+    filters:
+      and:
+        - 'type == "plan"'
+    groupBy:
+      property: note.state
+      direction: DESC
+    order:
+      - file.name
+      - formula.state
+      - note.project
+      - note.tldr
+      - note.next
+      - note.created
+    sort:
+      - property: note.created
+        direction: DESC

pcode-0.1.7/src/pcode/extensions/basic_memory/Home.md

@@ -0,0 +1,11 @@
+# Projects
+
+One brief per project: what it is, where it's at, how it works, what's wrong, what's next. How they're written: [[Brief format]].
+
+![[views/Briefs.base#Projects]]
+
+## Plans
+
+Proposed changes, written as the brief would read once implemented.
+
+![[views/Briefs.base#Plans]]