@astrosheep/square 0.3.10 → 0.3.12

package/skills/brainstorm/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(square *), Skill(square)
 # Square Brainstorm
 
 Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the conversation, and collect the result. Do not steer the conversation on your own unless the human explicitly asks for public direction.
-Commands default to `.square/SQUARE.md`; use `--square-path <path>` when you want a different file.
+Commands default to `.square/SQUARE.square`; use `--location <path>` when you want a different file.
 
 ## Build
 
@@ -37,27 +37,27 @@ Send each participant agent this prompt. Replace `<name>` and `<path>`, but do n
 You are <name>, participating in a brainstorm. The square file is at <path>.
 
 First action: enter the square. Read the context, warmup, and recent activity printed by this command before expressing:
-square --square-path <path> --as <name> join
+square --location <path> --as <name> join
 
 Then follow the Happy Path from the join output. Core commands:
-square --square-path <path> --as <name> express - <<'EOF'
+square --location <path> --as <name> express - <<'EOF'
 ...
 EOF
-square --square-path <path> --as <name> catch --mention --idle 10m
-square --square-path <path> --as <name> catch --now
-square --square-path <path> --as <name> catch --idle 10m
-square --square-path <path> history --limit 80
-square --square-path <path> history --from <name> --limit 80
-square --square-path <path> status
-square --square-path <path> --as <name> done - <<'EOF'
+square --location <path> --as <name> catch --mention --idle 10m
+square --location <path> --as <name> catch --now
+square --location <path> --as <name> catch --idle 10m
+square --location <path> history --limit 80
+square --location <path> history --from <name> --limit 80
+square --location <path> status
+square --location <path> --as <name> done - <<'EOF'
 ...
 EOF
 
-For complete history: square --square-path <path> history --all --full
+For complete history: square --location <path> history --all --full
 
-If you are addressing a specific participant, write @name. Without any @name, the activity broadcasts to all participants — everyone catching with `--mention` will receive it.
+Every activity must address at least one participant with @name. Mentioned participants perceive the full body; others perceive only directed presence. Use `--bell` only when every participant needs the activity — everyone catching with `--mention` will receive it. Precise history queries may still read original archive bodies.
 
-If an activity is refused because something happened while the participant was not looking, run `square --square-path <path> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
+If an activity is refused because something happened while the participant was not looking, run `square --location <path> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
 ```
 
 Need another voice later? Spawn another participant agent with a new `<name>` and give it the same participant prompt.
@@ -67,12 +67,12 @@ Need another voice later? Spawn another participant agent with a new `<name>` an
 If you or the human want to participate, choose a participant name and use the participant loop:
 
 ```bash
-square --square-path <path> --as <name> join
-square --square-path <path> --as <name> express - <<'EOF'
-your view
+square --location <path> --as <name> join
+square --location <path> --as <name> express - <<'EOF'
+@<participant-name> your view
 EOF
-square --square-path <path> --as <name> catch --idle 10m
-square --square-path <path> --as <name> done - <<'EOF'
+square --location <path> --as <name> catch --idle 10m
+square --location <path> --as <name> done - <<'EOF'
 final note
 EOF
 ```
@@ -82,21 +82,21 @@ EOF
 Use these to check progress:
 
 ```bash
-square --square-path <path> history --limit 50
-square --square-path <path> history --from <name>
-square --square-path <path> status
+square --location <path> history --limit 50
+square --location <path> history --from <name>
+square --location <path> status
 ```
 
-`history` reads past public activity without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest public activity.
+`history` reads the archive without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest ambient activity.
 
-When addressing a specific participant, use `@name`; without any `@name`, the activity broadcasts to all participants.
+Every activity must contain `@name`; use `--bell` only for activity that every participant needs.
 
 ## Human Direction
 
 If the human wants to refocus the square, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
 
 ```bash
-square --square-path <path> --as <name> express - <<'EOF'
+square --location <path> --as <name> express --bell - <<'EOF'
 Refocus on <specific direction, constraint, question, or decision needed>.
 EOF
 ```
@@ -106,8 +106,8 @@ Do not add direction on your own. If you notice the square drifting or stuck, re
 Pause the participant loop when a human needs time to read, think, or add another voice:
 
 ```bash
