karajan-code 2.5.0 → 2.6.1

package/src/types/config.js

@@ -0,0 +1,114 @@
+/**
+ * Karajan configuration typedefs. Mirrors the shape produced by loadConfig()
+ * and consumed throughout the orchestrator. Optional fields are intentional
+ * — users may set them in kj.config.yml without every field being required.
+ */
+
+/**
+ * @typedef {Object} RoleConfig
+ * @property {string} [provider]    - claude | codex | gemini | opencode | aider | anthropic | openai | google
+ * @property {string} [model]       - provider-specific model identifier
+ */
+
+/**
+ * @typedef {Object} PipelineToggle
+ * @property {boolean} [enabled]
+ */
+
+/**
+ * @typedef {Object} PipelineFlags
+ * @property {boolean} [coderEnabled]
+ * @property {boolean} [reviewerEnabled]
+ * @property {boolean} [plannerEnabled]
+ * @property {boolean} [researcherEnabled]
+ * @property {boolean} [architectEnabled]
+ * @property {boolean} [refactorerEnabled]
+ * @property {boolean} [testerEnabled]
+ * @property {boolean} [securityEnabled]
+ * @property {boolean} [impeccableEnabled]
+ * @property {boolean} [triageEnabled]
+ * @property {boolean} [discoverEnabled]
+ * @property {boolean} [huReviewerEnabled]
+ * @property {boolean} [coderRequired]
+ */
+
+/**
+ * @typedef {Object} GitConfig
+ * @property {boolean} [auto_commit]
+ * @property {boolean} [auto_push]
+ * @property {boolean} [auto_pr]
+ * @property {boolean} [auto_rebase]
+ * @property {string} [branch_prefix]
+ */
+
+/**
+ * @typedef {Object} SonarConfig
+ * @property {boolean} [enabled]
+ * @property {string} [host]
+ * @property {string} [token]
+ * @property {boolean} [external]
+ * @property {string} [enforcement_profile]
+ */
+
+/**
+ * @typedef {Object} BudgetConfig
+ * @property {Object} [pricing]
+ * @property {number} [warn_threshold_pct]
+ */
+
+/**
+ * @typedef {Object} BrainDecisorConfig
+ * @property {boolean} [enabled]
+ * @property {number} [maxDecisions]
+ */
+
+/**
+ * @typedef {Object} BrainConfig
+ * @property {boolean} [enabled]
+ * @property {string} [provider]
+ * @property {boolean} [bypass_solomon_on_correctness]
+ * @property {number} [max_consecutive_verification_failures]
+ * @property {BrainDecisorConfig} [decisor]
+ */
+
+/**
+ * @typedef {Object} SkillsConfig
+ * @property {boolean} [enabled]
+ * @property {"auto"|"regex"|"semantic"|"none"} [mode]
+ */
+
+/**
+ * @typedef {Object} PreflightConfig
+ * @property {boolean} [extended]
+ */
+
+/**
+ * Full Karajan configuration shape as resolved by loadConfig() +
+ * applyRunOverrides(). Not every field is always present; consumers should
+ * defensively read via `config.x?.y`.
+ *
+ * @typedef {Object} KarajanConfig
+ * @property {string} [coder]                   - legacy agent name (claude, codex, ...)
+ * @property {string} [reviewer]                - legacy agent name
+ * @property {Object.<string, RoleConfig>} [roles]
+ * @property {Object.<string, PipelineToggle>} [pipeline]
+ * @property {string} [review_mode]             - standard | strict | paranoid | relaxed
+ * @property {string} [review_rules]            - path to review rules .md
+ * @property {number} [max_iterations]
+ * @property {number} [max_budget_usd]
+ * @property {BudgetConfig} [budget]
+ * @property {SonarConfig} [sonarqube]
+ * @property {GitConfig} [git]
+ * @property {string} [base_branch]
+ * @property {Object} [session]                 - timeouts etc
+ * @property {Object} [output]                  - log level, report dir
+ * @property {Object} [development]             - methodology, require_test_changes
+ * @property {BrainConfig} [brain]
+ * @property {SkillsConfig} [skills]
+ * @property {PreflightConfig} [preflight]
+ * @property {string} [projectDir]              - absolute path, set at runtime
+ * @property {string} [productContext]          - runtime-loaded
+ * @property {string} [domainContext]           - runtime-loaded
+ */
+
+export {};

