peaks-cli 1.2.5 → 1.2.6

package/dist/src/cli/commands/workspace-commands.js

@@ -1,5 +1,6 @@
 import { initWorkspace, InvalidSessionIdError, ConflictingSessionError } from '../../services/workspace/workspace-service.js';
 import { ensureSession } from '../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerWorkspaceCommands(program, io) {
@@ -18,15 +19,26 @@ export function registerWorkspaceCommands(program, io) {
             //   - omitted: defer to ensureSession(), which reuses an existing
             //     binding or auto-generates a fresh one. The init then writes
             //     .session.json so the binding sticks.
+            //
+            // Before that: canonicalise the project root. If the user (or the
+            // LLM via "$(pwd)") passed a sub-directory of a real git repo
+            // (e.g. prompt-project/prompt-project/ inside the outer
+            // prompt-project/.git), promote the path to the git root. Without
+            // this, peaks would build a parallel .peaks/ tree under the
+            // nested sub-folder and silently break the project-binding model
+            // (the same regression that produced prompt-project/.peaks/ in
+            // the 5/27-5/29 sessions). When startPath is not inside any
+            // git repo, the helper falls through to the cwd verbatim.
+            const projectRoot = resolveCanonicalProjectRoot(options.project);
             let sessionId;
             if (options.sessionId !== undefined && options.sessionId.length > 0) {
                 sessionId = options.sessionId;
             }
             else {
-                sessionId = await ensureSession(options.project);
+                sessionId = await ensureSession(projectRoot);
             }
             const report = await initWorkspace({
-                projectRoot: options.project,
+                projectRoot,
                 sessionId,
                 allowSessionRebind: options.allowSessionRebind === true
             });

package/dist/src/services/config/config-safety.d.ts

@@ -2,6 +2,32 @@ export declare function getUserConfigPath(): string;
 export declare function isInsidePath(childPath: string, parentPath: string): boolean;
 export declare function findProjectRoot(startPath: string): string | null;
 export declare function resolveProjectRootForConfig(startPath: string): string;
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export declare function resolveCanonicalProjectRoot(startPath: string): string;
 export declare function getProjectConfigPath(projectRoot: string | null): string | null;
 export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
 export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;

package/dist/src/services/config/config-safety.js

@@ -1,4 +1,5 @@
 import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
@@ -89,6 +90,81 @@ export function resolveProjectRootForConfig(startPath) {
     }
     return pkgRoot ?? start;
 }
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export function resolveCanonicalProjectRoot(startPath) {
+    const start = resolve(startPath);
+    const gitRoot = resolveProjectRootFromGit(start);
+    if (gitRoot !== null) {
+        return gitRoot;
+    }
+    // Non-git fallback: walk the heuristic up to the home boundary.
+    // We do NOT call realpathSync on the heuristic result because the
+    // heuristic may legitimately return a path through a symlink that
+    // the caller passed in (no canonicalisation needed in that case).
+    const heuristicRoot = findProjectRoot(start);
+    if (heuristicRoot !== null) {
+        return heuristicRoot;
+    }
+    return start;
+}
+function resolveProjectRootFromGit(startPath) {
+    // execFileSync (not execSync) so a malicious `startPath` cannot
+    // inject argv into the spawned git invocation. The child only
+    // receives `startPath` as the cwd, never as a flag.
+    let rawRoot;
+    try {
+        const stdout = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: startPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null;
+        rawRoot = resolve(trimmed);
+    }
+    catch {
+        // git not on PATH, startPath is not in a repo, or some other
+        // benign failure — fall through to the heuristic.
+        return null;
+    }
+    // On macOS, /tmp is a symlink to /private/tmp; git returns the
+    // realpath. If the caller passed a path through the symlink, the
+    // two strings won't match byte-for-byte even though they refer
+    // to the same directory. realpathSync the git root and the
+    // startPath through the same lens so callers get a canonical
+    // answer that compares equal to the path they passed in.
+    try {
+        return realpathSync(rawRoot);
+    }
+    catch {
+        return rawRoot;
+    }
+}
 export function getProjectConfigPath(projectRoot) {
     if (!projectRoot)
         return null;

package/dist/src/services/config/config-service.d.ts

@@ -1,5 +1,5 @@
 import type { ConfigGetOptions, ConfigLayer, ConfigSetOptions, MiniMaxProviderConfig, PeaksConfig, TokenRef, WorkspaceConfig } from './config-types.js';
-export { resolveProjectRootForConfig } from './config-safety.js';
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 export declare function isConfigLayer(value: string): value is ConfigLayer;
 export declare function isSensitiveConfigPath(path: string): boolean;
 export declare function containsSensitiveConfigValue(value: unknown): boolean;

package/dist/src/services/config/config-service.js

@@ -3,8 +3,8 @@ import { dirname, isAbsolute, resolve } from 'node:path';
 import { DEFAULT_CONFIG } from './config-types.js';
 import { stablePath } from '../../shared/path-utils.js';
 import { findProjectRoot, getProjectBootstrapConfigPath, getProjectConfigPath, getUserConfigPath, isInsidePath, readConfigFileSafely, resolveProjectRootForConfig, validateArtifactWorkspaceMarkerPath, validateArtifactWorkspaceRoot, validateProjectBootstrapConfigPathForWrite, validateUserConfigPathForWrite, writeConfigFileSafely, writeProjectConfigFile, writeUserConfigFile } from './config-safety.js';
-// Re-export resolveProjectRootForConfig for external consumers
-export { resolveProjectRootForConfig } from './config-safety.js';
+// Re-export resolveProjectRootForConfig and resolveCanonicalProjectRoot for external consumers
+export { resolveProjectRootForConfig, resolveCanonicalProjectRoot } from './config-safety.js';
 function readJsonFile(path, validateBeforeRead, errorMessage = 'Config path must stay inside the config root') {
     if (!path || !existsSync(path))
         return null;

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.2.5";
+export declare const CLI_VERSION = "1.2.6";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.2.5";
+export const CLI_VERSION = "1.2.6";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/SKILL.md

@@ -1065,4 +1065,4 @@ Do not run upstream installer flows, mutate agent settings, or commit `.codegrap
 
 **MCP lifecycle**: `list → plan → apply --yes → call → rollback`. `apply` backs up settings and refuses non-peaks entries unless `--claim` is passed.
 
-Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`.
+Detailed rules: `references/external-skill-invocation.md`, `references/openspec-mcp-workflow.md`, `references/workflow.md`, `references/existing-system-extraction.md`. For an informational mapping of peaks artefact paths to the A2A (Agent2Agent) protocol's Task / Artifact / Part / Message / AgentCard vocabulary (no A2A implementation, just a shared naming layer), see `references/a2a-artifact-mapping.md`.

package/skills/peaks-solo/references/a2a-artifact-mapping.md

@@ -0,0 +1,115 @@
+# A2A artifact mapping (informational)
+
+> Reference for `peaks-solo` and any other peaks skill that produces durable artefacts in `.peaks/<session-id>/`. Maps peaks's on-disk artefact vocabulary onto the A2A (Agent2Agent) protocol's vocabulary so a future peaks consumer (e.g. an external LLM agent or a downstream peaks-cli extension) can read peaks output without having to learn a brand-new schema. This is a **documentation mapping**, not a protocol implementation: peaks-cli does not speak A2A over HTTP, does not host an AgentCard endpoint, and does not advertise its capabilities via A2A's discovery mechanism. It only uses A2A's *concepts* as a shared naming layer.
+
+## 1. Why this reference exists
+
+The A2A protocol (https://a2acn.com) defines five core concepts: **AgentCard**, **Task**, **Artifact**, **Message**, and **Part**. peaks-cli's session workspace is a parallel vocabulary that grew up independently: `prd/requests/<rid>.md`, `rd/tech-doc.md`, `qa/test-cases/<rid>.md`, etc. The two vocabularies are *not* identical (A2A is HTTP-shaped, peaks is filesystem-shaped), but the A2A concepts are close enough that aligning peaks artefact names with A2A terms in this reference:
+
+- gives an external consumer a single translation table instead of two schemas to learn,
+- lets a peaks operator talk about "the artifact" or "the task" in mixed conversations without losing precision,
+- documents what peaks output is **not** (no SSE streaming, no remote AgentCard), so the limits are explicit.
+
+This is the kind of borrowing that costs zero code and earns some interoperability. It is **not** an integration: peaks-cli does not implement A2A, does not run an A2A server, and does not depend on the a2a-protocol package. Adopting A2A concepts here is the same as adopting any other shared nomenclature (UML, OpenTelemetry, etc.): it improves the conversation, nothing more.
+
+## 2. Concept-to-path mapping
+
+The mapping below uses peaks's own paths verbatim. Each row also notes where peaks **diverges** from A2A, so a reader does not assume parity.
+
+| A2A concept | peaks artefact | Path (under `.peaks/<session-id>/`) | Notes |
+|---|---|---|---|
+| **AgentCard** (capability advertisement) | `peaks-skill-output-style` + `.peaks/.active-skill.json` | `.peaks/.active-skill.json`, `.peaks/.session.json` | peaks is a *local* tool, not a service. The "card" is the active-skill file plus a peek at `.peaks/PROJECT.md` for human-readable history. There is no `/.well-known/agent-card.json` endpoint. |
+| **Task** (stateful unit of work) | `peaks request` state machine for a single `<rid>` | `.peaks/<sid>/{prd,rd,qa,ui,sc}/requests/<rid>.md` (the request artefact); `.peaks/<sid>/<role>/session.json` (per-session metadata) | peaks's task lifecycle is `prd:confirmed-by-user → handed-off`, then per role `draft → spec-locked → implemented → qa-handoff`, then `qa:running → verdict-issued`. The full state graph is enforced by `peaks request transition`. A2A's Task object is JSON; peaks's task is **a set of files with a `state` field per role**. |
+| **Artifact** (immutable output) | `rd/tech-doc.md`, `rd/code-review.md`, `rd/security-review.md`, `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md`, `sc/handoff.md` | as listed | peaks's artefacts are *append-once*, not strictly immutable: a `qa/test-reports/<rid>.md` may be re-emitted on repair cycles. The convention is "newest write wins; the file at the end of the workflow is the truth", which is close enough to A2A's immutable-Artifact semantics for translation purposes. |
+| **Message** (non-artifact communication) | `peaks skill presence` heartbeat + transition `--reason` notes | `.peaks/.active-skill.json` (`lastHeartbeat`), transition notes in `.peaks/<sid>/<role>/requests/<rid>.md` | peaks does **not** separate Messages from Artifacts at the storage layer; a "message" is anything that is not the artefact body (the `<!-- peaks-memory:start -->` markers, the `state` field, the `--reason` text on a transition). Treat these as inline metadata of the artefact, not as separate objects. |
+| **Part** (atomic content unit) | Markdown sections within an artefact, frontmatter fields | inline within the artefact | peaks's Artifacts are single Markdown files, so the "Part" concept maps to a heading or a frontmatter field. A `Part`'s `kind` in A2A terms is `text` (the prose), `file` (a `<!-- peaks-memory:start -->` block as a structured chunk), or `data` (the frontmatter). A2A's `form` / `iframe` / video `Part` kinds are not produced by peaks. |
+
+## 3. Field-level mapping (A2A Part ↔ peaks frontmatter)
+
+A2A `Part` has `kind` and `metadata` (free-form) plus `content` (typed by kind). peaks's per-artifact frontmatter carries a subset:
+
+```yaml
+---
+name: <slug>            # used in memory extraction; not a 1:1 A2A field
+description: <title>     # roughly the A2A Artifact.description
+metadata:
+  type: <kind>          # A2A Artifact.kind equivalent
+  sourceArtifact: <rel> # A2A Artifact.source / provenance equivalent
+---
+```
+
+A consumer reading a peaks artefact and translating it to A2A can populate:
+
+- `Artifact.name` ← peaks `name`
+- `Artifact.description` ← peaks `description` (or the first H1)
+- `Artifact.kind` ← peaks `metadata.type`
+- `Artifact.parts[0]` ← the body text (A2A `Part{kind: "text"}`)
+- `Artifact.metadata.sourcePath` ← peaks `metadata.sourceArtifact`
+- `Artifact.metadata.sessionId` ← from `.peaks/.session.json`
+
+The mapping is not 100% lossless: A2A's `Part` can carry structured forms or file references, peaks cannot. That is the explicit *non-goal* of this mapping; it would be over-claiming to assert parity where there is none.
+
+## 4. State-graph mapping (A2A Task ↔ peaks request)
+
+A2A's Task object has a small set of states (typically: `submitted`, `working`, `input-required`, `completed`, `failed`, `canceled`). peaks's per-role request state machine is richer and per-role:
+
+| Role | peaks states (in order) | Closest A2A Task state |
+|---|---|---|
+| `prd` | `draft` → `confirmed-by-user` → `handed-off` | `submitted` → `working` → `input-required` (for the confirm gate) |
+| `rd` | `draft` → `spec-locked` → `implemented` → `qa-handoff` | `working` |
+| `qa` | `draft` → `running` → `verdict-issued` (verdict is `pass` / `return-to-rd` / `blocked`) | `working` → `completed` (pass) / `input-required` (return-to-rd) / `failed` (blocked) |
+| `ui` | `draft` → `direction-locked` → `handed-off` | `working` → `completed` |
+| `sc` | `draft` → `recorded` | `working` → `completed` |
+
+A consumer translating peaks states to A2A should:
+
+- collapse peaks's multi-role state machine to a *single* A2A Task state by taking the most progressed of any role,
+- use the A2A `input-required` state to model **any** gate where peaks is waiting for a human (`confirmed-by-user`, `--confirm`, AskUserQuestion for a login wall, etc.),
+- emit `completed` only when QA verdict is `pass` and SC has recorded the change,
+- emit `failed` on `blocked` QA verdict or `blocked` handoff.
+
+## 5. Worked example: a feature slice from start to finish
+
+A user runs `peaks-solo` for a "add user authentication" feature. Mapping the resulting files to A2A concepts:
+
+```
+.peaks/<sid>/prd/requests/001.md      → A2A Artifact (kind=proposal)
+.peaks/<sid>/ui/requests/001.md       → A2A Artifact (kind=design-direction)
+.peaks/<sid>/ui/design-draft.md       → A2A Artifact (kind=visual-spec)
+.peaks/<sid>/rd/tech-doc.md           → A2A Artifact (kind=implementation-plan)
+.peaks/<sid>/qa/test-cases/001.md     → A2A Artifact (kind=test-cases)
+.peaks/<sid>/rd/code-review.md        → A2A Artifact (kind=review, status=fixed)
+.peaks/<sid>/rd/security-review.md    → A2A Artifact (kind=security-review)
+.peaks/<sid>/qa/test-reports/001.md    → A2A Artifact (kind=test-report, verdict=pass)
+.peaks/<sid>/qa/security-findings.md  → A2A Artifact (kind=security-findings)
+.peaks/<sid>/qa/performance-findings.md → A2A Artifact (kind=performance-findings)
+.peaks/<sid>/sc/handoff.md            → A2A Artifact (kind=change-record)
+.peaks/<sid>/txt/handoff.md           → A2A Artifact (kind=handoff-capsule)
+.peaks/<sid>/system/sub-agent-*.json  → A2A Message (sub-agent presence markers)
+.peaks/<sid>/sc/swarm-plan.json       → A2A Message (the dispatch plan)
+.peaks/memory/*.md                    → A2A Artifact (kind=project-memory, persists across sessions)
+```
+
+A consumer wanting to render a single "feature" object in A2A terms picks the `test-reports/001.md` (verdict=pass) as the terminal Artifact and the rest as supporting Parts or sibling Artifacts. The mapping is intentionally loose: peaks's value is that *all of these files exist*, not that they fit A2A's object model exactly.
+
+## 6. What peaks does NOT provide
+
+To keep the mapping honest, peaks-cli **does not** currently provide the following A2A primitives, and consumers should not expect them:
+
+- A2A **AgentCard** served over HTTP at `/.well-known/agent-card.json`. peaks-cli is a local CLI; its "card" is the on-disk `.peaks/.active-skill.json` plus `peaks skill doctor --json`.
+- A2A **streaming** responses (SSE / WebSocket). peaks commands are synchronous and return a single JSON envelope.
+- A2A **identity / auth** (OAuth, OIDC, mTLS). peaks assumes local-machine trust.
+- A2A **cross-vendor discovery**. peaks has no A2A registry entry; it has `peaks mcp list --json` for MCP-compatible capabilities.
+- A2A **Task delegation across the network**. peaks's "sub-agent" is a Claude Code `Task` tool call in the same process, not a remote A2A server.
+
+These are *deliberate* omissions. peaks-cli solves a different problem (a local workflow-gating CLI for Claude Code), and adopting A2A's networking surface would add weight without addressing peaks's actual failure modes (which are around LLM bypassing gates, not around inter-agent discovery).
+
+## 7. When to re-evaluate
+
+Re-open this mapping in any of the following cases:
+
+- a peaks user reports a real need to share workflow state with a non-peaks agent (e.g. an Autogen / LangChain agent that wants to read a peaks handoff capsule);
+- peaks-cli ships a hosted / multi-user mode where AgentCard-style discovery becomes useful;
+- the A2A protocol stabilises on a thin `Artifact` JSON schema that matches peaks's on-disk shape close enough to make translation a one-liner rather than a reference doc.
+
+Until one of those fires, this reference doc is the entire A2A surface area of peaks-cli. Adding more is over-engineering.