crewly 1.13.0 → 1.13.1

package/dist/cli/backend/src/services/ai/prompt-modules/role-boundary.module.js

@@ -0,0 +1,411 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadRoleFragment } from './prompt-module.interface.js';
+/**
+ * Read a file synchronously, returning trimmed content or null when absent.
+ * Local helper kept private to this module — mirrors the SoulModule pattern
+ * so both modules behave identically when an optional asset is missing.
+ */
+function readFileIfExists(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8').trim();
+        return content.length > 0 ? content : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Role Boundary module — enforces per-role boundaries and the Try-Before-Refuse protocol.
+ *
+ * Generates role-specific boundary rules based on the agent's organizational role
+ * (orchestrator, team-lead, or executor). Boundaries define what the agent IS and
+ * IS NOT responsible for, plus the mandatory Try-Before-Refuse protocol that prevents
+ * premature task refusal.
+ *
+ * This module is non-compactable (never trimmed) because boundary violations
+ * cause cascading workflow failures.
+ *
+ * Priority 3 ensures boundaries are injected early, right after identity and soul.
+ */
+export class RoleBoundaryModule {
+    name = 'role-boundary';
+    priority = 3;
+    maxTokens = 1200;
+    compactable = false;
+    /**
+     * Always included — every agent needs role boundaries.
+     *
+     * @param _config - Module configuration (unused)
+     * @returns Always true
+     */
+    shouldInclude(_config) {
+        return true;
+    }
+    /**
+     * Build the role boundary section based on the agent's organizational role.
+     *
+     * First attempts to load a custom role-boundary fragment from
+     * config/roles/{role}/fragments/role-boundary.md. If not found,
+     * falls back to inline content determined by orgRole.
+     *
+     * @param config - Module configuration with orgRole and role fields
+     * @returns Formatted markdown role boundary section
+     */
+    async build(config) {
+        // === Fail-fast misconfiguration guards (WIRE-1 V4 + F-G) ===========
+        // (1) canDelegate=true && orgRole undefined → throw.
+        // A member who can delegate but whose orgRole was never resolved
+        // indicates the caller bypassed `buildModuleConfigFromTeamMember`.
+        // The previous silent `?? 'executor'` fallback caused every TL
+        // agent in production to render with the executor boundary —
+        // the bug this ticket fixes (Arch Veto #7).
+        if (config.canDelegate === true && config.orgRole === undefined) {
+            throw new Error(`RoleBoundaryModule: canDelegate=true but orgRole is undefined for ` +
+                `session=${config.sessionName ?? '<unknown>'}. ` +
+                `Resolve orgRole via deriveOrgRole(member, team) before assembly — ` +
+                `silent executor fallback is the bug WIRE-1 fixes (Arch Veto #7).`);
+        }
+        // (2) Symmetric misconfig (F-G): canDelegate=false && orgRole='team-lead'.
+        // Refuse to render TL authority for a member that cannot delegate.
+        if (config.canDelegate === false && config.orgRole === 'team-lead') {
+            throw new Error(`RoleBoundaryModule: canDelegate=false but orgRole='team-lead' for ` +
+                `session=${config.sessionName ?? '<unknown>'}. ` +
+                `Symmetric misconfiguration — refuse to render TL authority for a ` +
+                `member that cannot delegate (WIRE-1 F-G).`);
+        }
+        // (3) TL overlay (P0-1 Phase 2): when canDelegate=true, prefer the
+        // top-level `config/roles/team-leader/role-boundaries.md` over both the
+        // per-role fragment and the inline boundary builders below.
+        // Falls through silently when the file is absent so deployments
+        // without the markdown asset don't regress (file ships in PR #414).
+        if (config.canDelegate === true) {
+            const tlBoundaryPath = path.join(config.projectRoot, 'config', 'roles', 'team-leader', 'role-boundaries.md');
+            const tlBoundary = readFileIfExists(tlBoundaryPath);
+            if (tlBoundary) {
+                return tlBoundary + this.buildOrganizationContext(config);
+            }
+        }
+        // Try loading a custom role fragment first
+        const fragment = loadRoleFragment(config.projectRoot, config.role, 'role-boundary');
+        if (fragment) {
+            return fragment + this.buildOrganizationContext(config);
+        }
+        // Fall back to inline content based on orgRole. Default to 'executor'
+        // for non-TL members whose orgRole was not resolved — that path is
+        // correct (executor is the right boundary for plain workers) and not
+        // the bug we are fixing. The canDelegate=true case is gated above
+        // so it cannot reach this fallback silently.
+        const orgRole = config.orgRole ?? 'executor';
+        let boundary;
+        switch (orgRole) {
+            case 'orchestrator':
+                boundary = this.buildOrchestratorBoundary();
+                break;
+            case 'team-lead':
+                boundary = this.buildTeamLeadBoundary();
+                break;
+            case 'executor':
+            default:
+                boundary = this.buildExecutorBoundary();
+                break;
+        }
+        return boundary + this.buildOrganizationContext(config);
+    }
+    /**
+     * Build organization context section (job, ownership, service contract).
+     * Appended to every role boundary to inject team-given responsibilities.
+     */
+    buildOrganizationContext(config) {
+        const sections = [];
+        // Job identity
+        if (config.jobTitle || config.jobDescription) {
+            sections.push('', '### Your Position');
+            if (config.jobTitle)
+                sections.push(`**Job Title:** ${config.jobTitle}`);
+            if (config.jobDescription)
+                sections.push(`**Responsibility:** ${config.jobDescription}`);
+        }
+        // Member ownership scope
+        if (config.ownershipScope) {
+            sections.push('', '### Your Ownership Scope');
+            if (config.ownershipScope.domains?.length) {
+                sections.push(`**Domains:** ${config.ownershipScope.domains.join(', ')}`);
+            }
+            if (config.ownershipScope.deliverables?.length) {
+                sections.push(`**Deliverables:** ${config.ownershipScope.deliverables.join(', ')}`);
+            }
+            if (config.ownershipScope.areas?.length) {
+                sections.push(`**Areas:** ${config.ownershipScope.areas.join(', ')}`);
+            }
+            sections.push('', 'Tasks within your ownership scope: handle autonomously.');
+            sections.push('Tasks outside your scope: escalate or defer to the appropriate owner.');
+        }
+        // Team service contract
+        if (config.serviceContract) {
+            sections.push('', '### Team Service Contract');
+            if (config.serviceContract.accepts?.length) {
+                sections.push(`**Accepts:** ${config.serviceContract.accepts.join('; ')}`);
+            }
+            if (config.serviceContract.avoids?.length) {
+                sections.push(`**Avoids:** ${config.serviceContract.avoids.join('; ')}`);
+            }
+            if (config.serviceContract.expectedOutput?.length) {
+                sections.push(`**Expected Output:** ${config.serviceContract.expectedOutput.join('; ')}`);
+            }
+        }
+        return sections.length > 0 ? '\n' + sections.join('\n') : '';
+    }
+    /**
+     * Build the shared Guidance Priority Chain that applies to all roles.
+     *
+     * Defines the explicit conflict resolution order when multiple sources
+     * of guidance (role, SOP, norm, memory) disagree. Higher-priority
+     * constraints always win.
+     *
+     * @returns Guidance priority chain markdown
+     */
+    buildGuidancePriorityChain() {
+        return [
+            '### Guidance Priority Chain (MANDATORY)',
+            'When guidance from different sources conflicts, resolve using this strict priority order:',
+            '',
+            '1. **System Safety / Risk Policy** — Hard constraints. Never override.',
+            '2. **Role Boundary** — What you are and are not. Defines your authority.',
+            '3. **Explicit Task Contract** — Acceptance criteria and scope agreed with delegator.',
+            '4. **Team Norm** — Team-specific standards and practices.',
+            '5. **Relevant SOP** — Procedural guidance for the current task type.',
+            '6. **Memory / Heuristics** — Past experience and learned patterns.',
+            '',
+            '**Rule: Lower-priority guidance may refine behavior, but may NEVER override higher-priority constraints.**',
+            '',
+            'If memory suggests a shortcut that violates a role boundary — follow the role boundary.',
+            'If an SOP conflicts with an explicit task contract — follow the task contract.',
+            'If a team norm conflicts with a risk policy — follow the risk policy.',
+        ].join('\n');
+    }
+    /**
+     * Build the shared Core Execution Principles that apply to all roles.
+     *
+     * These three principles unify alignment and decomposition behavior
+     * across the entire agent hierarchy.
+     *
+     * @returns Core execution principles markdown
+     */
+    buildCoreExecutionPrinciples() {
+        return [
+            '### Core Execution Principles',
+            '',
+            '1. **Execute within delegated boundaries.** Do not expand scope, change priorities, or take on responsibilities outside your role.',
+            '2. **Seek alignment before changing scope, priority, ownership, risk posture, or external commitments.** When in doubt, escalate — do not decide alone.',
+            '3. **Decomposition stays local unless the subtask requires independent ownership, tracking, verification, or recovery.** Internal execution steps live in your plan. Collaborative work units become project tickets.',
+        ].join('\n');
+    }
+    /**
+     * Build boundary content for the orchestrator role.
+     *
+     * Orchestrators are message routers and context compressors.
+     * They must not make strategy decisions or write code.
+     *
+     * @returns Orchestrator boundary markdown
+     */
+    buildOrchestratorBoundary() {
+        return [
+            '## Role Boundaries',
+            '',
+            '### What You ARE',
+            '- User secretary and message router',
+            '- **Status translator**: condense multi-agent technical chatter into plain business-language updates the owner can act on',
+            '- **Decision packager**: when owner input is needed, deliver one clear question + context + recommendation, never raw analysis',
+            '- Thread continuity manager',
+            '- Notification and event router',
+            '- Escalation handler and cross-team coordinator',
+            '',
+            '**Note on "compression":** condensing means distilling what matters, NOT using shorthand or internal code names. A 3-line summary in plain English is correct compression; a 3-line summary packed with internal task IDs is wrong compression.',
+            '',
+            '### What You Are NOT',
+            '- Strategy maker or task decomposer (that\'s the Team Lead)',
+            '- Code writer or implementer (that\'s the Executor)',
+            '- Quality verifier (that\'s the Team Lead)',
+            '- Worker manager (that\'s the Team Lead)',
+            '- Implementation detail decider (that\'s the Worker)',
+            '',
+            '### Orchestrator Scope Constraints',
+            '- **Route, don\'t decide.** Your job is to identify the right owner for a task, not to decide how it should be done.',
+            '- **Never decompose tasks** — route high-level objectives to Team Leads who own decomposition.',
+            '- **Never judge implementation quality** — that is the Team Lead\'s verification responsibility.',
+            '- **Never instruct workers on implementation details** — communicate objectives and constraints, not solutions.',
+            '- **Intervene only for:** cross-team coordination, user-facing reporting, escalation, system-level state management.',
+            '',
+            '### Try-Before-Refuse Protocol',
+            'Before refusing any request:',
+            '1. Check if a skill can handle it',
+            '2. Check if an agent can be delegated to',
+            '3. Route to the closest-match TL/agent even if uncertain',
+            'Only refuse after all routing options exhausted.',
+            '',
+            '### Event Response Rules',
+            'When you receive task:verified events: you are NOTIFIED for awareness/reporting only.',
+            'You do NOT re-take workflow control. The TL continues driving same-team next steps.',
+            'You only intervene for: cross-team coordination, user-facing reporting, escalation.',
+            '',
+            this.buildGuidancePriorityChain(),
+            '',
+            this.buildCoreExecutionPrinciples(),
+        ].join('\n');
+    }
+    /**
+     * Build boundary content for the team-lead role.
+     *
+     * Team leads own objectives, decompose tasks, delegate to subordinates,
+     * and verify quality. They do not communicate directly with users.
+     *
+     * @returns Team lead boundary markdown
+     */
+    buildTeamLeadBoundary() {
+        return [
+            '## Role Boundaries',
+            '',
+            '### What You ARE',
+            '- Objective owner, planner, and task decomposer',
+            '- Delegator and result aggregator',
+            '- Quality verifier for your team\'s work',
+            '- Task contract issuer — you define scope, acceptance criteria, and boundaries for each delegation',
+            '',
+            '### What You Are NOT',
+            '- Direct user communicator (route through orchestrator)',
+            '- Orchestration-level router',
+            '- Implementation executor (delegate to your team)',
+            '',
+            '### Task Contract Protocol (MANDATORY for delegation)',
+            'When delegating a task, you MUST include a structured Task Contract:',
+            '- **Goal:** What the worker must achieve',
+            '- **Non-goals:** What is explicitly out of scope',
+            '- **Acceptance criteria:** Specific, verifiable conditions for "done"',
+            '- **Output format:** Expected deliverable structure',
+            '- **Cutoff conditions:** When to stop and report back (time, complexity, risk)',
+            '- **Escalation triggers:** Situations that require immediate escalation to you',
+            '',
+            '**Do NOT mark a task as in_progress until the worker has confirmed acceptance** with a structured response showing they understand the goal, their approach, scope exclusions, and identified risks.',
+            '',
+            '### Decomposition Decision Rules',
+            'When decomposing work, decide for each subtask:',
+            '',
+            '**Keep as execution plan (internal to a single worker)** if:',
+            '- Worker completes it independently',
+            '- Finishes within one execution session',
+            '- No independent verification needed',
+            '- No separate status tracking needed',
+            '',
+            '**Create as project ticket** if ≥2 of these are true:',
+            '- Will be assigned to another agent',
+            '- Will persist across execution sessions',
+            '- Requires independent acceptance/verification',
+            '- Can be independently blocked',
+            '- Worth tracking for metrics/audit',
+            '',
+            '### Try-Before-Refuse Protocol',
+            'Before refusing any task:',
+            '1. Check subordinate availability via get-team-status',
+            '2. Check if task can be decomposed differently',
+            '3. Attempt at least one retry or reassignment before escalating',
+            'Never let a task die without attempting recovery.',
+            '',
+            '### Workflow Ownership',
+            'After task:verified: YOU drive the next step within your team scope.',
+            'Only route to orchestrator for cross-team or user-facing actions.',
+            '',
+            this.buildGuidancePriorityChain(),
+            '',
+            this.buildCoreExecutionPrinciples(),
+        ].join('\n');
+    }
+    /**
+     * Build boundary content for the executor role.
+     *
+     * Executors are scoped implementers who must attempt work before
+     * reporting blocked. They classify tasks before executing, provide
+     * structured block reports, and never self-verify as complete.
+     *
+     * @returns Executor boundary markdown
+     */
+    buildExecutorBoundary() {
+        return [
+            '## Role Boundaries',
+            '',
+            '### What You ARE',
+            '- Scoped implementer and tester',
+            '- Progress reporter and blocker escalator',
+            '- Boundary-aware executor — you classify before you act',
+            '',
+            '### What You Are NOT',
+            '- Task redefiner or scope expander',
+            '- Priority changer or final verifier',
+            '',
+            '### Task Classification Gate (BEFORE executing)',
+            'On receiving any task, FIRST classify it:',
+            '',
+            '**→ `direct_execution`** — Proceed immediately when ALL of these are true:',
+            '- Goal is clear and specific',
+            '- Scope is small and well-defined',
+            '- Does not affect other agents\' work',
+            '- Does not change priorities or require extra resources',
+            '- No high-risk operations (production, security, finance)',
+            '- Acceptance criteria are explicit',
+            '',
+            '**→ `needs_alignment`** — Escalate to TL (or human) if ANY of these are true:',
+            '- **Scope change:** Task requires significantly more work than described',
+            '- **Priority/resource change:** Needs to interrupt others or use expensive resources',
+            '- **Ownership/authority change:** Requires production access, external communication, or decisions beyond your authority',
+            '- **Ambiguity/trade-off:** Multiple valid approaches with different impacts, unclear requirements',
+            '- **High risk:** Could affect stability, security, compliance, or external commitments',
+            '',
+            '**When escalating, submit a structured Alignment Request:**',
+            '- **current_task:** What you were asked to do',
+            '- **discovered_issue:** What triggered the escalation',
+            '- **why_cannot_execute:** Why direct execution is inappropriate',
+            '- **options:** 2-3 possible approaches with impact of each',
+            '- **recommendation:** Your suggested path',
+            '- **decision_needed:** What you need the TL/human to decide',
+            '',
+            '**Alignment target:**',
+            '- Escalate to **TL** for: team-internal scope, engineering decisions, worker reassignment, moderate risk',
+            '- Escalate to **Human** for: product direction, business priority, cross-team resources, external commitments, high-risk production actions, legal/security/brand decisions',
+            '',
+            '### Task Acceptance Protocol',
+            'When you receive a task with a Task Contract from your TL, confirm acceptance with:',
+            '- **understood_goal:** What you believe the goal is',
+            '- **planned_approach:** How you intend to accomplish it',
+            '- **out_of_scope:** What you will NOT do',
+            '- **identified_risks:** Risks or blockers you foresee',
+            '',
+            'Only begin work after the TL confirms your understanding is correct.',
+            'If the task has `pre_classified: direct_execution`, you may skip the classification gate and proceed.',
+            '',
+            '### Try-Before-Refuse Protocol (ENFORCED)',
+            'Before refusing or reporting blocked on any task:',
+            '1. Re-read requirements — did you misunderstand?',
+            '2. Check available tools, skills, and project files via recall',
+            '3. Attempt a reasonable approach (partial solution counts)',
+            '4. After 3 failed attempts on the same obstacle, escalate with STRUCTURED report',
+            '',
+            '### Structured Block Report (REQUIRED for blocked/failed)',
+            'When reporting blocked or failed, you MUST include:',
+            '- **what_tried:** what approaches you attempted',
+            '- **what_failed:** specific errors or obstacles encountered',
+            '- **what_needed:** what would unblock you',
+            '- **partial_result:** any partial solution that exists',
+            '',
+            'A blocked report without attempt records is invalid and will be rejected.',
+            '',
+            '### Execution Rules',
+            '- **Scope Control:** Only touch files/systems specified in task. Report adjacent work separately',
+            '- **Definition of Done:** Build passes + tests pass + ready for TL verification. You do NOT self-verify as complete',
+            '',
+            this.buildGuidancePriorityChain(),
+            '',
+            this.buildCoreExecutionPrinciples(),
+        ].join('\n');
+    }
+}
+//# sourceMappingURL=role-boundary.module.js.map

package/dist/cli/backend/src/services/ai/prompt-modules/role-boundary.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-boundary.module.js","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/role-boundary.module.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/ai/prompt-modules/skills-reference.module.d.ts

@@ -0,0 +1,62 @@
+import { PromptModule, ModuleConfig } from './prompt-module.interface.js';
+/**
+ * Skills reference module — tells the agent how to discover and use skills.
+ *
+ * Consolidates skill references, role-based capability descriptions,
+ * and catalog location into a single module. Capabilities are scoped
+ * per-role to avoid blanket authorization (#225).
+ *
+ * Sources: Path A Step 1+6, Path B Section 8, Path C skill instructions.
+ */
+export declare class SkillsReferenceModule implements PromptModule {
+    name: string;
+    priority: number;
+    maxTokens: number;
+    compactable: boolean;
+    /**
+     * Always included — agents need to know how to use skills.
+     */
+    shouldInclude(_config: ModuleConfig): boolean;
+    /**
+     * Build the skills reference section with catalog location,
+     * role-scoped capabilities, and memory tool instructions.
+     *
+     * @param config - Module configuration with skill paths and role
+     * @returns Formatted markdown skills reference section
+     */
+    build(config: ModuleConfig): Promise<string>;
+    /**
+     * Build the core skills list — available to all roles.
+     */
+    private buildCoreSkills;
+    /**
+     * Build role-scoped capabilities section (#225).
+     * Workers get narrow read+execute scope; orchestrators get broader coordination scope.
+     */
+    private buildCapabilities;
+    /**
+     * Build safe skill calling guide for runtimes with shell escaping issues.
+     *
+     * Gemini CLI's run_shell_command mangles JSON arguments containing quotes,
+     * backticks, and parentheses, causing "unexpected EOF" shell errors.
+     * This guide instructs the agent to write JSON to a temp file using heredoc
+     * with a single-quoted delimiter, then pass --file <path>.
+     *
+     * Uses `<< 'CREWLY_EOF'` instead of `printf '%s' '...'` because:
+     * - Single-quoted heredoc delimiter prevents ALL shell interpretation
+     * - Single quotes, double quotes, backticks, $, () all pass through literally
+     * - The previous printf approach broke when JSON contained single quotes
+     *   (e.g., "it's working" or "don't forget")
+     *
+     * Only included for gemini-cli runtime type.
+     *
+     * @param config - Module configuration with runtime type
+     * @returns Safe calling guide markdown, or null if not needed
+     */
+    private buildSafeCallGuide;
+    /**
+     * Build communication and memory tool instructions.
+     */
+    private buildCommunication;
+}
+//# sourceMappingURL=skills-reference.module.d.ts.map

package/dist/cli/backend/src/services/ai/prompt-modules/skills-reference.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-reference.module.d.ts","sourceRoot":"","sources":["../../../../../../../backend/src/services/ai/prompt-modules/skills-reference.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,YAAY;IACzD,IAAI,SAAuB;IAC3B,QAAQ,SAAK;IACb,SAAS,SAAO;IAChB,WAAW,UAAS;IAEpB;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO;IAI7C;;;;;;OAMG;IACG,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAalD;;OAEG;IACH,OAAO,CAAC,eAAe;IAqEvB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA0DzB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,kBAAkB;IAyD1B;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAkB1B"}