peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/artifacts/artifact-templates.js

@@ -0,0 +1,302 @@
+/**
+ * Handoff path helpers.
+ *
+ * Slice 2026-06-29-change-id-root-removal: all handoff paths now key
+ * on the session-id axis (`.peaks/_runtime/<sessionId>/<role>/...`)
+ * instead of the deleted change-id axis
+ * (`.peaks/_runtime/change/<sessionId>/<role>/...`). The session
+ * dir is gitignored; the hard ban on `.peaks/_runtime/<id>/`
+ * siblings remains in force.
+ *
+ * The render functions below emit markdown bodies that quote these
+ * paths verbatim as write instructions — if the body contains a
+ * banned top-level path, the sub-agent prompt will recreate the
+ * forbidden dir on its next write.
+ */
+/** Canonical handoff path for a downstream role's request artifact. */
+export function formatHandoffPath(sessionId, role, requestId) {
+    return `.peaks/_runtime/${sessionId}/${role}/requests/${requestId}.md`;
+}
+/** Canonical path for the SC commit-boundary handoff artifact. */
+export function formatCommitBoundaryPath(sessionId, requestId) {
+    return `.peaks/_runtime/${sessionId}/sc/commit-boundaries/${requestId}.md`;
+}
+/** Canonical path for the txt skill-usage lessons log under a session scope. */
+export function formatSkillUsageLessonsPath(sessionId) {
+    return `.peaks/_runtime/${sessionId}/txt/skill-usage-lessons.md`;
+}
+function renderPrdTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
+    return `# PRD Request ${requestId}
+
+- session: ${sessionId}
+- type: ${requestType}
+- source: <ticket, message URL, or "verbal" with a short sanitized quote>
+- raw input (sanitized): <one-paragraph restatement of what the user actually asked for>
+
+## Goals
+
+- ...
+
+## Non-goals
+
+- ...
+
+## Preserved behavior
+
+- ...
+
+## Acceptance criteria
+
+- ... (browser-verifiable when frontend is in scope)
+
+## Frontend delta (only when target is frontend)
+
+- pages / routes / components / states / permissions / data deps / edge cases
+- 待联调态: ...
+- API contracts pending: ...
+
+## Risks and open questions
+
+- ...
+
+## Handoff
+
+- to peaks-rd: ${formatHandoffPath(sessionId, 'rd', requestId)}
+- to peaks-qa: ${formatHandoffPath(sessionId, 'qa', requestId)}
+- to peaks-ui: ${formatHandoffPath(sessionId, 'ui', requestId)}  (when UI involved)
+
+## Status
+
+- created: ${timestamp}
+- last update: ${timestamp}
+- state: draft
+`;
+}
+function renderUiTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
+    return `# UI Request ${requestId}
+
+- session: ${sessionId}
+- linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
+- type: ${requestType}
+- scope: full new surface | iteration on existing surface | regression fix | visual refresh
+- design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
+
+## Affected surfaces
+
+- pages / routes / components / modals / states (loading, empty, error, hover, focus, active, responsive)
+- explicit out-of-scope surfaces (do not modify)
+
+## UX flow and page states
+
+- entry points, primary flow, secondary flows, exit points
+- state machine per surface when state transitions matter
+
+## Visual constraints
+
+- typography pair: ...
+- palette: ...
+- density and motion intensity dials: ...
+- rejected generic patterns
+
+## Interaction constraints
+
+- keyboard, focus order, ARIA roles, gesture support, accessibility minima
+
+## UI regression seeds
+
+- list of visible regressions QA must check against the prior state
+
+## Browser evidence
+
+- sanitized observations only — no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs with PII / SSO / MFA material
+
+## Handoff
+
+- to peaks-rd: ${formatHandoffPath(sessionId, 'rd', requestId)}
+- to peaks-qa: ${formatHandoffPath(sessionId, 'qa', requestId)}
+
+## Status
+
+- created: ${timestamp}
+- last update: ${timestamp}
+- state: draft
+`;
+}
+function renderRdTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
+    return `# RD Request ${requestId}
+
+- session: ${sessionId}
+- linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
+- linked-ui:  ${formatHandoffPath(sessionId, 'ui', requestId)}  (when UI involved)
+- type: ${requestType}
+
+## Red-line scope
+
+- in-scope files / routes / API paths / data models
+- explicit out-of-scope surfaces (do not modify, mock, delete, or replace)
+
+## Standards preflight
+
+- peaks standards init/update --project <path> --dry-run output paths and status
+- planned application: apply | review-only | blocked
+
+## OpenSpec linkage (when openspec/ exists)
+
+- change-id: <openspec change id>
+- entry validate: peaks openspec validate <change-id> data.valid status
+- to-rd projection: peaks openspec to-rd <change-id> artifact path
+- exit validate (after implementation): status
+
+## Coverage status
+
+- current total UT coverage: <percent>
+- new/changed code coverage: <percent>
+- gate verdict: pass | legacy-accepted | blocked
+
+## Slice contract
+
+- slice id, functional boundary, pre-refactor behavior, target structure, unit-test requirements, acceptance checks, rollback plan, commit boundary
+
+## Implementation evidence
+
+- diff paths, test commands + outputs, code review findings + fixes, security review findings + fixes, dry-run output
+
+## MCP usage (when external docs lookup was used)
+
+- capabilityId / tool / sanitized args
+- artifact path of stored result
+- no secrets, no full network bodies
+
+## Handoff
+
+- to peaks-qa: ${formatHandoffPath(sessionId, 'qa', requestId)}
+- to peaks-sc: ${formatCommitBoundaryPath(sessionId, requestId)}
+
+## Status
+
+- created: ${timestamp}
+- last update: ${timestamp}
+- state: draft
+`;
+}
+function renderQaTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
+    return `# QA Request ${requestId}
+
+- session: ${sessionId}
+- linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
+- linked-rd:  ${formatHandoffPath(sessionId, 'rd', requestId)}
+- linked-ui:  ${formatHandoffPath(sessionId, 'ui', requestId)}  (when UI involved)
+- type: ${requestType}
+
+## Red-line boundary check
+
+- in-scope changes seen in the diff (match PRD + RD scope)
+- out-of-scope changes flagged (any extra file, route, mock, fixture, behavior)
+- verdict: clean | boundary-violation
+
+## OpenSpec exit gate (when openspec/ exists)
+
+- change-id: <id>
+- peaks openspec validate <id> data.valid: true | false
+- issues: ...
+
+## Acceptance checks
+
+- per-criterion: check method, result (pass | fail | blocked), evidence path
+
+## Mandatory validation gates
+
+- unit tests: command + pass/fail + coverage delta
+- API validation (when applicable): request paths exercised, evidence
+- browser E2E (when frontend): headed gstack/browse/dist/browse visible-browser confirmation, sanitized route/actions, console/network observations
+- browser-error feedback loop: page errors, console exceptions, broken network, hydration failures → return-to-RD evidence
+- security check: tool used, findings, fixes, unresolved risks
+- performance check: tool used, baseline vs after numbers when available
+- validation report path
+
+## Regression matrix
+
+- list of surfaces / API paths / browser flows checked
+- pass/fail per row
+
+## Browser evidence
+
+- sanitized observations only — no login URLs, cookies, headers, tokens, storage state, browser traces, or screenshots/logs with PII / SSO / MFA material
+
+## Verdict
+
+- overall: pass | return-to-rd | blocked
+
+## Status
+
+- created: ${timestamp}
+- last update: ${timestamp}
+- state: draft
+`;
+}
+function renderScTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
+    return `# SC Request ${requestId}
+
+- session: ${sessionId}
+- linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
+- linked-rd:  ${formatHandoffPath(sessionId, 'rd', requestId)}
+- linked-qa:  ${formatHandoffPath(sessionId, 'qa', requestId)}
+- linked-ui:  ${formatHandoffPath(sessionId, 'ui', requestId)}  (when UI involved)
+- type: ${requestType}
+
+## Change impact
+
+- modules / files / routes / data models touched
+- blast radius: local | cross-cutting | release-critical
+- rollback strategy
+
+## Commit boundaries
+
+- one commit per OpenSpec heading (when openspec/ exists)
+- otherwise: list of slice ids → commit message + scope
+
+## Artifact retention
+
+- prd artifact: ...
+- rd artifact: ...
+- qa artifact: ...
+- ui artifact: ... (when UI involved)
+- coverage evidence: ...
+- code review evidence: ...
+
+## Sync / authorization
+
+- artifact workspace path: .peaks/_runtime/${sessionId}/
+- memory sync authorized: yes | no
+- artifact sync authorized: yes | no
+- rationale if not authorized: keep local
+
+## Rollback points
+
+- commits / tags / branches that can revert each boundary
+
+## Handoff
+
+- to peaks-txt: ${formatSkillUsageLessonsPath(sessionId)} (when reusable lesson exists)
+
+## Status
+
+- created: ${timestamp}
+- last update: ${timestamp}
+- state: draft
+`;
+}
+export function renderTemplate(role, requestId, sessionId, changeSlug, timestamp, requestType) {
+    switch (role) {
+        case 'prd':
+            return renderPrdTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
+        case 'ui':
+            return renderUiTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
+        case 'rd':
+            return renderRdTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
+        case 'qa':
+            return renderQaTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
+        case 'sc':
+            return renderScTemplate(requestId, sessionId, changeSlug, timestamp, requestType);
+    }
+}

