@wkronmiller/lisa 0.1.0

package/src/spec/skill-content.ts

@@ -0,0 +1,119 @@
+/**
+ * Generic Lisa skill content for repos that use Lisa.
+ * This is NOT the Lisa-repo-specific skill - it's what gets written
+ * into any repo that runs `lisa spec init`.
+ */
+
+export const LISA_SKILL_FRONTMATTER = `---
+name: lisa
+description: Spec-driven development workflow using Lisa. Use this skill when working with specs, implementing features, or verifying code against specs in this repo.
+---`;
+
+export const LISA_SKILL_BODY = `# Lisa
+
+This project uses Lisa for spec-driven development. Specs in .specs/ are the source of truth for intended behavior.
+
+## Workflow
+
+\`\`\`text
+specs -> git diff -> structured deltas -> plan -> implementation -> tests/benchmarks -> verification -> reports
+\`\`\`
+
+Typical loop:
+
+1. Write or update a spec under .specs/backend/ or .specs/frontend/.
+2. Run \`lisa spec diff\` to see what changed and the derived plan.
+3. Run \`lisa spec implement\` to apply code and test changes.
+4. Run \`lisa spec check --changed\` to verify conformance.
+
+## Commands
+
+\`\`\`text
+lisa spec init                              Scaffold a .specs workspace
+lisa spec status                            Show workspace and harness status
+lisa spec config --harness <id>             Set local harness override
+lisa spec guide [backend|frontend] [name]   Create a seed spec with guided next steps
+lisa spec generate [backend|frontend] [name] Draft a spec with preview and approval
+lisa spec diff                              Show changed spec deltas and plan
+lisa spec implement                         Implement code changes from spec deltas
+lisa spec check --changed                   Verify only changed specs
+lisa spec check --all                       Verify all active specs
+lisa spec import <path...>                  Draft specs from existing code
+\`\`\`
+
+## Spec layout
+
+\`\`\`text
+.specs/
+  backend/
+    <spec-name>.md
+    <spec-name>.bench.<environment>.md
+  frontend/
+    <spec-name>.md
+  environments/
+    <environment>.yaml
+  config.yaml
+  config.local.yaml          (gitignored, local harness override)
+\`\`\`
+
+## Spec format
+
+Active base specs are markdown with YAML frontmatter:
+
+\`\`\`md
+---
+id: backend.example
+status: active
+code_paths:
+  - src/example/**
+test_paths:
+  - tests/example/**
+test_commands:
+  - npm test -- example
+---
+
+# Summary
+What this feature does.
+
+## Use Cases
+- Primary user or system flows.
+
+## Invariants
+- Behavior that must always remain true.
+
+## Failure Modes
+- Edge cases and error handling.
+
+## Acceptance Criteria
+- Observable outcomes that prove the behavior works.
+
+## Out of Scope
+- What this spec does not cover.
+\`\`\`
+
+Required frontmatter: \`id\`, \`status\`, \`code_paths\`, and at least one of \`test_paths\` or \`test_commands\`.
+
+Required sections for active specs: Summary, Use Cases, Invariants, Acceptance Criteria, Out of Scope.
+
+Statuses: \`draft\` (not enforced), \`active\` (source of truth), \`deprecated\` (historical).
+
+## Working with specs
+
+- Review active specs before changing behavior in their \`code_paths\`.
+- When changing behavior, update the spec, code, and tests together.
+- Do not treat spec deletion as permission to silently remove code.
+- Keep edits within the mapped \`code_paths\` unless a supporting change is clearly required.
+- Use \`lisa spec guide\` to scaffold a new spec with placeholders, then fill it in before running implement.
+
+## Verification
+
+\`lisa spec check\` produces reports at .lisa/spec-report.json and .lisa/spec-report.md.
+
+Verdicts per spec: \`PASS\`, \`FAIL\`, \`UNSURE\`, \`SKIPPED\`.
+`;
+
+export const LISA_ROOT_GUIDANCE = `This project uses [Lisa](https://github.com/wkronmiller/lisa) for spec-driven development.
+
+Behavioral specs live in .specs/ and are the source of truth for intended behavior. Before making changes, review the relevant specs. Use \`lisa spec\` commands to implement and verify against specs.
+
+For full Lisa workflow guidance, see the Lisa skill.`;

package/src/spec/types.ts

