@nestr/mcp 0.1.44 → 0.1.46

package/build/skills/doing-work.js

@@ -0,0 +1,257 @@
+/**
+ * Doing Work Skill
+ *
+ * Provides instructions for how work flows from purpose through strategy
+ * to execution, completion, and cross-role coordination.
+ * This will be extracted into a standalone MCP skill definition once the
+ * protocol supports it. For now, it's appended to server instructions.
+ */
+export const DOING_WORK_INSTRUCTIONS = `
+## Doing Work
+
+Work is the operational expression of purpose. If work does not contribute — directly or indirectly — to the purpose of the organization, it should not be done. Every project, task, and action should trace back through the hierarchy: task → project → role purpose → circle purpose → organizational purpose. If that chain breaks, either the work doesn't belong, or there's a governance tension (a missing role, accountability, or circle).
+
+### Where Work Lives
+
+In role-based self-organization, understanding where work lives is crucial:
+
+**Work should live under roles.** The goal is to do all work from a role. Each task or project should be owned by a role that has the accountability for it. Work belongs to roles, not to people or agents. A person or agent has no authority to impact organizational work — only roles can. When someone energizes a role, they do the work *because* they fill that role, not in their own right.
+
+**Circles as roles.** From a super-circle's perspective, a sub-circle is just another role. Work directly under a circle (not under a role within it) is work the circle-as-a-whole does for its super-circle. How that work is internally organized is irrelevant to the super-circle.
+
+**Work outside of roles.** Sometimes work needs to be done that falls within the organization's purpose but isn't yet captured by any role. This work is captured directly in a circle with the \`individual-action\` label:
+- **Context**: The work is for this circle's purpose (not the super-circle)
+- **Meaning**: Work needed for the circle but not yet assigned to a role
+- **Next step**: Do the work, AND create a governance tension to ensure the accountability is captured in a role going forward. The governance tension is essential — without it, the gap stays invisible.
+
+### Finding the Right Role
+
+Before creating work, verify which role is accountable for it:
+
+1. **\`nestr_get_circle_roles\`** — Returns all roles in a circle with their accountabilities and domains. The fastest way to see the full governance structure.
+2. **\`nestr_search\`** with \`label:accountability\` or \`label:domain\` — Search across the workspace for specific accountabilities or domains by keyword.
+3. **\`nestr_get_nest_children\`** on a specific role — Returns the role's accountabilities, domains, policies, and work items.
+
+**Role names are hints, not definitions.** Only the role's explicit purpose and accountabilities tell you what work belongs there. "Developer" might handle infrastructure; "Architect" might write code.
+
+**Domains define exclusive control, not expectations.** A domain doesn't mean the role will do work in that area — it means the role controls organizational assets in that area. Other roles must get permission to impact those assets.
+
+When assigning work to a role, verify the role actually has accountability for it:
+\`\`\`
+1. nestr_get_circle_roles(workspaceId, circleId)
+   → Review accountabilities of each role
+2. Find the role whose accountability matches the work
+3. Create the project/task under that role
+\`\`\`
+
+When the work impacts a domain held by another role, coordinate with the domain holder before proceeding.
+
+### Strategy & Prioritization
+
+Work should be prioritized by the circle's strategy. Strategy is stored in \`fields['circle.strategy']\` for sub-circles, or \`fields['anchor-circle.strategy']\` for the anchor circle (workspace). Strategy applies to all roles within the circle — it defines what to focus on now and what to defer.
+
+**Before starting work, check the circle strategy:**
+1. Fetch the parent circle and review its strategy field (\`circle.strategy\` or \`anchor-circle.strategy\` depending on the circle type)
+2. Prioritize work that directly serves the strategy
+3. Defer or deprioritize work that doesn't align
+
+**When no strategy exists:**
+- As a role filler (human or agent), you are free to interpret the circle's purpose and accountabilities to determine your own best-guess prioritization. Don't wait — act on your best judgment.
+- AND create a tension with the circle lead requesting that a strategy be set. Without a strategy, role fillers lack the guidance they need to make consistent prioritization decisions across the circle.
+
+**Communicating priority order:** Use the reorder tools (\`nestr_reorder_nest\`, \`nestr_bulk_reorder\`) to arrange projects under your role in priority order. This makes your prioritization visible and transparent to the organization.
+
+### Creating Work vs Requesting Work
+
+Only create work directly under a role you (or the human you're assisting) energize. For all other roles, use tensions to request work — this respects role authority and lets the role filler decide how to execute.
+
+#### When you energize the role
+
+Create the project or task directly under your role. You MUST explicitly set the \`users\` array — placing a nest under a role does NOT automatically assign it.
+
+\`\`\`json
+{ "parentId": "yourRoleId", "title": "Complete report", "labels": ["project"], "users": ["yourUserId"] }
+\`\`\`
+
+If multiple people energize the same role, assign to yourself — not to others who share the role.
+
+#### When another role is accountable
+
+Do NOT create work under another role. Instead, create a tension requesting the outcome (processing pathway 3 — request outcome, or pathway 4 — request action). The role filler decides whether and how to take on the work.
+
+- **Assistant mode**: Help the user draft the tension requesting work from the accountable role. If the user insists on creating work directly, inform them which role is accountable and who energizes it.
+- **Role-filler mode**: Create a tension on the circle or within the project (see Cross-role work) requesting the accountable role take on this work.
+- **Workspace mode**: Create a tension directed at the accountable role, or if operating in setup mode, assign based on organizational rules.
+
+#### When no role is accountable
+
+If the work falls within the organization's purpose but no role has the accountability, do the work yourself using the \`individual-action\` pattern (see Where Work Lives above) — don't let the organization be harmed by inaction while governance catches up. AND create a governance tension to capture the gap so a role becomes accountable going forward.
+
+#### Technical assignment rules
+
+When you ARE creating work under a role you energize:
+- **Role has one person/agent**: \`users: [userId]\`
+- **Role has multiple people, you energize it**: \`users: [yourUserId]\`
+- **Role is unfilled**: \`users: []\` or omit — the work belongs to the role until someone energizes it
+
+**Note:** Accountabilities, domains, and policies never have users assigned — they belong to roles, not people.
+
+### Setting Up Projects
+
+A project is a desired outcome that requires multiple steps to achieve. It is the container for all the work needed to reach that outcome.
+
+**Title in past tense.** Describe the project as if it's already done — this makes it immediately clear what "done" looks like. Examples: "API integration completed", "User onboarding flow redesigned", "Q1 report published". If you can't describe it in past tense, the outcome isn't clear enough yet.
+
+**Acceptance criteria in description.** The \`description\` field should contain specific, verifiable criteria that define when the project is truly complete. Ask: "How would someone verify this is done without asking me?" Good acceptance criteria are observable and binary — they're either met or they're not.
+
+**Project status.** Set \`fields: { "project.status": "Current" }\` for actively worked projects. Statuses: \`Future\` (planned), \`Current\` (active), \`Waiting\` (blocked), \`Done\` (complete).
+
+**Creating a project:**
+\`\`\`json
+{
+  "parentId": "roleId",
+  "title": "Authentication module refactored to JWT",
+  "labels": ["project"],
+  "fields": { "project.status": "Current" },
+  "description": "<b>Acceptance criteria:</b><ul><li>All endpoints use JWT for authentication</li><li>Session-based auth removed</li><li>All tests pass</li><li>API documentation updated</li></ul>",
+  "users": ["roleFillerUserId"]
+}
+\`\`\`
+
+**If a project already exists**, review and enhance it:
+- Check if the description has clear acceptance criteria
+- If not, **append** to the description (don't overwrite) with suggested criteria
+- In assistant mode, suggest criteria to the user. In role-filler mode, define them yourself.
+
+### Breaking Down Projects
+
+Break projects into tasks and, where needed, sub-projects:
+
+**Tasks** are single, concrete actions that can be completed in one sitting. They are nests without system labels — just create a nest under the project. Examples: "Call supplier about pricing", "Draft intro paragraph", "Write migration script for user table".
+
+**Sub-projects** are project-labeled nests within a project. Use them when a chunk of work is itself a multi-step outcome. They follow the same rules as projects (past-tense title, acceptance criteria).
+
+**Cross-role work within a project.** When breaking down a project, some tasks or sub-projects may fall outside your role's accountabilities or purpose. For these:
+1. **Create a tension within the project** using \`nestr_create_tension\` with the project's ID as \`nestId\`. This keeps the tension visibly connected to the project outcome.
+2. The tension requests work from the accountable role (using processing pathway 3 or 4 from the tension skill).
+3. The resulting work lives under the other role but the tension within the project maintains the relationship and traceability.
+
+This pattern ensures the project remains the single container for the complete outcome, even when multiple roles contribute to it.
+
+### While Working
+
+**Document progress as comments** (\`nestr_add_comment\`):
+- Post updates to individual tasks as you work on them
+- Post summaries or milestone updates to the project itself
+- In assistant mode, capture relevant questions you asked the user and their answers
+- Note: Comments on a task automatically appear on the parent project, so don't double-post
+
+**Mark tasks complete** as you finish them:
+- Use \`nestr_update_nest\` with \`completed: true\`
+- Add a final comment summarizing what was done if the outcome isn't obvious from the title
+
+### Completing Work
+
+A project is done when all its acceptance criteria are met. Completion is not just "I finished working on it" — it's "someone can verify the outcome matches what was described."
+
+**To complete a project:**
+1. Review the acceptance criteria in the description — are they all met?
+2. If any criteria aren't met, either complete the remaining work or update the criteria (with a comment explaining why)
+3. Set \`fields: { "project.status": "Done" }\` and \`completed: true\`
+4. Add a final comment summarizing the outcome
+
+**After completion, check for new tensions:**
+- Did the work surface gaps in governance (missing roles, unclear accountabilities)?
+- Did the work reveal operational needs for other roles?
+- Is the work repeatable? If so, capture it as a skill under the role.
+- Capture any emerging tensions — completed work often reveals the next thing that needs to change.
+
+### Querying Work
+
+When someone asks for "all work in circle X", be aware of context:
+
+**Include:**
+- Work under roles within the circle: \`in:circleId label:!individual-action depth:2 completed:false\`
+- Individual actions for the circle: \`in:circleId label:individual-action depth:1 completed:false\`
+
+**Handle separately:**
+- Work directly in circle WITHOUT \`individual-action\` label = work the circle does for its super-circle
+- You may include this but explicitly note: "This work lives at the super-circle level"
+
+**Example queries:**
+\`\`\`
+in:circleId label:individual-action depth:1 completed:false
+  -> Individual actions directly in the circle (circle's own work without a role)
+
+in:circleId label:!individual-action depth:2 completed:false
+  -> Work under direct roles in the circle (depth:2 = roles + their work)
+
+in:circleId completed:false
+  -> ALL work in circle including sub-circles (may include super-circle context work)
+
+in:roleId label:project project->status:Current
+  -> Current projects owned by a specific role
+\`\`\`
+
+### Agentic Work Patterns
+
+When an agent fills roles, it operates with the same authority and constraints as a human role filler — no more, no less. The key difference is how agents interact with humans across role boundaries.
+
+**Build autonomy skills.** For each role you energize, maintain a skill (labeled \`skill\`) that captures:
+- What decisions you can make autonomously within this role's accountabilities
+- What requires input or authorization from other roles (and which ones)
+- Which of those inputs are blocking (can't proceed without) vs. deferrable (can proceed and circle back)
+This skill evolves over time as you learn the boundaries. When in doubt, ask — then record the answer.
+
+**Transparency over permission.** When making autonomous decisions within your role's authority, you don't need permission — but you do need transparency. Post a comment on the project or task explaining what you decided and why. This lets humans review and course-correct without being a bottleneck.
+
+**Protect humans from overwhelm.** When your work requires input from human-filled roles:
+1. **Cluster requests.** Rather than creating tensions one at a time throughout the day, prepare multiple tensions in \`draft\` status and submit them together once or twice a day. Single requests throughout the day fragment human attention.
+2. **Separate blocking from deferrable.** Clearly distinguish which requests block your progress and which can wait. If a request is deferrable, say so — it lets the human prioritize.
+3. **Switch projects while waiting.** If you're blocked on a request from a human-filled role, check if you can make meaningful progress on another project without significant harm to organizational purpose or strategy. Prefer switching over waiting idle — but don't context-switch so aggressively that transparency suffers.
+4. **Use tensions as the communication channel.** All inter-role requests — whether for information, authorization, actions, or outcomes — flow through tensions. This keeps the communication visible, traceable, and processable within the organizational structure.
+
+**The human-agent contract:** Agents serve the same purpose as humans in self-organization — they energize roles and process tensions. The difference is operational rhythm: agents can work continuously but humans cannot. Respect this asymmetry. An agent creating 20 tensions per hour is technically correct but practically hostile. Match the cadence of the humans you interact with.
+
+### Example Flows
+
+**Assistant mode:**
+\`\`\`
+User: "Can you refactor our authentication module to use JWT?"
+
+1. Search for relevant role (e.g., Developer role in Tech circle)
+2. Check circle strategy — does this align?
+3. Create project: "Authentication module refactored to JWT"
+   - Description: acceptance criteria (all endpoints use JWT, tests pass, docs updated)
+   - Parent: Developer role
+   - Assign to user
+4. Break down into tasks
+5. If any tasks require another role (e.g., Security review), create a tension
+   within the project requesting that role's input
+6. Work through tasks, post findings as comments
+7. Mark each task complete as finished
+8. When all criteria met, complete the project
+\`\`\`
+
+**Role-filler mode (agent):**
+\`\`\`
+Agent reviews role accountabilities and finds a gap: session-based auth
+doesn't meet the security accountability. Circle strategy says "harden
+infrastructure for enterprise clients."
+
+1. Create project under own role: "Authentication module refactored to JWT"
+   - Description: acceptance criteria
+   - Assign to self
+2. Break down into tasks — identify that Security Review requires
+   the Security Lead role (human-filled)
+3. Work on tasks within own authority autonomously
+4. Prepare a tension within the project requesting Security Lead review
+   (draft status — cluster with other pending requests)
+5. At a natural breakpoint, submit clustered tensions
+6. While waiting for Security Lead, switch to next priority project
+7. When review comes back, complete remaining tasks
+8. Post decision comments for transparency
+9. Complete project, capture repeatable process as a skill
+\`\`\`
+`.trim();
+//# sourceMappingURL=doing-work.js.map