package/src/types/hu.js

@@ -0,0 +1,47 @@
+/**
+ * HU (Historia de Usuario) typedefs. An HU is a user story that the
+ * pipeline can decompose into, certify via hu-reviewer, then run as a
+ * sub-pipeline.
+ */
+
+/**
+ * @typedef {"pending"|"planned"|"in_progress"|"done"|"rejected"|"blocked"|"failed"} HUStatus
+ */
+
+/**
+ * @typedef {Object} HUAcceptanceCriterion
+ * @property {string} [given]
+ * @property {string} [when]
+ * @property {string} [then]
+ * @property {string} [raw]                     - plain-text AC if not Gherkin
+ */
+
+/**
+ * @typedef {Object} HUStory
+ * @property {string} id                        - stable slug per batch
+ * @property {string} title
+ * @property {string} [role]                    - "Como ..."
+ * @property {string} [goal]                    - "Quiero ..."
+ * @property {string} [benefit]                 - "Para ..."
+ * @property {HUAcceptanceCriterion[]} [acceptanceCriteria]
+ * @property {HUStatus} [status]
+ * @property {string} [assignee]
+ * @property {string[]} [dependencies]          - ids of HUs that must be done first
+ * @property {Object} [certification]           - hu-reviewer verdict
+ * @property {Object} [session]                 - sub-pipeline session metadata when it runs
+ */
+
+/**
+ * A batch is the ordered collection of HUs produced by the auto-generator
+ * or loaded from a YAML file.
+ *
+ * @typedef {Object} HUBatch
+ * @property {string} id                        - typically the parent sessionId
+ * @property {string} [task]                    - original task text
+ * @property {HUStory[]} stories
+ * @property {string} [created_at]
+ * @property {string} [updated_at]
+ * @property {Object} [board]                   - HU Board metadata (port, URL)
+ */
+
+export {};

package/src/types/index.js

@@ -0,0 +1,38 @@
+/**
+ * Central JSDoc typedef registry. Import typedefs via:
+ *
+ *   /** @typedef {import("../types/index.js").KarajanConfig} KarajanConfig *\/
+ *
+ * This module re-exports every type so consumers have a single import path.
+ * The actual typedef bodies live in the focused files under src/types/.
+ *
+ * Intentionally a runtime-empty module: it only carries JSDoc annotations,
+ * nothing to execute.
+ */
+
+/**
+ * @typedef {import("./config.js").KarajanConfig} KarajanConfig
+ * @typedef {import("./config.js").RoleConfig} RoleConfig
+ * @typedef {import("./config.js").PipelineFlags} PipelineFlags
+ *
+ * @typedef {import("./session.js").Session} Session
+ * @typedef {import("./session.js").Checkpoint} Checkpoint
+ *
+ * @typedef {import("./stage.js").StageContext} StageContext
+ * @typedef {import("./stage.js").StageResult} StageResult
+ *
+ * @typedef {import("./agent.js").AgentResult} AgentResult
+ * @typedef {import("./agent.js").AgentResponse} AgentResponse
+ *
+ * @typedef {import("./hu.js").HUStory} HUStory
+ * @typedef {import("./hu.js").HUBatch} HUBatch
+ *
+ * @typedef {import("./policy.js").ResolvedPolicies} ResolvedPolicies
+ * @typedef {import("./policy.js").QualityGateResult} QualityGateResult
+ *
+ * @typedef {import("./solomon.js").Conflict} SolomonConflict
+ * @typedef {import("./solomon.js").ConflictHistoryEntry} SolomonConflictHistoryEntry
+ * @typedef {import("./solomon.js").SolomonResult} SolomonResult
+ */
+
+export {};