@@ -0,0 +1,239 @@
+import type { Stage } from "../harness/types";
+import type { LisaStorageMode } from "./workspace";
+
+export const SPEC_AREAS = ["backend", "frontend"] as const;
+export const SPEC_KINDS = ["base", "benchmark", "extension"] as const;
+export const SPEC_STATUSES = ["draft", "active", "deprecated"] as const;
+export const SPEC_STAGES: Stage[] = ["generate", "implement", "check", "import"];
+export const SPEC_IMPORT_UNCERTAINTY_LEVELS = ["low", "medium", "high"] as const;
+
+export type SpecArea = (typeof SPEC_AREAS)[number];
+export type SpecKind = (typeof SPEC_KINDS)[number];
+export type SpecStatus = (typeof SPEC_STATUSES)[number];
+export type SpecImportUncertaintyLevel = (typeof SPEC_IMPORT_UNCERTAINTY_LEVELS)[number];
+
+export interface ParsedMarkdownSection {
+  title: string;
+  level: number;
+  content: string;
+}
+
+export interface ParsedSpecDocument {
+  path: string;
+  filename: string;
+  area?: SpecArea;
+  kind: SpecKind;
+  extensionKind?: string;
+  id?: string;
+  status?: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  sections: ParsedMarkdownSection[];
+}
+
+export interface ParsedEnvironmentConfig {
+  path: string;
+  name?: string;
+  runtime?: Record<string, unknown>;
+  resources?: Record<string, unknown>;
+  notes?: string;
+  raw: Record<string, unknown>;
+}
+
+export interface ParsedStageProfile {
+  harness?: string;
+  model?: string;
+  allowEdits?: boolean;
+  raw: Record<string, unknown>;
+}
+
+export interface ParsedHarnessConfig {
+  command?: string;
+  args: string[];
+  raw: Record<string, unknown>;
+}
+
+export interface ParsedAgentGuidanceConfig {
+  enabled?: boolean;
+  target?: string;
+  targets?: string[];
+  raw: Record<string, unknown>;
+}
+
+export interface ParsedSpecConfig {
+  path: string;
+  raw: Record<string, unknown>;
+  defaultStageProfiles: Partial<Record<Stage, string>>;
+  profiles: Record<string, ParsedStageProfile>;
+  harnesses: Record<string, ParsedHarnessConfig>;
+  agentGuidance?: ParsedAgentGuidanceConfig;
+}
+
+export interface StageProfileOverrides {
+  profile?: string;
+  harness?: string;
+  model?: string;
+}
+
+export interface ResolvedStageProfile {
+  stage: Stage;
+  profileName: string;
+  harness: string;
+  model?: string;
+  allowEdits: boolean;
+  command?: string;
+  args: string[];
+}
+
+export type SpecFileChange = "added" | "modified" | "deleted";
+
+export interface SpecSectionChange {
+  section: string;
+  changeType: string;
+  oldText?: string;
+  newText?: string;
+}
+
+export interface SpecDelta {
+  specId: string;
+  path: string;
+  kind: SpecKind;
+  extensionKind?: string;
+  fileChange: SpecFileChange;
+  sectionChanges: SpecSectionChange[];
+  previousDocument?: ParsedSpecDocument;
+  nextDocument?: ParsedSpecDocument;
+  extendsSpecId?: string;
+}
+
+export interface SpecDiffReport {
+  workspacePath: string;
+  baseRef: string;
+  headRef: string;
+  deltas: SpecDelta[];
+}
+
+export interface PlannedTask {
+  id: string;
+  specId: string;
+  type: "code" | "test" | "benchmark" | "review" | "doc";
+  description: string;
+  targets?: string[];
+}
+
+export interface PlannedBenchmarkContext {
+  id: string;
+  path: string;
+  fileChange: SpecFileChange;
+  environment?: string;
+  required?: boolean;
+  command?: string;
+  metrics: Record<string, string>;
+}
+
+export interface PlannedSpecTarget {
+  specId: string;
+  path: string;
+  fileChange: SpecFileChange;
+  codePaths: string[];
+  testPaths: string[];
+  testCommands: string[];
+  invariants: string[];
+  acceptanceCriteria: string[];
+  benchmarkSidecars: PlannedBenchmarkContext[];
+}
+
+export interface SpecImplementationPlan {
+  diff: SpecDiffReport;
+  tasks: PlannedTask[];
+  impactedSpecs: PlannedSpecTarget[];
+  testCommands: string[];
+  deletedSpecIds: string[];
+}
+
+export interface ValidationIssue {
+  severity: "error" | "warning";
+  path: string;
+  message: string;
+}
+
+export type SpecCheckMode = "changed" | "all";
+export type SpecCheckStatus = "PASS" | "FAIL" | "UNSURE" | "SKIPPED";
+export type SpecCheckEvidenceType = "test" | "benchmark" | "code-audit" | "config";
+
+export interface SpecCheckEvidence {
+  type: SpecCheckEvidenceType;
+  detail: string;
+}
+
+export interface SpecCheckResult {
+  specId: string;
+  path: string;
+  status: SpecCheckStatus;
+  summary: string;
+  evidence: SpecCheckEvidence[];
+  issues: string[];
+}
+
+export interface SpecDriftWarning {
+  specId: string;
+  path: string;
+  changedPaths: string[];
+  message: string;
+}
+
+export interface SpecCheckReport {
+  workspacePath: string;
+  mode: SpecCheckMode;
+  baseRef?: string;
+  headRef?: string;
+  generatedAt: string;
+  profile: string;
+  harness: string;
+  results: SpecCheckResult[];
+  driftWarnings: SpecDriftWarning[];
+  summary: {
+    pass: number;
+    fail: number;
+    unsure: number;
+    skipped: number;
+  };
+}
+
+export interface LoadedSpecWorkspace {
+  workspacePath: string;
+  storageMode: LisaStorageMode;
+  specRoot: string;
+  repoSpecRoot: string;
+  worktreeSpecRoot?: string;
+  configPath: string;
+  localConfigRoot: string;
+  runtimeRoot: string;
+  snapshotRoot: string;
+  metadataPath?: string;
+  globalPackRoots: string[];
+  config?: ParsedSpecConfig;
+  environments: ParsedEnvironmentConfig[];
+  documents: ParsedSpecDocument[];
+  issues: ValidationIssue[];
+}
+
+export interface SpecImportUncertainty {
+  path?: string;
+  specId?: string;
+  level: SpecImportUncertaintyLevel;
+  detail: string;
+  question?: string;
+}
+
+export interface SpecImportReport {
+  workspacePath: string;
+  generatedAt: string;
+  selectedPaths: string[];
+  profile: string;
+  harness: string;
+  files: string[];
+  notes: string[];
+  uncertainties: SpecImportUncertainty[];
+  dryRun: boolean;
+}