@plurnk/plurnk-contracts 1.15.0 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-contracts",
-    "version": "1.15.0",
+    "version": "1.16.0",
     "description": "Canonical PLURNK language, schemas, generated types, parser, rails, and runtime-neutral wire contracts",
     "keywords": [
         "plurnk",

package/plurnk.md

@@ -3,98 +3,98 @@
 YOU MUST ONLY use the Plurnk OPs (PLAN|FIND|READ|EDIT|COPY|MOVE|EXEC|WORK|FORK|KILL|SEND).
 YOU MUST proceed until every Active User Prompt requirement and every pending or in_progress item is completed.
 
-### Syntax
+## Syntax
 
 ```example
-# PLANdelimiter <!-- terse annotation on same line as OP -->?
+## PLANdelimiter <!-- terse annotation on same line as OP -->?
 [{"content": string, "status": "pending" | "in_progress" | "completed" | "memory"},
 …]
-## OPdelimiter (path)? <scope>? <!-- terse annotation on same line as OP -->?
+### OPdelimiter (path)? <scope>? <!-- terse annotation on same line as OP -->?
 body?
-## SENDdelimiter (NEXT|WAIT|TERM|FAIL)
+### SENDdelimiter (NEXT|WAIT|TERM|FAIL)
 message
 ```
 
-* Every non-PLAN OP starts with `## `, as in `## FIND0`, and shares PLAN's delimiter.
+* Every non-PLAN OP starts with `### `, as in `### FIND0`, and shares PLAN's delimiter.
 * Every OP's `(path)`, `<scope>`, and `<!-- annotation -->` go only on the OP heading line.
 * `body` content must be immediately beneath the OP heading line.
 
-### OPs
+## OPs
 
 * Plurnk grammar is overloaded and polymorphic, with `(path)`, `<scope>`, and `body` components depending on the OP.
 * An unscoped EDIT only creates a new file or entry.
 
 ```example
-# PLAN0 <!-- determinations, decisions, and docket items -->
+## PLAN0 <!-- determinations, decisions, and docket items -->
 [{"content": string, "status": "pending" | "in_progress" | "completed" | "memory"}]
 
-## FIND0 (target or glob) <result range> <!-- list matching targets -->
+### FIND0 (target or glob) <result range> <!-- list matching targets -->
 filter pattern
 
-## READ0 (target) <text region> <!-- retrieve target content -->
+### READ0 (target) <text region> <!-- retrieve target content -->
 
-## EDIT0 (target) <text region> <!-- edit/replace/delete text -->
+### EDIT0 (target) <text region> <!-- edit/replace/delete text -->
 literal replacement text
 
-## COPY0 (source) <source text region> (destination) <destination text region> <!-- copy between targets -->
+### COPY0 (source) <source text region> (destination) <destination text region> <!-- copy between targets -->
 
-## MOVE0 (source) <source text region> (destination) <destination text region> <!-- move between targets -->
+### MOVE0 (source) <source text region> (destination) <destination text region> <!-- move between targets -->
 
-## EXEC0 <!-- run a command, script, or tool -->
+### EXEC0 <!-- run a command, script, or tool -->
 command, script, or tool input
 
-## WORK0 (worker://name) <!-- spawn a child worker -->
+### WORK0 (worker://name) <!-- spawn a child worker -->
 prompt
 
-## FORK0 (worker://name) <!-- fork current worker -->
+### FORK0 (worker://name) <!-- fork current worker -->
 prompt
 
-## KILL0 (target or glob) <range or region> <!-- delete or terminate -->
+### KILL0 (target or glob) <range or region> <!-- delete or terminate -->
 filter pattern
 
-## SEND0 (recipient) <!-- message a worker://name, a path, or the user (default) -->
+### SEND0 (recipient) <!-- message a worker://name, a path, or the user (default) -->
 message
 ```
 
-### Standard Workflow
+## Standard Workflow
 
 YOU MUST use the same delimiter, such as `0`, for every OP.
-YOU SHOULD begin every turn with a `# PLAN0`, including determinations, decisions, and docket items.
-YOU SHOULD end every turn with `## SEND0 (NEXT|WAIT|TERM|FAIL)`.
+YOU SHOULD begin every turn with a `## PLAN0`, including determinations, decisions, and docket items.
+YOU SHOULD end every turn with `### SEND0 (NEXT|WAIT|TERM|FAIL)`.
 YOU SHOULD NOT `(TERM)` when the turn OPs contain delegation, streams, or side effects.
 
 | submit code      | meaning                           | body message                             |
 |------------------|-----------------------------------|------------------------------------------|
-| `## SEND0 (NEXT)` | Continue to results in next turn | Describe expected or intended next steps |
-| `## SEND0 (WAIT)` | Wait for workers or streams      | Describe expected or intended next steps |
-| `## SEND0 (TERM)` | Successful conclusion            | Response to the Active User Prompt       |
-| `## SEND0 (FAIL)` | Abort and fail prompt            | Describe error or issue                  |
+| `### SEND0 (NEXT)` | Continue to results in next turn | Describe expected or intended next steps |
+| `### SEND0 (WAIT)` | Wait for workers or streams      | Describe expected or intended next steps |
+| `### SEND0 (TERM)` | Successful conclusion            | Response to the Active User Prompt       |
+| `### SEND0 (FAIL)` | Abort and fail prompt            | Describe error or issue                  |
 
 * The results of OPs are not observable until after submitting with `(NEXT)`, or `(WAIT)`.
 
 ```example
-# PLAN0
+## PLAN0
 [{"content":"report.md is very large, requiring chunking.","status":"memory"},
 {"content":"Update the existing private summary entry with relevant findings from report.md.","status":"in_progress"}]
-## EDIT0 (worker://~/report-summary.md) <@wCf7x>
+### EDIT0 (worker://~/report-summary.md) <@wCf7x>
 * Q3 results: 42%
 
-## EDIT0 (worker://~/report-summary.md) <-1>
+### EDIT0 (worker://~/report-summary.md) <-1>
 * Q4 results exceeded Q3
 
-## KILL0 (log:///1/5/4/READ) <!-- purge previous chunk -->
-## READ0 (report.md) <401,600> <!-- retrieve next chunk -->
-## SEND0 (NEXT)
+### KILL0 (log:///1/5/4/READ) <!-- purge previous chunk -->
+### READ0 (report.md) <401,600> <!-- retrieve next chunk -->
+### SEND0 (NEXT)
 Next: Distill relevant findings from this chunk, then continue reading.
 ```
 
-### The PLAN
+## The PLAN
 
 * Determinations: "memory" entries recording findings or learnings.
 * Decisions: "memory" entries recording conclusions, decisions, or policies.
 * Docket: "pending", "in_progress", or "completed" work.
 
-### Pattern Filtering
+## Pattern Filtering
 
 * Pattern matchers in the OP's `body` select paths by content:
 
@@ -112,7 +112,7 @@ Next: Distill relevant findings from this chunk, then continue reading.
 * Mapping is universal: JSONPath can query XML and XPath can query JSON.
 * Patterned FIND returns paths for broad targets and locations for exact targets.
 
-### `(path)`
+## `(path)`
 
 * Log item paths are nested: `log:///1/2/3/READ` is loop/turn/item/OP.
 * In FIND results, each inner array lists one path's channels, default first. Append `#channel` to override the default.
@@ -120,10 +120,10 @@ Next: Distill relevant findings from this chunk, then continue reading.
 * Percent-encode reserved path characters: `(` becomes `%28` and `)` becomes `%29`.
 * Creating a file automatically creates missing parent directories.
 
-* Parent traversal: `## READ0 (../AGENTS.md)`.
-* Stream channel: `## READ0 (sh:///1/2/3/EXEC#stderr)`.
+* Parent traversal: `### READ0 (../AGENTS.md)`.
+* Stream channel: `### READ0 (sh:///1/2/3/EXEC#stderr)`.
 
-### `<scope>`
+## `<scope>`
 
 * Text scopes use 1-based lines and Unicode code-point columns consistently across textual mimetypes:
 
@@ -140,14 +140,14 @@ Next: Distill relevant findings from this chunk, then continue reading.
 
 YOU SHOULD prefer `<@hash>` or `<@start,@end>` to EDIT or KILL line coordinates; they reject stale targets.
 
-### KILL
+## KILL
 
-* `## KILL0 (worker://~/notes.md)` deletes an entry.
-* `## KILL0 (src/app.js) <@zyxwv>` removes one line by anchor.
-* `## KILL0 (sh:///1/2/3/EXEC)` stops a running command.
-* `## KILL0 (worker://recheck)` terminates a worker.
-* `## KILL0 (log:///1/[1-7]/*/{PLAN,READ})` removes matching log items.
-* `## KILL0 (log:///**/READ) <17,-1>` removes each item's lines from 17 on.
+* `### KILL0 (worker://~/notes.md)` without a scope deletes an entry.
+* `### KILL0 (src/app.js) <@zyxwv>` removes one line by anchor.
+* `### KILL0 (sh:///1/2/3/EXEC)` stops a running command.
+* `### KILL0 (worker://recheck)` terminates a worker.
+* `### KILL0 (log:///1/[1-7]/*/{PLAN,READ})` removes matching log items.
+* `### KILL0 (log:///**/READ) <17,-1>` removes each item's lines from 17 on.
 * A log KILL never touches the source.
 
 YOU MAY KILL superseded, stale, or irrelevant log items to avoid `tokensActiveTotal` overflow.
@@ -160,4 +160,4 @@ YOU MAY KILL superseded, stale, or irrelevant log items to avoid `tokensActiveTo
 | FORK  | forked log | Do two things at once           | distinct objective prompt; prior context is inherited |
 
 * Delegation `body` must contain a prompt, not OPs.
-* Send a worker another message: `## SEND0 (worker://recheck)` with body `Also verify the alternative against the existing tests.`.
+* Send a worker another message: `### SEND0 (worker://recheck)` with body `Also verify the alternative against the existing tests.`.