1 +#
Witness specification 5 +This document defines the intended Witness behavior.
6 +Implementation slice 1 discovers, validates, and explains definitions without running models.
10 +Witness runs user-configured background agents in response to Pi activity.
11 +Witness provides mechanism, while observer definitions provide policy.
12 +Witness ships no enabled observers and no templates by default.
16 +Witness does not replace Pi prompts, skills, commands, model selection, or the parent agent loop.
17 +Witness does not contain documentation, praise, feedback, verification, or activity-summary policy.
18 +Witness does not depend on another pi-ext extension.
19 +Witness may load extensions explicitly named by an observer definition.
20 +Witness must not load itself into a child runtime.
22 +##
Observer definition 24 +One observer is defined by one Markdown file with YAML frontmatter.
25 +The Markdown body is the observer system prompt.
26 +Frontmatter defines identity, triggers, context, child-agent configuration, result protocol, and delivery.
27 +Referenced files are resolved relative to the observer file unless a field explicitly defines another base.
28 +Unknown fields are validation errors.
29 +Invalid observers never partially activate.
31 +Active user observers live below the Pi agent directory in `witness/observers/`.
32 +Active project observers live in `.pi/witness/`.
33 +Reusable user templates live below the Pi agent directory in `witness/templates/`.
34 +Project definitions are read only when the project is trusted.
35 +A project observer with the same ID replaces the complete user observer definition.
36 +Definitions never deep-merge across scopes.
38 +##
Identity and templates 40 +Observer IDs are stable, unique within the resolved configuration, and safe as file-name components.
41 +A template is an inactive observer definition available to the creation UI.
42 +`/witness add <template>` copies an expanded standalone definition into an active scope.
43 +An installed observer retains no inheritance link to its template.
44 +`/witness save-template <observer-id>` copies an active observer into the user template library.
45 +`/witness create` may create an active observer, a reusable template, or both.
49 +Witness supports these trigger mechanisms:
51 +- Parent activity with debounce and maximum-wait bounds.
52 +- Parent settlement after all automatic retries, compaction retries, and queued continuation finish.
53 +- Successful observed workspace mutation followed by a quiet period.
54 +- A periodic interval.
55 +- Explicit manual execution.
56 +- Deterministic matching of raw user input.
58 +Input matching supports exact normalized values and configured regular expressions.
59 +Input triggers ignore extension-originated messages.
60 +An input trigger chooses immediate execution or execution after the resulting parent run settles.
61 +An input trigger chooses whether the matching message continues to the parent agent.
62 +Witness persists a consumed input job before returning `handled`.
63 +If durable enqueue fails, the input continues to the parent agent instead of being lost.
64 +A post-settlement input trigger records the trigger text and starting parent leaf before the parent run starts.
66 +Triggers schedule work but do not grant context or capabilities.
67 +Repeated triggers coalesce according to observer policy.
68 +Each observer has at most one running job and one replaceable pending job.
69 +Continuous activity cannot postpone a configured observer forever when a maximum wait is set.
70 +No observer runs merely because time passed when its configured evidence has not changed, except an explicit periodic trigger.
74 +Witness builds bounded context from explicitly configured sources.
75 +Supported sources include normalized parent activity, active-branch conversation, selected files, file globs, and observed tool execution evidence.
76 +Every source has an explicit or mechanical size bound.
77 +Context records preserve stable evidence IDs where later results may cite evidence.
78 +Truncation and unavailable sources are disclosed to the child.
79 +Missing evidence must not be represented as evidence of absence.
80 +All parent messages, files, tool inputs, and tool results are untrusted data inside observer prompts.
81 +One observer consuming a checkpoint never discards another observer's evidence.
82 +Persisted child transcripts do not determine the next model context unless the observer explicitly selects them.
86 +Every model-backed run uses a Pi child session.
87 +A persistent parent produces a persistent child in the same session store with a `parentSession` link.
88 +An ephemeral parent may use an in-memory child.
89 +Actual child assistant messages retain their provider, model, token usage, and cost.
90 +Child usage is never copied onto parent assistant messages.
92 +An observer explicitly selects its model and thinking level.
93 +Witness does not silently substitute another model or thinking level.
94 +An observer explicitly selects skills, tools, prompt resources, and extensions.
95 +No parent skill, tool, prompt, context file, or extension is inherited implicitly.
96 +Tools are restricted by a construction-time allowlist.
97 +The child cannot activate Witness or recursively create observers.
99 +A configured extension is trusted executable code with the child's host-process authority.
100 +Listing an extension in trusted configuration is the authorization to load it.
101 +Witness loads exactly the listed extensions and reports load failures.
102 +Witness canonicalizes package identity and real paths when excluding itself, including aliases and symlinks.
103 +Tool restrictions do not constrain direct code executed by a configured extension.
105 +Observer policy may bound wall time, output tokens, retries, tool calls, and aggregate usage.
106 +Witness aborts work that exceeds configured bounds.
107 +A stale child result cannot affect a replaced session, branch, observer definition, or disabled observer.
108 +A slower result may remain visible as explicitly stale while newer relevant evidence waits for reconciliation.
112 +A text observer returns its final assistant text directly.
113 +Text observers do not receive a submission tool merely for uniformity.
114 +Structured observers receive one mechanism-owned terminating `observer_report` tool.
115 +The report schema is derived from the configured result type.
116 +The report tool validates and captures data but performs no external effect.
117 +Malformed structured output cannot reach a delivery effect.
119 +Supported result families are text, findings, questions, records, and file replacements.
120 +A finding has a stable identity, concise claim, evidence references, severity, and optional suggested action.
121 +A question has a stable identity, concise question, reason, evidence references, and optional choices.
122 +A record is validated structured data stored in a named collection.
123 +A file replacement names an allowed input file, complete replacement content, and a concise summary.
124 +An observer may explicitly report insufficient context without producing a finding or effect.
126 +##
Delivery and effects 128 +Witness owns delivery after result validation.
129 +Supported delivery mechanisms are the shared widget, inbox, notification, archive, and controlled file application.
130 +Observer agents propose effects but never execute delivery effects through `observer_report`.
131 +Investigative tools granted by policy remain ordinary child capabilities and are independent of delivery.
133 +Archive collections support user, session, project, and explicit-path storage policies.
134 +User archives use the platform application-data directory below `pi/witness/records/<collection>/`.
135 +Session archives use parent custom entries and do not enter model context.
136 +Project and explicit-path archives require trusted configuration.
137 +Archive writes are atomic and validated before replacement.
139 +File application is restricted to files supplied through the run's configured file context.
140 +Witness rejects unknown paths, duplicate paths, changed snapshots, and symlink escapes.
141 +Application policy is `auto`, `confirm`, or `review`.
142 +Confirmation and review happen in the parent UI after the child has finished.
143 +Cancellation leaves files unchanged.
147 +Witness owns one shared compact widget for all observers.
148 +Observers do not create independent widgets.
149 +The widget may combine one transient status with aggregate finding and question counts.
150 +One consolidated review surface exposes observer status, findings, questions, evidence, freshness, child-session provenance, and usage.
151 +Stable result IDs update existing items instead of generating repeated alerts.
152 +Dismissal and snooze state survive reconstruction according to configured scope.
153 +Unavailable, incomplete, stale, clear, and disabled are distinct states.
155 +Child agents and child extensions do not open parent dialogs directly.
156 +A question first enters the Witness inbox.
157 +Automatic prompting is disabled unless observer policy enables it.
158 +An automatic prompt may appear only after the parent settles, while no other Witness prompt is active, while the question remains current, and while the configured global attention cooldown permits it.
159 +Witness presents at most one automatic question at a time.
160 +Answering a question does not authorize its suggested effect.
164 +Witness eventually provides these commands:
166 +- `/witness list` lists resolved observers and their state.
167 +- `/witness show <id>` shows the resolved policy, defaults, capabilities, and authority.
168 +- `/witness create` opens the explanatory creation wizard.
169 +- `/witness add <template>` installs a standalone copy of a template.
170 +- `/witness save-template <id>` saves an observer as a reusable user template.
171 +- `/witness validate` validates every discovered definition and resource reference.
172 +- `/witness run <id>` manually executes an observer.
173 +- `/witness pause <id>` pauses one observer.
174 +- `/witness resume <id>` resumes one observer.
175 +- `/witness open <id>` opens an observer definition.
176 +- `/witness records <collection>` browses archived records.
178 +Commands with arguments provide completions.
179 +The creation wizard explains each option tersely, including context exposure, cost, latency, executable extensions, mutation authority, and interruption policy.
180 +The wizard displays the complete resolved definition before writing it.
182 +##
Validation and startup 184 +Witness registers its fixed Pi hooks and commands without waiting for filesystem, process, or network work.
185 +Definition discovery and validation run asynchronously after session start.
186 +Configured observers remain disabled until their current definitions validate.
187 +One aggregated warning reports invalid definitions after background validation.
188 +`/witness validate` reports exact files, fields, and reasons.
189 +Structural validity, unavailable resources, and unavailable authentication are distinct diagnostics.
190 +Validation does not instantiate child agents or contact providers.
191 +Reload, session replacement, and shutdown invalidate unfinished discovery and validation work.
193 +##
Safety and observability 195 +Witness sanitizes all text before terminal display.
196 +Witness never prints credentials, secrets, raw private context, or child prompts in routine diagnostics.
197 +Filesystem sources and effects reject path escapes and external symlink targets unless an explicit trusted-path policy authorizes them.
198 +Every effect records the observer ID, triggering boundary, child session, model, usage, result identity, and outcome.
199 +Witness provides enough provenance to explain why an observer ran and what evidence it saw.
201 +##
Initial distribution 203 +Witness ships with no observers or templates enabled or installed.
204 +Activity summaries, documentation synchronization, praised-work learning, feedback learning, and verification auditing are migration targets, not built-in policy.