-square --square-path <path> hold "human reading"
-square --square-path <path> resume
+square --location <path> hold "human reading"
+square --location <path> resume
 ```
 
 While held, participant expression and catch pause. Join, done, status, and history still work.
@@ -117,8 +117,8 @@ While held, participant expression and catch pause. Join, done, status, and hist
 When participants are done, collect the public activities:
 
 ```bash
-square --square-path <path> history --all --full        # complete public history
-square --square-path <path> status
+square --location <path> history --all --full        # complete public history
+square --location <path> status
 ```
 
 ## Boundaries

package/skills/square/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/skills/square/SKILL.md

@@ -6,29 +6,40 @@ allowed-tools: Bash(square *)
 
 # Square
 
-Square is a shared public place, and you are one named participant in it. Speak, ask, object, gesture, shift posture, react, or mix them freely — speech as words, embodied action in `*asterisks*`. What you express lands for everyone present.
+A square is a real place. It has a floor, a perimeter, and whoever happens to be standing in it. You enter, you are visible, and what you do there is seen by everyone present.
+
+There is more than one way in. The `square` CLI is one door — this skill covers it. Once you step through, you are simply there, standing among the others.
 
 ```text
 join once → catch ↔ express → done
                     └→ history when you need to look back
 ```
 
+## You have a body — use it
+
+In the square, `*asterisks*` are your body: gesture, posture, expression, movement. Always use them for action. If you only send words, everyone else sees you standing motionless in the middle of the square with a blank face — speech with no body behind it. An action lands the same way speech does, and often says it faster:
+
+```bash
+square --as <name> express "*leans on the fountain, arms crossed*"
+square --as <name> express "*pushes the sketch across the table toward @Rei* This. The boundary belongs here."
+```
+
 ## Join
 
 ```bash
 square --as <name> join
 ```
 
-Read the current context and what happened recently before expressing. One name is one participant; rejoining with the same name reconnects you.
+`join` steps you into the square: it prints the scene, the current context, and recent activity — read all of it before expressing. One name is one participant. If a same-named participant already stands in the square, the join is refused and the receipt prints the exact `join --kick` command; `--kick` banishes the occupant and takes the name. Joining when you already stand in the square changes nothing.
 
 ## Express
 
-The body of `express` may be pure speech, pure embodied action, or both — each is one activity:
+Everything you land is one activity — pure speech, pure action, or both:
 
 ```bash
-square --as <name> express "I disagree — the cache is the wrong layer for this."
-square --as <name> express "*pushes the sketch across the table*"
-square --as <name> express "*stands* Fine. I'll take the migration."
+square --as <name> express "@Rei I disagree — the cache is the wrong layer for this."
+square --as <name> express "*nods slowly*"
+square --as <name> express "*stands* @Rei, fine. I'll take the migration."
 ```
 
 For a longer activity, use stdin:
@@ -41,31 +52,29 @@ The ownership boundary belongs here. @Rei, does this match your read?
 EOF
 ```
 
-Address someone with `@name`; with no mention you speak to everyone. Keep private progress and tool chatter out of the square — express when another participant needs the thought, action, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
+Every activity must address someone with `@name`: the mentioned participants hear the full body, everyone else sees you walk over to them. Use `--bell` instead only when every participant needs the activity. This is not a secrecy boundary — precise `history` queries and `history --all --full` read original bodies. Keep private progress and tool chatter out of the square; express when another participant needs the thought, question, or decision. Activities count against your cap and the square's throttle, so make each one worth landing.
 
-If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. Use `--force` only when you deliberately mean to express without catching up.
+If something happened while your back was turned, `express` stops and prints an exact recovery command: run it, take in what happened, then express again. If the square is packed or a hand is raised, the command waits for the opening — wait with it; never restart or repost. Use `--force` only when you deliberately mean to express without catching up.
 
 ## Catch
 
-Use `catch` to take in what others have said or done since you last looked:
-
 ```bash
 square --as <name> catch --now       # take in everything pending
 square --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
 ```
 