package/dist/services/artifacts/repair-cycle-service.d.ts

@@ -0,0 +1,23 @@
+export type RepairCycleEntry = {
+    cycle: number;
+    timestamp: string;
+    reason: string;
+};
+export type RepairCycleReport = {
+    requestId: string;
+    sessionId: string;
+    path: string;
+    cycleCount: number;
+    maxCycles: number;
+    remaining: number;
+    atCap: boolean;
+    blocked: boolean;
+    entries: RepairCycleEntry[];
+};
+export type RepairCycleStatusOptions = {
+    projectRoot: string;
+    requestId: string;
+    sessionId?: string;
+    maxCycles?: number;
+};
+export declare function getRepairCycleStatus(options: RepairCycleStatusOptions): Promise<RepairCycleReport | null>;

package/dist/services/artifacts/repair-cycle-service.js

@@ -0,0 +1,52 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const DEFAULT_MAX_CYCLES = 3;
+// Matches transition notes Code writes during repair routing.
+// Format example:
+//   - transition note (2026-05-25T08:00:00.000Z): QA return-to-rd cycle 1: failing acceptance items A, B
+//   - transition note (2026-05-25T09:00:00.000Z): QA cycle 2: regression in module X
+const REPAIR_NOTE_PATTERN = /-\s*transition note\s*\(([^)]+)\)\s*:\s*(?:QA(?:\s+return-to-rd)?\s+cycle\s+(\d+))\s*:?\s*(.*?)$/i;
+export async function getRepairCycleStatus(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'rd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const maxCycles = options.maxCycles ?? DEFAULT_MAX_CYCLES;
+    const lines = artifact.content.split(/\r?\n/);
+    const entries = [];
+    for (const rawLine of lines) {
+        const match = REPAIR_NOTE_PATTERN.exec(rawLine);
+        if (match === null)
+            continue;
+        const [, timestamp, cycleStr, reason] = match;
+        if (timestamp === undefined || cycleStr === undefined)
+            continue;
+        const cycle = Number(cycleStr);
+        if (!Number.isFinite(cycle) || cycle < 1)
+            continue;
+        entries.push({ cycle, timestamp, reason: (reason ?? '').trim() });
+    }
+    // Distinct cycle numbers — repair loop may write the same cycle note multiple times.
+    const distinct = new Set(entries.map((entry) => entry.cycle));
+    const cycleCount = distinct.size;
+    const remaining = Math.max(0, maxCycles - cycleCount);
+    const atCap = cycleCount >= maxCycles;
+    return {
+        requestId: options.requestId,
+        sessionId: artifact.sessionId,
+        path: artifact.path,
+        cycleCount,
+        maxCycles,
+        remaining,
+        atCap,
+        blocked: atCap,
+        entries
+    };
+}