package/src/types/policy.js

@@ -0,0 +1,43 @@
+/**
+ * Policy + quality-gate typedefs. Policies are resolved once per session
+ * from config + task type; quality gates are the outputs of each gate
+ * (sonar, perf, tests, review).
+ */
+
+/**
+ * @typedef {Object} ResolvedPolicies
+ * @property {boolean} [tdd]                    - whether TDD is enforced
+ * @property {boolean} [sonar]                  - Sonar gate enabled
+ * @property {boolean} [tests]                  - tester gate enabled
+ * @property {boolean} [security]               - security audit enabled
+ * @property {boolean} [reviewer]               - reviewer gate enabled
+ * @property {boolean} [planner]                - planner enabled
+ * @property {boolean} [researcher]             - researcher enabled
+ * @property {boolean} [architect]              - architect enabled
+ * @property {boolean} [refactorer]             - refactorer enabled
+ * @property {boolean} [impeccable]             - impeccable audit enabled
+ * @property {boolean} [triage]                 - triage enabled
+ * @property {boolean} [discover]               - discover phase enabled
+ * @property {boolean} [hu_reviewer]            - HU certification enabled
+ * @property {number} [reviewer_retries]
+ * @property {number} [tester_retries]
+ * @property {string} [reason]                  - why these policies (task type + config chain)
+ */
+
+/**
+ * Result of a quality gate evaluation — Sonar, perf, tester, reviewer, etc.
+ *
+ * @typedef {Object} QualityGateResult
+ * @property {boolean} ok                       - did the gate pass
+ * @property {"OK"|"FAIL"|"WARN"|"ERROR"} gateStatus
+ * @property {string} [summary]
+ * @property {Object[]} [blocking_issues]       - for reviewer/security gates
+ * @property {number} [openIssues]              - sonar
+ * @property {number} [issuesInitial]
+ * @property {number} [issuesFinal]
+ * @property {number} [issuesResolved]
+ * @property {string} [provider]                - which agent produced the verdict (when relevant)
+ * @property {Object} [details]                 - gate-specific payload
+ */
+
+export {};

package/src/types/session.js

@@ -0,0 +1,74 @@
+/**
+ * Session state typedefs. The session is a mutable object that accumulates
+ * state throughout a kj run and is persisted to ~/.karajan/sessions/<id>/.
+ */
+
+/**
+ * @typedef {Object} Checkpoint
+ * @property {string} [at]                   - ISO timestamp
+ * @property {string} [stage]
+ * @property {number} [iteration]
+ * @property {string} [conflictStage]
+ * @property {string} [ruling]
+ * @property {string} [alternativeAgent]
+ * @property {string} [waitUntil]
+ * @property {string[]} [conditions]
+ * @property {boolean} [escalate]
+ * @property {string} [error]
+ * @property {string|null} [subtask]
+ */
+
+/**
+ * @typedef {Object} SolomonRulingRecord
+ * @property {string} at                     - ISO timestamp
+ * @property {string} stage
+ * @property {string} trigger
+ * @property {Object} conflict
+ * @property {string} ruling                 - approve | approve_with_conditions | escalate_human | create_subtask | ...
+ * @property {string} [reasoning]
+ * @property {string[]} [conditions]
+ * @property {string|null} [alternativeAgent]
+ * @property {string} [result]
+ */
+
+/**
+ * @typedef {Object} BrainDecisionRecord
+ * @property {number} seq
+ * @property {string} at
+ * @property {string} intent                 - "<taskType>:<level>"
+ * @property {string[]} rolesOn
+ * @property {string} confidence             - low | medium | high
+ * @property {string} rationale
+ * @property {string[]} appliedOverrides
+ */
+
+/**
+ * @typedef {Object} RtkSavings
+ * @property {number} [callCount]
+ * @property {number} [estimatedTokensSaved]
+ * @property {number} [savedPct]
+ * @property {number} [originalBytes]
+ * @property {number} [rtkBytes]
+ */
+
+/**
+ * @typedef {Object} Session
+ * @property {string} id                     - session id
+ * @property {string} task                   - user's task text
+ * @property {"running"|"paused"|"approved"|"rejected"|"failed"} status
+ * @property {string} created_at             - ISO timestamp
+ * @property {string} updated_at
+ * @property {Checkpoint[]} [checkpoints]
+ * @property {SolomonRulingRecord[]} [solomonRulings]     - KJC-TSK-0287
+ * @property {BrainDecisionRecord[]} [brainDecisions]     - KJC-TSK-0322
+ * @property {string[]} [skillsRecommended]               - wouldHaveUsed when openskills missing
+ * @property {string[]} [autoInstalledSkills]
+ * @property {RtkSavings} [rtk_savings]
+ * @property {string} [session_start_sha]
+ * @property {string} [_journalDir]                       - runtime journal path
+ * @property {string[]} [_journalIterations]              - rendered iteration markdown
+ * @property {string[]} [_journalFiles]
+ * @property {Object} [budget]                            - final budget summary snapshot
+ */
+
+export {};

