@rolexjs/core 1.4.0-dev-20260305092016 → 1.4.0-dev-20260306081757

package/dist/index.js

@@ -2124,7 +2124,7 @@ var processes = {
   abandon: "Feature: abandon \u2014 abandon a plan\n  Mark a plan as dropped and create an encounter.\n  Call this when a plan's strategy is no longer viable. Even failed plans produce learning.\n\n  Scenario: Abandon a plan\n    Given a focused plan exists\n    And the plan's strategy is no longer viable\n    When abandon is called\n    Then the plan is tagged #abandoned and stays in the tree\n    And an encounter is created under the role\n    And the encounter can be reflected on \u2014 failure is also learning\n\n  Scenario: Writing the encounter Gherkin\n    Given the encounter records what happened \u2014 even failure is a raw experience\n    Then the Feature title describes what was attempted and why it was abandoned\n    And Scenarios capture what was tried, what went wrong, and what was learned\n    And the tone is concrete and honest \u2014 failure produces the richest encounters",
   activate: "Feature: activate \u2014 enter a role\n  Project the individual's full state including identity, goals,\n  and organizational context. This is the entry point for working as a role.\n\n  Scenario: Activate an individual\n    Given an individual exists in society\n    When activate is called with the individual reference\n    Then the full state tree is projected\n    And identity, goals, and organizational context are loaded\n    And the individual becomes the active role",
   complete: "Feature: complete \u2014 complete a plan\n  Mark a plan as done and create an encounter.\n  Call this when all tasks in the plan are finished and the strategy succeeded.\n\n  Scenario: Complete a plan\n    Given a focused plan exists\n    And its tasks are done\n    When complete is called\n    Then the plan is tagged #done and stays in the tree\n    And an encounter is created under the role\n    And the encounter can be reflected on for learning\n\n  Scenario: Writing the encounter Gherkin\n    Given the encounter records what happened \u2014 a raw account of the experience\n    Then the Feature title describes what was accomplished by this plan\n    And Scenarios capture what the strategy was, what worked, and what resulted\n    And the tone is concrete and specific \u2014 tied to this particular plan",
-  direct: 'Feature: direct \u2014 stateless world-level executor\n  Execute commands and load resources without an active role.\n  Direct operates as an anonymous observer \u2014 no role identity, no role context.\n  For operations as an active role, use the use tool instead.\n\n  Scenario: When to use "direct" vs "use"\n    Given no role is activated \u2014 I am an observer\n    When I need to query or operate on the world\n    Then direct is the right tool\n    And once a role is activated, use the use tool for role-level actions\n\n  Scenario: Execute a RoleX command\n    Given the locator starts with `!`\n    When direct is called with the locator and named args\n    Then the command is parsed as `namespace.method`\n    And dispatched to the corresponding RoleX API\n\n  Scenario: Load a ResourceX resource\n    Given the locator does not start with `!`\n    When direct is called with the locator\n    Then the locator is passed to ResourceX for resolution\n    And the resource is loaded and returned',
+  direct: 'Feature: direct \u2014 stateless world-level executor\n  Execute commands and load resources without an active role.\n  Direct operates as an anonymous observer \u2014 no role identity, no role context.\n  For operations as an active role, use the use tool instead.\n\n  Scenario: When to use "direct" vs "use"\n    Given no role is activated \u2014 I am an observer\n    When I need to query or operate on the world\n    Then direct is the right tool\n    And once a role is activated, use the use tool for role-level actions\n\n  Scenario: Execute a RoleX command\n    Given the locator starts with `!`\n    When direct is called with command and args\n    Then the command is parsed as `namespace.method`\n    And dispatched to the corresponding RoleX API\n    And all named parameters go inside the args object\n    And example: command = "!census.list", args = { type: "individual" }\n\n  Scenario: Load a ResourceX resource\n    Given the locator does not start with `!`\n    When direct is called with the locator\n    Then the locator is passed to ResourceX for resolution\n    And the resource is loaded and returned',
   finish: "Feature: finish \u2014 complete a task\n  Mark a task as done and create an encounter.\n  The encounter records what happened and can be reflected on for learning.\n\n  Scenario: Finish a task\n    Given a task exists\n    When finish is called on the task\n    Then the task is tagged #done and stays in the tree\n    And an encounter is created under the role\n\n  Scenario: Finish with experience\n    Given a task is completed with a notable learning\n    When finish is called with an optional experience parameter\n    Then the experience text is attached to the encounter\n\n  Scenario: Finish without encounter\n    Given a task is completed with no notable learning\n    When finish is called without the encounter parameter\n    Then the task is tagged #done but no encounter is created\n    And the task stays in the tree \u2014 visible via focus on the parent goal\n\n  Scenario: Writing the encounter Gherkin\n    Given the encounter records what happened \u2014 a raw account of the experience\n    Then the Feature title describes what was done\n    And Scenarios capture what was done, what was encountered, and what resulted\n    And the tone is concrete and specific \u2014 tied to this particular task",
   focus: "Feature: focus \u2014 view or switch focused goal\n  View the current goal's state, or switch focus to a different goal.\n  Subsequent plan and todo operations target the focused goal.\n  Only goal ids are accepted \u2014 plan, task, or other node types are rejected.\n\n  Scenario: View current goal\n    Given an active goal exists\n    When focus is called without a name\n    Then the current goal's state tree is projected\n    And plans and tasks under the goal are visible\n\n  Scenario: Switch focus\n    Given multiple goals exist\n    When focus is called with a goal id\n    Then the focused goal switches to the named goal\n    And subsequent plan and todo operations target this goal\n\n  Scenario: Reject non-goal ids\n    Given a plan or task id is passed to focus\n    Then focus returns an error indicating the node type\n    And suggests using the correct goal id instead",
   forget: "Feature: forget \u2014 remove a node from the individual\n  Remove any node under the individual by its id.\n  Use forget to discard outdated knowledge, stale encounters, or obsolete skills.\n\n  Scenario: Forget a node\n    Given a node exists under the individual (principle, procedure, experience, encounter, etc.)\n    When forget is called with the node's id\n    Then the node and its subtree are removed\n    And the individual no longer carries that knowledge or record\n\n  Scenario: When to use forget\n    Given a principle has become outdated or incorrect\n    And a procedure references a skill that no longer exists\n    And an encounter or experience has no further learning value\n    When the role decides to discard it\n    Then call forget with the node id",
@@ -2178,7 +2178,7 @@ var processes = {
   reflect: 'Feature: reflect \u2014 encounter to experience\n  Consume an encounter and create an experience.\n  Experience captures what was learned in structured form.\n  This is the first step of the cognition cycle.\n\n  Scenario: Reflect on an encounter\n    Given an encounter exists from a finished task or completed plan\n    When reflect is called with encounter ids and an experience id\n    Then the encounters are consumed\n    And an experience is created under the role\n    And the experience can be distilled into knowledge via realize or master\n\n  Scenario: Experience ID convention\n    Given the id is keywords from the experience content joined by hyphens\n    Then "Token refresh matters" becomes id "token-refresh-matters"\n    And "ID ownership determines generation strategy" becomes id "id-ownership-determines-generation-strategy"\n\n  Scenario: Writing the experience Gherkin\n    Given the experience captures insight \u2014 what was learned, not what was done\n    Then the Feature title names the cognitive insight or pattern discovered\n    And Scenarios describe the learning points abstracted from the concrete encounter\n    And the tone shifts from event to understanding \u2014 no longer tied to a specific task',
   skill: "Feature: skill \u2014 load full skill content\n  Load the complete skill instructions by ResourceX locator.\n  This is progressive disclosure layer 2 \u2014 on-demand knowledge injection.\n\n  Scenario: Load a skill\n    Given a procedure exists in the role with a locator\n    When skill is called with the locator\n    Then the full SKILL.md content is loaded via ResourceX\n    And the content is injected into the AI's context\n    And the AI can now follow the skill's detailed instructions",
   todo: "Feature: todo \u2014 add a task to a plan\n  A task is a concrete, actionable unit of work.\n  Each task has Gherkin scenarios describing the steps and expected outcomes.\n\n  Scenario: Create a task\n    Given a focused plan exists\n    And a Gherkin source describing the task\n    When todo is called with the source\n    Then a new task node is created under the plan\n    And the task can be finished when completed\n\n  Scenario: Writing the task Gherkin\n    Given the task is a concrete, actionable unit of work\n    Then the Feature title names what will be done \u2014 a single deliverable\n    And Scenarios describe the steps and expected outcomes of the work\n    And the tone is actionable \u2014 clear enough that someone can start immediately",
-  use: 'Feature: use \u2014 act as the current role\n  Execute commands and load resources as the active role.\n  Use requires an active role \u2014 the role is the subject performing the action.\n  For operations before activating a role, use the direct tool instead.\n\n  Scenario: When to use "use" vs "direct"\n    Given a role is activated \u2014 I am someone\n    When I perform operations through use\n    Then the operation happens in the context of my role\n    And use is for role-level actions \u2014 acting in the world as myself\n\n  Scenario: Execute a RoleX command\n    Given the locator starts with `!`\n    When use is called with the locator and named args\n    Then the command is parsed as `namespace.method`\n    And dispatched to the corresponding RoleX API\n\n  Scenario: Load a ResourceX resource\n    Given the locator does not start with `!`\n    When use is called with the locator\n    Then the locator is passed to ResourceX for resolution\n    And the resource is loaded and returned',
+  use: 'Feature: use \u2014 act as the current role\n  Execute commands and load resources as the active role.\n  Use requires an active role \u2014 the role is the subject performing the action.\n  For operations before activating a role, use the direct tool instead.\n\n  Scenario: When to use "use" vs "direct"\n    Given a role is activated \u2014 I am someone\n    When I perform operations through use\n    Then the operation happens in the context of my role\n    And use is for role-level actions \u2014 acting in the world as myself\n\n  Scenario: Execute a RoleX command\n    Given the locator starts with `!`\n    When use is called with command and args\n    Then the command is parsed as `namespace.method`\n    And dispatched to the corresponding RoleX API\n    And all named parameters go inside the args object\n    And example: command = "!org.hire", args = { org: "dp", individual: "sean" }\n\n  Scenario: Load a ResourceX resource\n    Given the locator does not start with `!`\n    When use is called with the locator\n    Then the locator is passed to ResourceX for resolution\n    And the resource is loaded and returned',
   want: 'Feature: want \u2014 declare a goal\n  Declare a new goal for a role.\n  A goal describes a desired outcome with Gherkin scenarios as success criteria.\n\n  Scenario: Declare a goal\n    Given an active role exists\n    And a Gherkin source describing the desired outcome\n    When want is called with the source\n    Then a new goal node is created under the role\n    And the goal becomes the current focus\n    And subsequent plan and todo operations target this goal\n\n  Scenario: Writing the goal Gherkin\n    Given the goal describes a desired outcome \u2014 what success looks like\n    Then the Feature title names the outcome in concrete terms\n    And Scenarios define success criteria \u2014 each scenario is a testable condition\n    And the tone is aspirational but specific \u2014 "users can log in" not "improve auth"'
 };
 var world = {
@@ -2280,6 +2280,95 @@ var world = {
     Then tool names and concept names are appropriate \u2014 they are the domain language
     And this rule applies to end-user communication, not developer communication`,
   execution: "Feature: Execution \u2014 the doing cycle\n  The role pursues goals through a structured lifecycle.\n  activate \u2192 want \u2192 plan \u2192 todo \u2192 finish \u2192 complete or abandon.\n\n  Scenario: Declare a goal\n    Given I know who I am via activate\n    When I want something \u2014 a desired outcome\n    Then I declare it with want(id, goal)\n    And focus automatically switches to this new goal\n\n  Scenario: Plan and create tasks\n    Given I have a focused goal\n    Then I call plan(id, plan) to break it into logical phases\n    And I call todo(id, task) to create concrete, actionable tasks\n\n  Scenario: Execute and finish\n    Given I have tasks to work on\n    When I complete a task\n    Then I call finish(id) to mark it done\n    And an encounter is created \u2014 a raw record of what happened\n    And I optionally capture what happened via the encounter parameter\n\n  Scenario: Complete or abandon a plan\n    Given tasks are done or the plan's strategy is no longer viable\n    When the plan is fulfilled I call complete()\n    Or when the plan should be dropped I call abandon()\n    Then an encounter is created for the cognition cycle\n\n  Scenario: Goals are long-term directions\n    Given goals are managed with want and forget\n    When a goal is no longer needed\n    Then I call forget to remove it\n    And learning is captured at the plan and task level through encounters\n\n  Scenario: Multiple goals\n    Given I may have several active goals\n    When I need to switch between them\n    Then I call focus(id) to change the currently focused goal\n    And subsequent plan and todo operations target the focused goal",
+  issue: `Feature: Issue \u2014 persistent structured collaboration beyond a single context
+  AI individuals face a fundamental challenge: context breaks.
+  Each new session starts fresh \u2014 identity and knowledge survive, but the working state is lost.
+  Like humans writing journals and memos, individuals need externalized records
+  that persist across sessions and across individuals.
+
+  Issue is the externalized, structured collaboration primitive of the RoleX world.
+  It enables both self-collaboration (same individual, different sessions)
+  and inter-individual collaboration (different individuals, asynchronous).
+
+  Scenario: Why issues exist
+    Given AI individuals have a context window limit
+    And each new session loses the previous working state
+    And multiple individuals may need to coordinate without being active simultaneously
+    When structured, persistent, discoverable records are needed
+    Then issues serve as externalized working memory for the society
+    And they survive context breaks, session restarts, and individual switches
+
+  Scenario: Self-collaboration \u2014 continuity across sessions
+    Given an individual is working on something that spans multiple sessions
+    When the context window resets or a new session begins
+    Then the individual can publish or check issues to restore working context
+    And comments serve as a journal \u2014 recording progress, decisions, and next steps
+    And the issue persists until explicitly closed, regardless of how many sessions pass
+
+  Scenario: Inter-individual collaboration \u2014 asynchronous coordination
+    Given multiple individuals need to work together
+    And they are never active simultaneously
+    When one individual publishes an issue or leaves a comment
+    Then other individuals can discover it, respond, and contribute
+    And assignee indicates who should act next
+    And labels categorize across concerns
+
+  Scenario: Relationship to goals and tasks
+    Given goals express intent \u2014 what I want to achieve
+    And tasks express action \u2014 what I am doing right now
+    When an issue is something that needs ongoing attention and discussion
+    Then issues may inspire goals, or goals may spawn issues
+    And issues may be resolved by tasks, or tasks may surface new issues
+    But issues are independent \u2014 they belong to the society, not to any single individual's goal tree
+
+  Scenario: Publish a new issue
+    Given I need to raise a topic for attention
+    When I call use("!issue.publish", { title, body, author, assignee? })
+    Then a new issue is created with an auto-incremented number
+    And author should be the active individual's id
+
+  Scenario: Browse and view issues
+    Given I need to see what issues exist
+    When I call use("!issue.list", { status?, author?, assignee?, label? })
+    Then matching issues are returned ordered by number descending
+    When I need details of a specific issue
+    Then I call use("!issue.get", { number })
+
+  Scenario: Update, close, and reopen
+    Given I need to manage an issue's lifecycle
+    When I call use("!issue.update", { number, title?, body?, assignee? })
+    Then the specified fields are updated
+    When resolved I call use("!issue.close", { number })
+    And if it needs more work I call use("!issue.reopen", { number })
+
+  Scenario: Assign and discuss
+    Given I need to delegate or discuss
+    When I call use("!issue.assign", { number, assignee })
+    Then the issue is assigned to another individual
+    When I call use("!issue.comment", { number, body, author })
+    Then a comment is added to the threaded discussion
+    And I can view all comments with use("!issue.comments", { number })
+
+  Scenario: Label for categorization
+    Given I want to categorize issues
+    When I call use("!issue.label", { number, label })
+    Then the label is attached \u2014 auto-created if new
+    And I can remove it with use("!issue.unlabel", { number, label })
+
+  Scenario: Command reference
+    Given the following commands are available:
+      | command          | required args          | optional args                   |
+      | !issue.publish   | title, body, author    | assignee                        |
+      | !issue.get       | number                 |                                 |
+      | !issue.list      |                        | status, author, assignee, label |
+      | !issue.update    | number                 | title, body, assignee           |
+      | !issue.close     | number                 |                                 |
+      | !issue.reopen    | number                 |                                 |
+      | !issue.assign    | number, assignee       |                                 |
+      | !issue.comment   | number, body, author   |                                 |
+      | !issue.comments  | number                 |                                 |
+      | !issue.label     | number, label          |                                 |
+      | !issue.unlabel   | number, label          |                                 |`,
   gherkin: 'Feature: Gherkin \u2014 the universal language\n  Everything in RoleX is expressed as Gherkin Feature files.\n  Gherkin is not just for testing \u2014 it is the language of identity, goals, and knowledge.\n\n  Scenario: Feature and Scenario convention\n    Given RoleX uses Gherkin to represent goals, plans, tasks, experience, and knowledge\n    Then a Feature represents one independent concern \u2014 one topic, explained fully\n    And Scenarios represent different situations or conditions within that concern\n    And Given/When/Then provides narrative structure within each scenario\n\n  Scenario: Writing Gherkin for RoleX\n    Given the AI creates goals, plans, tasks, and experiences as Gherkin\n    Then keep it descriptive and meaningful \u2014 living documentation, not test boilerplate\n    And use Feature as the title \u2014 what this concern is about\n    And use Scenario for specific situations within that concern\n    And each Feature focuses on one concern \u2014 separate unrelated topics into their own Features\n\n  Scenario: Valid step keywords\n    Given the only valid step keywords are Given, When, Then, And, But\n    When writing steps that express causality or explanation\n    Then use And to chain the reason as a follow-up fact\n    And example: "Then use RoleX tools" followed by "And RoleX tools feed the growth loop"\n\n  Scenario: Expressing causality\n    Given you want to write "Then X because Y"\n    Then rewrite as two steps \u2014 "Then X" followed by "And Y" stating the reason as a fact',
   memory: `Feature: Memory \u2014 when to reflect
   Reflection is how encounters become experience.
@@ -2321,22 +2410,23 @@ var world = {
 
   Scenario: How to read use instructions in skills
     Given a skill document contains use("!resource.add", { path: "..." })
-    Then this means: call the MCP use tool with command "!resource.add" and path "..."
-    And all named arguments are passed as flat top-level parameters alongside command
+    Then this means: call the MCP use tool with command "!resource.add"
+    And all named arguments go inside the args object parameter
+    And example: command = "!resource.add", args = { path: "/absolute/path" }
     And always use the MCP use tool for RoleX operations
     And this applies to every use("...") pattern you encounter in any skill or documentation
 
   Scenario: ! prefix dispatches to RoleX runtime
     Given the command starts with !
     Then it is parsed as !namespace.method
-    And dispatched to the corresponding RoleX API with named args
+    And dispatched to the corresponding RoleX API with the args object
 
   Scenario: Mandatory skill loading before execution
     Given your procedures list the skills you have
     When you need to execute a command you have not seen in a loaded skill
     Then you MUST call skill(locator) first to load the full instructions
     And the loaded skill will tell you the exact command name and arguments
-    And only then call use with the correct command and flat named parameters
+    And only then call use with the correct command and args object
     And do not use commands from other roles' descriptions \u2014 only your own skills
 
   Scenario: NEVER guess commands
@@ -2576,7 +2666,7 @@ var tools = [
       args: {
         type: "record",
         required: false,
-        description: "Named arguments for the command. Load the relevant skill first to learn what args to pass."
+        description: 'Named arguments object for the command. All parameters (id, content, org, individual, etc.) go inside this object. Example: { id: "sean", content: "Feature: ..." }. Load the relevant skill first to learn what args to pass.'
       }
     }
   },
@@ -2591,7 +2681,7 @@ var tools = [
       args: {
         type: "record",
         required: false,
-        description: "Named arguments for the command. Load the relevant skill first to learn what args to pass."
+        description: 'Named arguments object for the command. All parameters (id, content, org, individual, etc.) go inside this object. Example: { type: "individual" }. Load the relevant skill first to learn what args to pass.'
       }
     }
   }