package/dist/services/artifacts/request-artifact-service.d.ts

@@ -0,0 +1,116 @@
+import { DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES, type PrerequisiteCheckResult, type RequestType } from './artifact-prerequisites.js';
+export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType, type RequestType };
+import type { RequestArtifactRole } from './artifact-templates.js';
+export type { RequestArtifactRole } from './artifact-templates.js';
+export { formatHandoffPath, formatCommitBoundaryPath, formatSkillUsageLessonsPath } from './artifact-templates.js';
+export type CreateRequestArtifactOptions = {
+    role: RequestArtifactRole;
+    requestId: string;
+    projectRoot: string;
+    sessionId?: string;
+    /**
+     * Optional explicit session-id scope. When set, the artifact file lands at
+     * `.peaks/_runtime/<sessionId>/<role>/requests/...`. When unset, falls back
+     * to the binding, then to the requestId. The CLI's `--session-id <scope>`
+     * flag uses this to preserve the legacy "session-id as scope dir name"
+     * behavior.
+     */
+    apply?: boolean;
+    requestType?: RequestType;
+    clock?: () => string;
+    /**
+     * Slice 020 — caller-keyed session binding. The callerId that initiated
+     * this artifact creation (resolved via `resolveCallerId` by the CLI).
+     * Recorded in the JSON envelope and on the artifact body's frontmatter
+     * so a future reader knows which caller produced it. The caller-keyed
+     * binding file itself is at `.peaks/_runtime/callers/<callerId>.json`;
+     * the per-caller active-skill marker is at
+     * `.peaks/_runtime/<peakSid>/active-skill-<callerId>.json` (D6).
+     */
+    callerId?: string;
+};
+export type CreateRequestArtifactResult = {
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId: string;
+    path: string;
+    content: string;
+    applied: boolean;
+    /**
+     * Slice 020 — caller-keyed session binding. The resolved callerId
+     * (D4 priority: flag > env > platform fallback) when --caller-id
+     * was passed. Omitted from the result when no callerId was set.
+     */
+    callerId?: string;
+    /**
+     * Slice 2026-06-23-request-init-change-scope-leak. The session-axis
+     * dir resolved under `.peaks/_runtime/<sid>/`. Always populated so
+     * the sub-agent prompt can report a stable, canonical scope
+     * location to the writer.
+     */
+    scopeDir: string;
+};
+export declare function createRequestArtifact(options: CreateRequestArtifactOptions): Promise<CreateRequestArtifactResult>;
+export type RequestArtifactSummary = {
+    role: RequestArtifactRole;
+    /**
+     * Durable scope of the artifact: the top-level `.peaks/_runtime/<sessionId>/`
+     * directory the file lives in. As of slice 2026-06-05-change-id-as-unit-of-work,
+     * the prerequisite gate resolves paths under this dir (not the body
+     * `- session:` line), so the file body and the on-disk path agree.
+     */
+    sessionId: string;
+    /**
+     * Session binding (which developer's local session wrote the file).
+     * Read from the file body's `- session:` line. Falls back to `sessionId`
+     * when the body is missing the line. For back-compat with legacy
+     * session-id dirs, this may equal the dir name.
+     */
+    writerSessionId?: string;
+    requestId: string;
+    path: string;
+    state: string;
+    requestType: RequestType;
+    createdAt?: string;
+};
+export type ListRequestArtifactsOptions = {
+    projectRoot: string;
+    sessionId?: string;
+    role?: RequestArtifactRole;
+};
+export type ShowRequestArtifactOptions = {
+    projectRoot: string;
+    role: RequestArtifactRole;
+    requestId: string;
+    sessionId?: string;
+};
+export type ShowRequestArtifactResult = RequestArtifactSummary & {
+    content: string;
+};
+export declare function listRequestArtifacts(options: ListRequestArtifactsOptions): Promise<RequestArtifactSummary[]>;
+export declare function showRequestArtifact(options: ShowRequestArtifactOptions): Promise<ShowRequestArtifactResult | null>;
+export type TransitionRequestArtifactOptions = {
+    role: RequestArtifactRole;
+    requestId: string;
+    projectRoot: string;
+    newState: RequestArtifactState;
+    sessionId?: string;
+    reason?: string;
+    allowIncomplete?: boolean;
+    confirmed?: boolean;
+    forceConfirm?: boolean;
+    typeSanityCheck?: {
+        projectRoot: string;
+        declaredType: RequestType;
+    };
+    clock?: () => string;
+};
+export type TransitionRequestArtifactResult = RequestArtifactSummary & {
+    previousState: string;
+    content: string;
+    bypassedPrerequisites?: PrerequisiteCheckResult;
+};
+import type { RequestArtifactState } from './request-artifact-state-helpers.js';
+export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
+export type { RequestArtifactState } from './request-artifact-state-helpers.js';
+export declare function transitionRequestArtifact(options: TransitionRequestArtifactOptions): Promise<TransitionRequestArtifactResult | null>;