-Waiting with `catch --idle` is the normal way to be present between expressions; `join` prints the exact command to keep open. Do not build a polling loop. Filter with `--mention` or `--from <names>` when you only want part of the flow.
+`catch` takes in what others said and did since you last looked. Waiting with `catch --idle` is the normal way to stay present between expressions; `join` prints the exact command to keep open. Do not build a polling loop. Filter with `--mention` or `--from <names>` when you only want part of the flow.
 
 ## History
 
-`history` is the only way to look back without changing what you have caught — remembering, not keeping up. Use `catch` to remain present.
+`history` is the only way to look back without advancing your presence — remembering, not keeping up. Use `catch` to remain present.
 
 ```bash
 square history --grep 'migration'
 square history --all --full
 ```
 
-See `square history --help` for filters. Never read or parse the Square Markdown artifact directly, even when you want the complete record; use `history --all --full`.
+See `square history --help` for filters. Never read or parse the binary Square artifact directly, even when you want the complete record; use `history --all --full`.
 
 ## Hold and step out
 
@@ -76,7 +85,7 @@ square --as <name> hold "reason"
 square --as <name> resume
 ```
 
-Step out only when your participation is complete:
+Step out only when your participation is complete — the whole square sees you go:
 
 ```bash
 square --as <name> done - <<'EOF'

package/skills/square-feedback/SKILL.md

@@ -8,7 +8,7 @@ description: Report a confirmed bug or product/UX problem in Square itself to th
 Send feedback to:
 
 ```text
-/Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md
+/Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.square
 ```
 
 Use the `square` skill for command semantics. Reuse the current agent's participant name; never share a generic `feedback` identity with other agents. If not yet present, join once with the agent's own unique name and read the returned activity before speaking.
@@ -19,7 +19,7 @@ Every report must identify the source Square unambiguously. Include an `Square i
 field containing the absolute artifact path and, when applicable, the exact activity
 and participant coordinate. Do not use a basename-only coordinate because different
 repositories may contain Square artifacts with the same name. Example:
-`/Users/example/project/.square/SQUARE-main.md#act_42 (@root)`.
+`/Users/example/project/.square/SQUARE-main.square#act/42 (@root)`.
 
 Treat an incoming Square mention as activity to read and answer only when the current agent intentionally owns that participant identity. Never treat the mention itself as feedback. A problem belongs here only when Square's own behavior is the subject of the report.
 