package/src/types/solomon.js

@@ -0,0 +1,87 @@
+/**
+ * Typedefs for Solomon — the AI judge consulted by Brain on genuine dilemmas.
+ *
+ * Architectural invariant (enforced by convention, see docs/ARCHITECTURE.md):
+ *   Solomon is **NEVER** invoked directly from stages, rules or roles.
+ *   The only legitimate entry points are:
+ *     - `src/brain/solomon-consult.js#consultSolomonForRouting`
+ *     - `src/orchestrator/solomon-escalation.js#invokeSolomon`
+ *   Both are called by Brain (or by the orchestrator on Brain's behalf).
+ *   The v2.3.0 audit fixed 21 violations where stages bypassed Brain and
+ *   called Solomon directly. Don't reintroduce that pattern.
+ *
+ * This module is runtime-empty — it only carries JSDoc annotations.
+ *
+ * @module types/solomon
+ */
+
+/**
+ * A single turn of feedback attributed to a pipeline agent. Used to build
+ * `Conflict.history` when Brain escalates a decision to Solomon.
+ *
+ * @typedef {Object} ConflictHistoryEntry
+ * @property {string} agent     - slug of the agent that produced the feedback
+ *                                (e.g. "reviewer", "sonar", "tester",
+ *                                "coder_rate_limit").
+ * @property {string} feedback  - raw textual feedback to be weighted by Solomon.
+ */
+
+/**
+ * The bundle of context Brain hands to Solomon when it cannot decide on its
+ * own. Solomon reads only this object + the stage + task; it never sees
+ * session internals beyond what is packed here.
+ *
+ * Historical shape: this matches the argument already used by
+ * `invokeSolomon({ ..., conflict })` — the typedef formalizes the contract
+ * so future drift is caught by `npm run typecheck`.
+ *
+ * @typedef {Object} Conflict
+ * @property {string} stage
+ *           Pipeline stage that triggered escalation (e.g. "reviewer",
+ *           "sonar", "tester", "init_error", "coder_rate_limit").
+ * @property {string} task
+ *           Original user task (denormalized so Solomon sees what the user
+ *           actually asked for, not just the stage context).
+ * @property {number} iterationCount
+ *           Current iteration number inside the escalating sub-loop.
+ * @property {number} maxIterations
+ *           Configured cap for that sub-loop (reviewer retries, tester
+ *           retries, full pipeline iterations, etc.). Hitting this cap is
+ *           the canonical trigger for Solomon consultation.
+ * @property {string|null} [cooldownUntil]
+ *           ISO timestamp for rate-limit / standby escalations. Null when
+ *           the conflict is not a rate-limit.
+ * @property {number|null} [cooldownMs]
+ *           Remaining cooldown in milliseconds. Null outside rate-limit
+ *           escalations.
+ * @property {ConflictHistoryEntry[]} history
+ *           Ordered list of agent feedback Solomon should weigh. Most
+ *           recent last. Must be non-empty — Solomon should always see at
+ *           least one piece of evidence.
+ */
+
+/**
+ * Solomon's ruling on a `Conflict`. Returned by `invokeSolomon()` and
+ * consumed by the orchestrator to decide what happens next.
+ *
+ * @typedef {Object} SolomonResult
+ * @property {"continue"|"pause"|"subtask"} action
+ *           - `continue`: retry the sub-loop with optional `humanGuidance`
+ *             appended to the next feedback round.
+ *           - `pause`: stop the pipeline and surface a question to the
+ *             human operator (`SolomonResult.question`).
+ *           - `subtask`: bifurcate into a named sub-task defined in
+ *             `SolomonResult.subtask`.
+ * @property {string} [rationale]         - human-readable reasoning for the
+ *                                          chosen action. Logged to the
+ *                                          decisions journal.
+ * @property {string} [humanGuidance]     - text to merge into the next
+ *                                          coder/reviewer prompt when
+ *                                          action === "continue".
+ * @property {string} [question]          - prompt shown to the human when
+ *                                          action === "pause".
+ * @property {Object} [subtask]           - sub-task descriptor when
+ *                                          action === "subtask".
+ */
+
+export {};

