Skip to content
Merged
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
4 changes: 4 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,14 @@
"keywords": [
"pi-package"
],
"bin": {
"pardes-feedback": "./plugins/pardes-pi/scripts/pardes-feedback.ts"
},
"scripts": {
"ci": "biome ci .",
"format": "biome format --write .",
"format:check": "biome format .",
"feedback": "bun plugins/pardes-pi/scripts/pardes-feedback.ts",
"lint": "biome check --error-on-warnings .",
"lint:fix": "biome check --error-on-warnings --write .",
"references:effect": "bash plugins/pardes-pi/scripts/sync-effect-reference.sh",
Expand Down
34 changes: 33 additions & 1 deletion plugins/pardes-pi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ refresh same-tier numeric counts.
The manager-visible tools are grouped by purpose:

```text
question
question · feedback
pardes_status · inbox_get · inbox_acknowledge
workstream_create · workstream_list · workstream_get · workstream_complete
report_get
Expand Down Expand Up @@ -181,6 +181,38 @@ publication. Pardes never merges autonomously.
Structured state is written beneath `~/.pi/agent/pardes/`. Override that root
for development or tests with `PARDES_PI_STATE_DIR`.

## Frustration feedback

The model-facing `feedback({ text })` tool is available to managers, writing
workers, and advisory verifiers. It is deliberately general: if anything is
frustrating, confusing, broken, annoying, or wasteful, write it here. The tool
accepts only free-form text. Pardes adds bounded
provenance (time, id, role and available session/manager/agent/workstream,
repository, verifier, and version identities); it never automatically captures
logs, files, environment values, or secrets.

Each submission is an immutable atomic JSON record in the owner-only global
registry; existing registry directories and artifacts are tightened when read.
Addressed state is stored separately so triage never rewrites the submission.
The installed package exposes a human CLI:

```bash
pardes-feedback help
pardes-feedback list --addressed no
pardes-feedback show <feedback-id>
pardes-feedback watch --cursor triage
pardes-feedback address <feedback-id>
```

From a source checkout, use `bun run feedback -- <command>`. Watch cursors use
one durable initialization boundary, a recoverable cross-process scan lock, and
atomic per-entry receipts written only after output succeeds. Concurrent scans
do not duplicate output; a crash between output and receipt deliberately replays
the entry after restart for at-least-once delivery. A cursor consumes every
observed entry, including filter nonmatches, so use a distinct cursor name when
changing filters or triage purpose. CLI rendering treats feedback text as
untrusted and escapes terminal controls.

## Development validation

Hosted GitHub Actions is the normal integration authority. Run relevant
Expand Down
5 changes: 5 additions & 0 deletions plugins/pardes-pi/docs/MANAGER.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,11 @@ action; omit empty categories. Avoid fluff, repeated narration, excessive
headings, pseudo-diagrams, gratuitous code fences, and vertical whitespace.
Drill down only for a specific decision.

Use `feedback({ text })`: if anything is frustrating, confusing, broken,
annoying, or wasteful, write it here. Describe the friction in bounded free-form
words. Do not paste logs, file contents, environment values, or secrets; Pardes
adds only bounded explicit provenance automatically.

Use the smallest projection needed:

- `pardes_status()` for counts, warnings, and pending attention;
Expand Down
34 changes: 29 additions & 5 deletions plugins/pardes-pi/docs/NORTH_STAR.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,10 @@ Durable manager state lives beneath:

```text
~/.pi/agent/pardes/
├── feedback/
│ ├── submissions/ # one immutable atomic JSON record per submission
│ ├── triage/ # separate addressed-state records
│ └── watch-cursors/ # durable per-entry CLI watch receipts
└── projects/
└── <repo-key>/
└── managers/
Expand Down Expand Up @@ -308,7 +312,7 @@ The manager coordinates work rather than editing source. Its model-visible tools
are grouped by purpose:

```text
question
question · feedback
pardes_status · inbox_get · inbox_acknowledge
workstream_create · workstream_list · workstream_get · workstream_complete
report_get
Expand All @@ -324,17 +328,18 @@ is opt-in.

### Writing worker

A writing worker receives ordinary coding tools rooted in one managed worktree.
The extension rejects file-tool paths outside the assigned worktree. Bash is not
A writing worker receives ordinary coding tools rooted in one managed worktree,
plus the global `feedback` frustration channel. The extension rejects file-tool
paths outside the assigned worktree. Bash is not
a complete security boundary, so completion, publication, and cleanup paths
also audit changed files and Git state.

### Advisory verifier

An advisory verifier runs in a fresh detached scratch checkout pinned to the
reviewed worker SHA. It has path-rooted read tools, Bash for efficient
inspection, fixed-argv captured-head evidence, structured reporting, and no
`edit` or `write` UI affordances.
inspection, fixed-argv captured-head evidence, structured reporting, the global
`feedback` frustration channel, and no `edit` or `write` UI affordances.

Verifier Bash can mutate disposable scratch files and same-user filesystem
access is not isolation. Verifier commits are never publication sources.
Expand Down Expand Up @@ -380,6 +385,25 @@ synchronize an existing review gate after a fresh audit. Terminal merge
observation can stop an idle owner and complete its workstream mechanically.
Merges remain user-controlled.

## Frustration feedback

Managers, writing workers, and advisory verifiers have one first-class
`feedback({ text })` tool. Its intentionally minimal schema has one required
free-form text field. If anything is frustrating, confusing, broken, annoying,
or wasteful, write it here. Each submission is a
separate immutable atomic JSON record in global Pardes state. Pardes adds only
bounded explicit provenance and never automatically captures logs, file
contents, environment values, or secrets. Registry directories and artifacts
are owner-only, including tightened existing entries. Human addressed-state
triage remains in a separate durable record. The `pardes-feedback` CLI lists,
filters, shows, watches, and marks entries addressed. Watch uses one durable
initialization boundary, a recoverable cross-process scan lock, and output-before-
receipt at-least-once delivery: ordinary concurrent scans do not duplicate, while
a crash between output and receipt safely replays after restart. Filters apply at
observation time and every observed entry advances that cursor, including
nonmatches; changing filters requires a distinct cursor. Terminal output treats
authored text as untrusted data.

## External feedback and trust

Pull-request comments, submitted reviews, CI logs, child reports, and advisory
Expand Down
Loading
Loading