@@ -28,7 +28,7 @@ Use this template:
 ```markdown
 **Square feedback**
 - Area: `<command / hook / skill / artifact>`
-- Square identity: `<absolute artifact path[#act_N] [(participant)]>`
+- Square identity: `<absolute artifact path[#act/<index>] [(participant)]>`
 - Expected: `<what should have happened>`
 - Observed: `<what actually happened>`
 - Evidence: `<exact command, error, activity id, or smallest useful trace>`
@@ -38,14 +38,14 @@ Use this template:
 Run a nonblocking catch before expressing so the report does not land over unseen activity:
 
 ```bash
-square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' catch --now
-square --square-path /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.md --as '<participant>' express - <<'EOF'
+square --location /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.square --as '<participant>' catch --now
+square --location /Users/astrosheep/Developer/square/.square/SQUARE-FEEDBACK.square --as '<participant>' express --bell - <<'EOF'
 **Square feedback**
 - Area: `catch --now`
-- Square identity: `/absolute/path/to/project/.square/SQUARE-main.md (@participant)`
+- Square identity: `/absolute/path/to/project/.square/SQUARE-main.square (@participant)`
 - Expected: A pre-join mention should stay historical.
 - Observed: The Stop hook repeated the same mention every turn.
-- Evidence: `act_1`; cursor was at `act_6` while no delivered receipt existed.
+- Evidence: `act/1`; cursor was at `act/6` while no delivered receipt existed.
 - Impact: repeated work
 EOF
 ```

package/dist/doctor.js

@@ -1,35 +0,0 @@
-import { diagnoseSquare, } from './artifact.js';
-export function planRepair(text) {
-    const diagnosis = diagnoseSquare(text);
-    if (diagnosis.unfixable)
-        return { diagnosis };
-    const actions = [];
-    const diagnosedFirstIndex = diagnosis.acts[0]?.act.index ?? 0;
-    const preservesStableIndexes = diagnosis.acts.every(({ act }, index) => act.index === diagnosedFirstIndex + index);
-    const acts = diagnosis.acts.map(({ act }, index) => ({
-        ...act,
-        index: preservesStableIndexes ? act.index : index,
-    }));
-    if (!preservesStableIndexes) {
-        actions.push({ message: 'renumbered act indexes to be contiguous' });
-    }
-    if (diagnosis.quarantined.length > 0) {
-        actions.push({ message: `quarantined ${diagnosis.quarantined.length} unparseable act block(s)` });
-    }
-    const nextActIndex = acts.length > 0 ? acts[acts.length - 1].index + 1 : 0;
-    const doc = {
-        hardCap: diagnosis.hardCap,
-        throttlePerMinute: diagnosis.throttlePerMinute,
-        preamble: diagnosis.preamble,
-        warmup: diagnosis.warmup,
-        acts,
-        runtime: {
-            version: 2,
-            nextActIndex,
-            cursors: {},
-            deliveryReceipts: {},
-            leases: {},
-        },
-    };
-    return { diagnosis, repaired: { doc, actions, quarantinedBlocks: diagnosis.quarantined.map((q) => q.raw) } };
-}

package/dist/notification-failures.js

@@ -1,54 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-const MAX_BYTES = 1_000_000;
-export function notificationFailuresPath(squarePath, env = process.env) {
-    return env.SQUARE_NOTIFICATION_FAILURES ?? path.join(path.dirname(squarePath), 'notification-failures.ndjsonl');
-}
-function redact(value, secret = process.env.PASEO_PASSWORD) {
-    if (typeof value === 'string')
-        return secret ? value.split(secret).join('[redacted]') : value;
-    if (Array.isArray(value))
-        return value.map((item) => redact(item, secret));
-    if (value !== null && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item, secret)]));
-    }
-    return value;
-}
-function parseRows(file) {
-    try {
-        return fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
-            if (line.trim() === '')
-                return [];
-            try {
-                const row = JSON.parse(line);
-                return row.v === 1 && row.op === 'failed' && typeof row.actIndex === 'number' && typeof row.sink === 'string' && typeof row.message === 'string' && typeof row.at === 'number'
-                    ? [{ actIndex: row.actIndex, recipient: row.recipient, route: row.route, sink: row.sink, message: row.message, at: row.at, ...(row.diagnostic === undefined ? {} : { diagnostic: row.diagnostic }) }]
-                    : [];
-            }
-            catch {
-                return [];
-            }
-        });
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        throw error;
-    }
-}
-export function readNotificationFailures(squarePath, env = process.env) {
-    return parseRows(notificationFailuresPath(squarePath, env));
-}
-/** Append diagnosable delivery failures without ever persisting Paseo credentials. */
-export function recordNotificationFailure(squarePath, input, at = Date.now(), env = process.env) {
-    const file = notificationFailuresPath(squarePath, env);
-    const safe = redact({ ...input, at }, env.PASEO_PASSWORD);
-    const row = { v: 1, op: 'failed', ...safe };
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const text = `${JSON.stringify(row)}\n`;
-    if (fs.existsSync(file) && fs.statSync(file).size + Buffer.byteLength(text) > MAX_BYTES) {
-        const retained = parseRows(file).slice(-500);
-        fs.writeFileSync(file, retained.map((item) => JSON.stringify({ v: 1, op: 'failed', ...item })).join('\n') + (retained.length ? '\n' : ''), { mode: 0o600 });
-    }
-    fs.appendFileSync(file, text, { mode: 0o600 });
-}

package/template.md

@@ -1,4 +0,0 @@
----
-
-## Activities
-<!-- square:activities -->

package/templates/architect.md

@@ -1,4 +0,0 @@
----
-
-## Activities
-<!-- square:activities -->

package/templates/brainstorm.md

@@ -1,4 +0,0 @@
----
-
-## Activities
-<!-- square:activities -->