package/src/types/stage.js

@@ -0,0 +1,68 @@
+/**
+ * Stage context + stage result typedefs. A StageContext is the bundle of
+ * orchestration state every stage function receives; a StageResult is what
+ * they return for downstream stages to consume.
+ */
+
+/**
+ * @typedef {Object} Logger
+ * @property {(msg: string, ...rest: any[]) => void} info
+ * @property {(msg: string, ...rest: any[]) => void} warn
+ * @property {(msg: string, ...rest: any[]) => void} error
+ * @property {(msg: string, ...rest: any[]) => void} [debug]
+ */
+
+/**
+ * @typedef {Object} Emitter
+ * @property {(event: string, data?: any) => void} emit
+ */
+
+/**
+ * Shape of `eventBase` propagated to every emitted event for correlation.
+ *
+ * @typedef {Object} EventBase
+ * @property {string} sessionId
+ * @property {number} iteration
+ * @property {string|null} stage
+ * @property {number} startedAt                  - epoch ms
+ */
+
+/**
+ * The context every pipeline stage consumes. Most stages pick a subset with
+ * destructuring. Listed here so consumers can import a single type instead
+ * of re-declaring ad-hoc objects.
+ *
+ * @typedef {Object} StageContext
+ * @property {import("./config.js").KarajanConfig} config
+ * @property {import("./session.js").Session} session
+ * @property {Logger} logger
+ * @property {Emitter|null} emitter
+ * @property {EventBase} eventBase
+ * @property {Function} [trackBudget]
+ * @property {Function} [budgetSummary]
+ * @property {import("./config.js").PipelineFlags} [pipelineFlags]
+ * @property {Object} [coderRole]                - CoderRole instance
+ * @property {Object} [reviewerRole]
+ * @property {Object} [brainCtx]
+ * @property {Function} [askQuestion]
+ * @property {Object} [stageResults]             - accumulated results from prior stages
+ * @property {string} [task]
+ * @property {string|null} [pgTaskId]
+ * @property {string|null} [pgProject]
+ * @property {Object} [flags]                    - CLI/call-time flags
+ */
+
+/**
+ * The structured return of most stage helpers. Stages are allowed to return
+ * shape-specific additions on top of these common fields.
+ *
+ * @typedef {Object} StageResult
+ * @property {boolean} ok
+ * @property {string} [summary]
+ * @property {Object} [result]                   - stage-specific payload
+ * @property {string} [action]                   - "return" | "retry" | "continue" | "skip" | ...
+ * @property {Object} [stageResult]              - alternate nested result shape used by some stages
+ * @property {string} [provider]
+ */
+
+export {};