opencode-swarm 7.100.1 → 7.101.0

package/dist/sdd/effective-spec.d.ts

@@ -1,4 +1,4 @@
-export type EffectiveSpecSource = 'swarm' | 'openspec_projection';
+export type EffectiveSpecSource = 'swarm' | 'openspec_projection' | 'speckit_projection';
 export interface OpenSpecArtifact {
     relPath: string;
     bytes: number;
@@ -29,17 +29,218 @@ export interface SddStatus {
     errors: string[];
     warnings: string[];
 }
-export declare function loadSddStatusSync(directory: string): SddStatus;
+/** A single Spec-Kit feature directory containing a spec.md. */
+export interface SpeckitFeatureEntry {
+    /** Full directory name, e.g. `001-feature-name`. */
+    featureId: string;
+    /** Posix-normalized path relative to the repo root, e.g. `specs/001-feature-name/spec.md`. */
+    specRelPath: string;
+}
+/** Result returned by {@link detectSpeckit}. */
+export interface SpeckitDetection {
+    /** Whether the `.specify/` marker directory is present at the repo root (A-001). */
+    markerPresent: boolean;
+    /**
+     * Detected feature directories, sorted lexicographically by {@link SpeckitFeatureEntry.featureId}.
+     * Empty when no `specs/<feature>/spec.md` files are found (or when markerPresent is false).
+     */
+    features: SpeckitFeatureEntry[];
+}
+/**
+ * Discriminated union returned by {@link resolveSpeckitProjection} (task 1.4).
+ *
+ * Each kind carries exactly the information the command layer (task 2.2) needs to
+ * produce the correct error message per FR-008, FR-012, FR-013 without re-detecting.
+ *
+ * - `not_speckit`      — no `.specify/` marker at the repo root (A-001).
+ * - `empty`            — marker present but no `specs/NNN/spec.md` feature dirs (FR-012).
+ * - `ambiguous`        — more than one feature and no `options.feature` given (FR-008);
+ *                        `features` = sorted feature ids for naming in the error message.
+ * - `unknown_feature`  — `options.feature` was given but matches no detected feature.
+ * - `zero_requirements`— the selected feature's spec.md yielded zero parsable functional
+ *                        requirements (covers unreadable/oversized *input* files too) (FR-013).
+ * - `too_large`        — requirements parsed, but the projected *output* exceeds the byte
+ *                        cap and is refused; `bytes` is the projected size. Distinct from
+ *                        zero_requirements so the command layer reports the real reason.
+ * - `ok`               — a valid projection was built; `spec` is ready for use, `feature`
+ *                        identifies the projected feature dir name.
+ */
+export type SpeckitResolution = {
+    kind: 'not_speckit';
+} | {
+    kind: 'empty';
+} | {
+    kind: 'ambiguous';
+    features: string[];
+} | {
+    kind: 'unknown_feature';
+    feature: string;
+    available: string[];
+} | {
+    kind: 'zero_requirements';
+    feature: string;
+} | {
+    kind: 'too_large';
+    feature: string;
+    bytes: number;
+} | {
+    kind: 'ok';
+    spec: EffectiveSpec;
+    feature: string;
+};
+/**
+ * Detect whether `directory` is a GitHub Spec-Kit project (FR-001, A-001).
+ *
+ * Detection key: the `.specify/` marker directory at the repo root.
+ * A repo with `specs/` but no `.specify/` is NOT a Spec-Kit repo (A-001).
+ *
+ * When the marker is present, enumerates all direct children of `specs/` that
+ * contain a `spec.md` file.  The enumeration is:
+ * - One level deep (depth is bounded by construction — stronger than MAX_WALK_DEPTH).
+ * - Bounded by MAX_SPEC_FILES.
+ * - Symlink-safe: directories and spec.md files that are symlinks are skipped.
+ * - Size-bounded: spec.md files exceeding MAX_SOURCE_BYTES are skipped.
+ * - Error-swallowing: unreadable directories are skipped silently.
+ * - Deterministic: feature entries are sorted lexicographically by featureId.
+ *
+ * Does NOT read or parse spec.md content — detection only (FR-001).
+ */
+export declare function detectSpeckit(directory: string): SpeckitDetection;
+/**
+ * Resolve a Spec-Kit feature projection with a discriminated result (FR-008, FR-012, FR-013).
+ *
+ * Returns one of six kinds so the command layer can produce the right error message without
+ * re-running detection:
+ * - `not_speckit`       — no `.specify/` marker (A-001).
+ * - `empty`             — marker present but no feature dirs (FR-012).
+ * - `ambiguous`         — multiple features, no `options.feature` (FR-008).
+ * - `unknown_feature`   — `options.feature` not among detected features.
+ * - `zero_requirements` — feature found but yields zero parsable FRs, or spec.md unreadable
+ *                         (FR-013; covers oversized files too).
+ * - `ok`                — valid EffectiveSpec built (FR-002, FR-003, FR-004, FR-005).
+ *
+ * This function is the single source of truth for feature selection logic.
+ * {@link buildSpeckitProjectionSync} delegates here and maps `ok → spec | null`.
+ */
+export declare function resolveSpeckitProjection(directory: string, options?: {
+    feature?: string;
+}): SpeckitResolution;
+/**
+ * Project a single Spec-Kit feature into an EffectiveSpec (FR-002, FR-003, FR-004, FR-005).
+ *
+ * Delegates all selection and build logic to {@link resolveSpeckitProjection} — that function
+ * is the single source of truth for feature selection.  This wrapper preserves the existing
+ * `EffectiveSpec | null` contract so all call sites (task 2.2, tests) are unchanged.
+ *
+ * Returns null when resolution is anything other than `ok` (not_speckit, empty, ambiguous,
+ * unknown_feature, zero_requirements).  Callers that need the failure reason should call
+ * {@link resolveSpeckitProjection} directly.
+ */
+export declare function buildSpeckitProjectionSync(directory: string, options?: {
+    feature?: string;
+}): EffectiveSpec | null;
+export declare function loadSddStatusSync(directory: string, opts?: ReadEffectiveSpecOpts): SddStatus;
 export declare function buildOpenSpecProjectionSync(directory: string, options?: {
     changeId?: string;
 }): EffectiveSpec | null;
-export declare function readEffectiveSpecSync(directory: string): EffectiveSpec | null;
+/**
+ * Resolver options for {@link readEffectiveSpecSync} (task 2.1, FR-009).
+ *
+ * Both fields are optional so that all 13 existing single-argument call sites
+ * continue to work unchanged.
+ */
+export interface ReadEffectiveSpecOpts {
+    /**
+     * Explicit provider selection (FR-009 step b).
+     * When given, the specified provider is used directly after the native swarm
+     * spec check.  A `'swarm'` selection with no `.swarm/spec.md` returns null.
+     */
+    source?: 'swarm' | 'openspec' | 'speckit';
+    /**
+     * Feature selector forwarded to {@link buildSpeckitProjectionSync} when the
+     * effective provider is Spec-Kit.  Ignored for `source: 'openspec'` or
+     * `source: 'swarm'` (feature-vs-non-speckit source validation is enforced at
+     * the command layer in task 2.2, not here).
+     */
+    feature?: string;
+}
+/**
+ * Read (or build) the effective spec for a directory, applying deterministic
+ * source precedence (FR-009, FR-010, FR-011).
+ *
+ * **Precedence:**
+ * a. `.swarm/spec.md` present → return the native swarm spec.  This branch is
+ *    IDENTICAL to the pre-task-2.1 code and wins even over an explicit
+ *    `opts.source` — native swarm spec always wins (FR-009).
+ * b. `opts.source` given → use that provider: `'openspec'` calls
+ *    {@link buildOpenSpecProjectionSync}; `'speckit'` calls
+ *    {@link buildSpeckitProjectionSync}; `'swarm'` with no `.swarm/spec.md`
+ *    returns null.
+ * c. Auto-detect:
+ *    - **No `.specify/` marker** → byte-identical to pre-task-2.1 behavior:
+ *      call {@link buildOpenSpecProjectionSync} and return its result (FR-011).
+ *    - **`.specify/` present but no feature dirs** (empty marker) → Spec-Kit is
+ *      NOT counted as a competing source; behaves like the no-marker case.
+ *    - **`.specify/` with ≥1 feature dir and no openspec projection** → return
+ *      the Spec-Kit projection.
+ *    - **`.specify/` with ≥1 feature dir AND openspec yields a projection** →
+ *      AMBIGUOUS (FR-010): emit a concrete diagnostic via `console.warn` (the
+ *      anti-silent-suppression requirement; critic Finding 2) and return null.
+ *      The diagnostic is independent of the return value so it fires even when
+ *      no consumer inspects the null return (e.g. the drift gate, which only
+ *      checks for null to decide advisory-vs-blocking mode).
+ *
+ * **Backward-compat (FR-011):** when `.detectSpeckit(directory).markerPresent`
+ * is false, the function is byte-identical to pre-task-2.1.  The additional
+ * `detectSpeckit` call (a single `fs.existsSync`) is the only overhead.
+ *
+ * **Deviation from task-2.1 literal text:** the task body says "Spec-Kit
+ * present (`detectSpeckit(dir).markerPresent`)" but plan.md task 3.1 and the
+ * test note both state that an empty `.specify/` "would never reach the
+ * ambiguity branch."  `markerPresent` is true for empty-specify, so it cannot
+ * be the discriminator.  We use `features.length > 0` instead, which is
+ * symmetric with "OpenSpec present (yields a projection)" and makes empty
+ * `.specify/` a non-competing source, matching both citations.
+ */
+export declare function readEffectiveSpecSync(directory: string, opts?: ReadEffectiveSpecOpts): EffectiveSpec | null;
 export declare function writeProjectedSpecSync(directory: string, options?: {
     changeId?: string;
     dryRun?: boolean;
+    /** When `'speckit'`, builds a Spec-Kit projection instead of OpenSpec (task 2.2). */
+    source?: 'openspec' | 'speckit';
+    /** Feature selector forwarded to buildSpeckitProjectionSync when source is speckit. */
+    feature?: string;
 }): {
     written: boolean;
     projection: EffectiveSpec | null;
     archivePath?: string;
     path: string;
 };
+/**
+ * Validate Spec-Kit artifacts READ-ONLY (FR-007, task 2.3).
+ *
+ * MUST NOT write or modify any Spec-Kit artifact — it only reads spec.md and
+ * tasks.md to report structural problems.
+ *
+ * Returns the {@link SpeckitResolution} from {@link resolveSpeckitProjection}
+ * alongside a flat `problems` array.  Returning both avoids a second
+ * `resolveSpeckitProjection` call in the command layer (which would need the
+ * projection's hash / sourcePaths from `resolution.spec`).
+ *
+ * **Problems reported** (only when `resolution.kind` is `'ok'` or
+ * `'zero_requirements'` — i.e. when we have a feature to inspect):
+ * - Zero parsable functional requirements (`zero_requirements` kind, FR-013).
+ * - Missing required spec.md sections (`SPECKIT_REQUIRED_SECTIONS`).
+ * - `tasks.md` task lines that carry no `[US#]` user-story reference (FR-007).
+ *
+ * For other resolution kinds (`not_speckit`, `empty`, `ambiguous`,
+ * `unknown_feature`, `too_large`) the command layer uses
+ * {@link formatSpeckitError} on the returned resolution — same messaging path
+ * as task 2.2 (plan.md task 2.3 requirement: no second messaging scheme).
+ */
+export declare function validateSpeckit(directory: string, options?: {
+    feature?: string;
+}): {
+    resolution: SpeckitResolution;
+    problems: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.100.1",
+	"version": "7.101.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",