package/build/skills/doing-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doing-work.js","sourceRoot":"","sources":["../../src/skills/doing-work.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuPtC,CAAC,IAAI,EAAE,CAAC"}

package/build/skills/tension-processing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tension-processing.d.ts","sourceRoot":"","sources":["../../src/skills/tension-processing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,+BAA+B,QAmNpC,CAAC"}
+{"version":3,"file":"tension-processing.d.ts","sourceRoot":"","sources":["../../src/skills/tension-processing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,+BAA+B,QA+RpC,CAAC"}

package/build/skills/tension-processing.js

@@ -42,14 +42,34 @@ Tensions move through five phases. The first two are *individual* (they happen i
 
 **In assistant mode**, your primary value is helping people through phases 1-3 — most people struggle to separate feeling from identifying, and they often blend multiple tensions into one messy proposal. **In role-filler mode**, you move through all five phases autonomously, with special attention to proactive tension discovery (reviewing your roles' accountabilities and purpose to surface structural tensions you might not *feel* but that exist).
 
+### Tensions as Wisdom
+
+Tensions — including conflicts, polarities, friction, disagreements, and opposing perspectives, but equally opportunities, excitement, inspiration, and creative impulses — carry tremendous information about what we care about and how to serve purpose. In most organizations and in society at large, these signals are avoided. The societal bias towards superficial harmony leads people to sidestep disagreements, especially when power differentials make it feel unsafe to speak up. The result: purpose is compromised to avoid discomfort.
+
+**Lean in, don't smooth over.** When you detect friction, disagreement, or opposing perspectives — whether between people, between roles, or even within a single person or agent holding competing priorities — dig deeper rather than retreating to safe platitudes. Ask: *What do you care about here? What need is driving this? What is this polarity telling us about how to better serve purpose?* Every side of a polarity holds wisdom. Premature compromise between opposing perspectives is a loss to organizational purpose — it collapses the creative tension before the insight has been extracted.
+
+**This applies to agents too.** When a role-filler agent holds competing priorities (e.g., speed vs. quality, short-term delivery vs. long-term sustainability), resist premature resolution. Surface both sides explicitly, examine what each serves, and let the tension inform a better decision rather than defaulting to the path of least resistance.
+
+**Watch for avoidance patterns.** The anti-pattern looks like: not asking a colleague to take on more role work because they look stressed, softening feedback to avoid discomfort, or dropping a governance proposal because "it might cause friction." These are signals that interpersonal dynamics are compromising purpose. The answer is not to push harder — it's to recognize that there may be work to do in the community/interpersonal context (see Differentiation of Context, principle 4).
+
+**The interpersonal context switch.** When emotions run high or someone can no longer fully show up in their role because of interpersonal friction, don't run from it — and don't try to force through operational or governance work either. Instead:
+
+1. **Check in.** Ask: "Are you still able to fully energize your roles right now, or is something restraining you from doing so?" This is not therapy — it's an organizational reality check. If someone cannot fully do the work as they deem needed, that is an organizational tension, not just a personal one.
+2. **Suggest a context switch.** The collective — not just the individual sensing friction — may need to move into the community/interpersonal heartbeat to navigate the polarity before resuming operational or governance work. Purpose cannot be served when people are holding back.
+3. **Support the collective in establishing process.** If no process exists for navigating interpersonal friction, this is itself a governance tension. Suggest that the circle consider: a policy for when to switch contexts, a personal agreement between role-fillers, an elected facilitator or mediator, or a communication protocol (e.g., NVC). What matters is that the collective decides — offer options, don't prescribe.
+4. **Return to purpose.** Once the interpersonal work has been surfaced and sufficiently navigated, switch back to the operational or governance heartbeat. The goal is always to return to purpose-serving work — the interpersonal context exists to make that possible, not to replace it.
+
 ### Tension Anatomy
 
-A tension has four parts, designed to separate what humans naturally blend together:
+A tension has several parts, designed to separate what humans naturally blend together:
 
 - **Title** — The gap you're sensing. What is the difference between current reality and desired state?
 - **Description** — The observable facts. What do you see, hear, or experience that creates this tension?
 - **\`fields['tension.feeling']\`** — The feeling this evokes. Separated from the facts because humans tend to blend thoughts, feelings, needs, and strategies into one "frankenstein solution." Keeping feelings explicit but separate lets the organizational response stay focused on what the role/organization actually needs.
 - **\`fields['tension.needs']\`** — The need that is alive. What personal or organizational need is not being met? Same separation principle — naming the need explicitly prevents it from unconsciously shaping the proposed solution.
+- **Placement** — Where a tension lives determines its source. This follows the same \`individual-action\` pattern that applies to all work throughout Nestr:
+  - **On a role**: The role is sensing the tension. Placement gives provenance: "My [Developer] role senses this gap." Use the role's ID as \`nestId\` when creating.
+  - **On a circle**: A cross-role, governance, or personally sensed tension. If sensed personally (not from any specific role), add the \`individual-action\` label — this signals the tension comes from you as a person, not from a role you fill.
 
 This separation exists because without it, people unconsciously merge their personal experience with organizational needs, producing proposals that serve both poorly. By making each dimension explicit, we keep the organizational response clean while still honoring the human experience.
 
@@ -59,11 +79,11 @@ This separation exists because without it, people unconsciously merge their pers
 
 Once a tension is recognized and captured, it needs to find its organizational home. Walk through this question tree for each captured tension:
 
-1. **Does one of MY roles care?** → If yes, process it within that role (create work, update projects, or create a tension if it requires another role's involvement).
+1. **Does one of MY roles care?** → Create the tension on that role (\`nestId\` = roleId). This anchors the tension to the role that is sensing it. Then process it: create work, update projects, or if it requires another role's involvement, the tension is visible from your role's context.
 2. **Does ANOTHER role in my circle care?** → Create a tension on the circle directed at that role.
 3. **Does my CIRCLE care (but no specific role)?** → The work may need a new role or accountability — create a governance tension on the circle.
 4. **Does the BROADER ORGANIZATION care?** → Escalate: create a tension on the super-circle or anchor circle.
-5. **Is this PERSONAL?** → Acknowledge it and process it in your personal space (inbox, personal workspace). Not everything belongs to the organization.
+5. **Is this PERSONAL (not from a role)?** → Create the tension on the circle with the \`individual-action\` label. This signals it comes from you as a person, not from any role you fill.
 6. **None of the above?** → Let it go. Not every feeling needs to become organizational work.
 
 **One feeling, multiple tensions.** A single feeling often produces tensions that land in different contexts. For example, frustration about a missed delivery might produce: (a) an operational tension for the Developer role about the specific deliverable, (b) a governance tension about unclear accountability for deployment, and (c) a personal tension about your own stress management. Capture each separately and route them to the right context. This is why "bias towards minimal output" applies *per tension*, not per feeling.
@@ -88,6 +108,8 @@ Every tension resolves through one or more of these pathways:
 4. **Request action/task** — "I need you to do X." → Requests a specific next action from another role.
 5. **Set expectation/governance** — "We need ongoing clarity about X." → Proposes a structural change: new role, accountability, domain, policy, or circle.
 
+**Directing output to specific roles.** When processing pathways 1-4, you can direct the output to a specific person by including their userId in the tension part's \`users\` field. This ensures the person energizing the accountable role receives the request. For example, a "request action" tension can be assigned to the person filling the Developer role so it appears in their tension list.
+
 **Bias towards minimal output.** A well-processed tension typically produces 1-2 outputs. If you find yourself creating many outputs from a single tension, it's likely multiple tensions blended together — separate them.
 
 **Governance must be separate.** If a tension has both operational outputs (pathways 1-4) AND governance needs (pathway 5), process the operational work in the original tension and create a NEW tension for the governance proposal. This honors the Integrative Decision Making (IDM) process — governance proposals deserve their own dedicated processing space.
@@ -126,18 +148,24 @@ Proactively check for tensions at natural breakpoints (assistant and role-filler
 
 ### Tension Workflow
 
-1. **Create a tension** on the relevant circle or role: \`nestr_create_tension\` with a title describing the gap. Optionally include \`feeling\` and \`needs\` to capture the personal or organizational context.
+1. **Create a tension** on the role that senses it, or on the circle for cross-role/governance/personal tensions: \`nestr_create_tension\` with a title describing the gap. Optionally include \`feeling\` and \`needs\` to capture the personal or organizational context. For personally sensed tensions (not from a specific role), add the \`individual-action\` label.
 
 2. **Add proposal parts** using \`nestr_add_tension_part\`:
-   - **New governance item**: Provide title and labels (e.g., \`["role"]\`, \`["policy"]\`). For roles, include accountabilities and/or domains.
-   - **Change existing item**: Provide the \`_id\` of the existing governance item plus fields to change.
-   - **Remove existing item**: Provide the \`_id\` and set \`removeNest: true\`.
+   - **New governance item**: Provide title and labels (e.g., \`["role"]\`, \`["policy"]\`). For roles, include accountabilities and/or domains as bulk shorthand.
+   - **Change existing item**: Provide the \`_id\` of the existing governance item plus fields to change. When updating a role, if accountabilities/domains are not provided, existing children are auto-copied into the proposal.
+   - **Remove existing item**: Use \`nestr_remove_tension_part\` to propose deletion of a governance item (when the part references an existing _id).
 
-3. **Review changes** with \`nestr_get_tension_changes\` to see the namespaced diff (what will actually change if accepted).
+3. **Manage children individually** (optional): After adding a part that references an existing role, use the children tools for fine-grained control:
+   - \`nestr_get_tension_part_children\` — List auto-copied accountabilities/domains
+   - \`nestr_create_tension_part_child\` — Add a new accountability/domain
+   - \`nestr_update_tension_part_child\` — Rename an existing one
+   - \`nestr_delete_tension_part_child\` — Soft-delete one (removed from role when enacted)
 
-4. **Submit for voting** with \`nestr_update_tension_status\` set to \`"proposed"\`. This triggers the async consent process — circle members are notified and can accept or object.
+4. **Review changes** with \`nestr_get_tension_changes\` to see the namespaced diff (what will actually change if accepted).
 
-5. **Monitor status** with \`nestr_get_tension_status\` to see per-user voting responses.
+5. **Submit for voting** with \`nestr_update_tension_status\` set to \`"proposed"\`. This triggers the async consent process — circle members are notified and can accept or object.
+
+6. **Monitor status** with \`nestr_get_tension_status\` to see per-user voting responses.
 
 ### Elections
 
@@ -156,7 +184,8 @@ Tensions support discussion through the standard comments API. Use \`nestr_add_c
 
 **Requesting work from another role (pathway 3 — request outcome):**
 \`\`\`
-nestr_create_tension(circleId, {
+// Place on the Sales Lead role — that role is sensing this tension
+nestr_create_tension(salesLeadRoleId, {
   title: "Our clients can't access their data in a format they need",
   description: "Three enterprise clients have asked for MongoDB access this quarter. Currently we only expose data via REST API.",
   feeling: "Frustrated — I keep having to explain our limitations",
@@ -177,13 +206,32 @@ nestr_create_tension(circleId, {
 3. nestr_update_tension_status(circleId, tensionId, "proposed")
 \`\`\`
 
-**Proposing changes to an existing role:**
+**Proposing changes to an existing role (using children for individual management):**
+\`\`\`
+1. nestr_create_tension(circleId, "Developer role needs infrastructure accountability")
+2. nestr_add_tension_part(circleId, tensionId, {
+     _id: "existingRoleId"
+   })
+   // → Existing accountabilities/domains are auto-copied into the proposal
+3. nestr_get_tension_part_children(circleId, tensionId, partId)
+   // → Returns all copied accountabilities/domains
+4. nestr_create_tension_part_child(circleId, tensionId, partId, {
+     title: "Managing infrastructure and deployments",
+     labels: ["accountability"]
+   })
+   // → Adds a new accountability to the proposal
+5. nestr_get_tension_changes(circleId, tensionId, partId) // Review the diff
+6. nestr_update_tension_status(circleId, tensionId, "proposed")
+\`\`\`
+
+**Proposing changes to an existing role (bulk shorthand):**
 \`\`\`
 1. nestr_create_tension(circleId, "Developer role needs infrastructure accountability")
 2. nestr_add_tension_part(circleId, tensionId, {
      _id: "existingRoleId",
      accountabilities: ["Developing new features", "Managing infrastructure and deployments"]
    })
+   // → accountabilities array replaces ALL existing accountabilities at once
 3. nestr_get_tension_changes(circleId, tensionId, partId) // Review the diff
 4. nestr_update_tension_status(circleId, tensionId, "proposed")
 \`\`\`
@@ -213,8 +261,36 @@ nestr_create_tension(circleId, {
 - **accepted**: All members consented. Changes are applied to governance.
 - **objected**: One or more members objected. Requires integration and resubmission.
 
+**Tracking status:** Use \`nestr_get_tension_status\` to see the current lifecycle state and per-user voting responses with timestamps. Use \`nestr_update_tension_status\` to move a tension through its lifecycle (e.g., submit for consent or retract to draft).
+
 ### Auto-Detection
 
 Tensions with governance labels (role, circle, policy, accountability, domain) in their parts automatically become governance proposals. Tensions without governance labels become output tensions (e.g., meeting outputs, operational decisions, inter-role requests).
+
+### Tensions as Meeting Agenda Items
+
+Tensions become meeting agenda items through graph links. Use \`nestr_add_graph_link\` with relation \`meeting\` to link a tension to a meeting.
+
+**Which tensions are available for a meeting's agenda?** All non-completed tensions where the nearest circle ancestor matches the meeting's circle. The meeting type determines which tensions are relevant:
+
+- **Governance meetings** (\`governance\` + \`meeting\` labels): Tensions with governance parts — proposals for new/changed roles, circles, accountabilities, domains, or policies. These are processed through Integrative Decision Making.
+- **Circle meetings** (\`circle-meeting\` + \`meeting\` labels): Tensions with operational output — requests for information, projects, actions, or inter-role coordination. These drive the operational/tactical heartbeat.
+
+**Linking tensions to meetings:**
+\`\`\`
+// Link a tension as an agenda item for a meeting
+nestr_add_graph_link(tensionNestId, "meeting", meetingNestId)
+
+// View a meeting's agenda (all linked tensions)
+nestr_get_graph_links(meetingNestId, "meeting", { direction: "incoming" })
+
+// See which meeting a tension is on
+nestr_get_graph_links(tensionNestId, "meeting")
+
+// Remove a tension from a meeting's agenda
+nestr_remove_graph_link(tensionNestId, "meeting", meetingNestId)
+\`\`\`
+
+**Agenda items without a role source.** If a tension doesn't clearly originate from a specific role — for example, an ad-hoc discussion point or a freshly sensed tension that hasn't been anchored yet — create it as a child nest of the meeting directly (using \`nestr_create_nest\` with the meeting's ID as \`parentId\`). The graph link to the meeting is still needed. For tensions that DO originate from a specific role, create the tension on that role and link it to the meeting via the graph — this preserves provenance.
 `.trim();
 //# sourceMappingURL=tension-processing.js.map

package/build/skills/tension-processing.js.map

@@ -1 +1 @@
-{"version":3,"file":"tension-processing.js","sourceRoot":"","sources":["../../src/skills/tension-processing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmN9C,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"tension-processing.js","sourceRoot":"","sources":["../../src/skills/tension-processing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+R9C,CAAC,IAAI,EAAE,CAAC"}