Ingeniería de Specs

// scripts/score-spec.ts
interface SpecQualityScore {
  acceptanceCriteriaScore: number;   // 0-25
  behavioralContractScore: number;   // 0-25
  contextCompletenessScore: number;  // 0-25
  taskDecompositionScore: number;    // 0-25
  total: number;                     // 0-100
  grade: "A" | "B" | "C" | "D" | "F";
  suggestions: string[];
}

function scoreSpec(specContent: string): SpecQualityScore {
  const suggestions: string[] = [];

  // Score acceptance criteria
  let acScore = 0;
  const acTable = specContent.match(
    /\| AC-\d+.*\|/g
  );
  if (acTable && acTable.length > 0) {
    acScore += 10; // Has structured ACs
    if (acTable.every((row) => row.includes("-test") || row.includes("-check"))) {
      acScore += 10; // All ACs have validation methods
    } else {
      suggestions.push(
        "Some acceptance criteria lack validation methods"
      );
    }
    if (acTable.length >= 5) {
      acScore += 5; // Sufficient coverage
    } else {
      suggestions.push(
        "Consider adding more acceptance criteria for edge cases"
      );
    }
  } else {
    suggestions.push(
      "Add structured acceptance criteria with IDs and validation methods"
    );
  }

  // Score behavioral contract
  let bcScore = 0;
  if (specContent.includes("**Inputs:**")) bcScore += 5;
  else suggestions.push("Add an Inputs table to the behavioral contract");
  if (specContent.includes("**Outputs (success):**")) bcScore += 5;
  else suggestions.push("Add a success Outputs table");
  if (specContent.includes("**Outputs (error):**")) bcScore += 5;
  else suggestions.push("Add an error Outputs table");
  if (specContent.includes("**Behavior — Normal Flow:**")) bcScore += 5;
  else suggestions.push("Add normal flow behavior description");
  if (specContent.includes("**Behavior — Error Flow:**")) bcScore += 5;
  else suggestions.push("Add error flow behavior description");

  // Score context completeness
  let ctxScore = 0;
  if (specContent.includes("## System Constitution")) ctxScore += 5;
  else suggestions.push("Add System Constitution reference");
  if (specContent.includes("Golden Sample")) ctxScore += 10;
  else suggestions.push("Add golden sample references");
  if (specContent.includes("Context Packet")) ctxScore += 5;
  else suggestions.push("Add context packet file listing");
  if (specContent.includes("token") || specContent.includes("budget"))
    ctxScore += 5;
  else suggestions.push("Add token budget estimate");

  // Score task decomposition
  let tdScore = 0;
  const taskMatches = specContent.match(/### Task \d+/g);
  if (taskMatches && taskMatches.length > 0) {
    tdScore += 10;
    if (specContent.includes("**Dependencies:**")) tdScore += 5;
    if (specContent.includes("**Validates:**")) tdScore += 5;
    if (specContent.includes("**Golden Sample:**")) tdScore += 5;
  } else {
    suggestions.push("Decompose spec into ordered subtasks with dependencies");
  }

  const total = acScore + bcScore + ctxScore + tdScore;
  const grade =
    total >= 85
      ? "A"
      : total >= 70
        ? "B"
        : total >= 55
          ? "C"
          : total >= 40
            ? "D"
            : "F";

  return {
    acceptanceCriteriaScore: acScore,
    behavioralContractScore: bcScore,
    contextCompletenessScore: ctxScore,
    taskDecompositionScore: tdScore,
    total,
    grade,
    suggestions,
  };
}

# BEFORE: Vague spec that causes agent failures
# ------------------------------------------------
feature: User Authentication
description: Add login functionality
requirements:
  - Users can log in with email and password
  - Show error on invalid credentials
  - Use JWT for sessions
notes: Follow existing patterns

# AFTER: Engineered spec that agents execute reliably
# ------------------------------------------------
feature: User Authentication — Login Endpoint
spec_version: 1
status: ready
author: "@context-architect"

behavioral_contract:
  purpose: "Authenticate user by email/password, return signed JWT"
  inputs:
    - name: email
      type: string
      constraints: "RFC 5322 email format"
      required: true
    - name: password
      type: string
      constraints: "8-128 characters"
      required: true
  outputs_success:
    - name: token
      type: string
      description: "RS256-signed JWT, 24h expiry, contains userId/email/role"
    - name: user
      type: object
      description: "{ id: string, email: string, role: string }"
  outputs_error:
    - status: 401
      code: AUTH_INVALID_CREDENTIALS
      when: "Email exists but password does not match"
    - status: 401
      code: AUTH_USER_NOT_FOUND
      when: "No user with provided email"
    - status: 429
      code: AUTH_RATE_LIMITED
      when: "5+ failures from same IP in 15 minutes"
    - status: 400
      code: AUTH_INVALID_INPUT
      when: "Email or password fails format validation"

acceptance_criteria:
  - id: AC-1
    criterion: "Returns 200 with JWT on valid credentials"
    validation: integration-test
    priority: must-have
  - id: AC-2
    criterion: "Returns 401 AUTH_INVALID_CREDENTIALS on wrong password"
    validation: integration-test
    priority: must-have
  - id: AC-3
    criterion: "Returns 429 after 5 failed attempts from same IP in 15min"
    validation: integration-test
    priority: must-have
  - id: AC-4
    criterion: "JWT uses RS256, contains userId/email/role, 24h expiry"
    validation: unit-test
    priority: must-have
  - id: AC-5
    criterion: "bcrypt timing-safe comparison for passwords"
    validation: unit-test
    priority: must-have

system_constitution_ref: "context/constitution/coding-standards.md"
golden_samples:
  - path: "src/users/services/user-service.ts"
    demonstrates: "Service pattern, error handling"
  - path: "src/users/__tests__/user-service.test.ts"
    demonstrates: "Test structure, mocking"

context_packet:
  - "prisma/schema.prisma"
  - "src/shared/errors/app-error.ts"
  - "docs/api/auth-spec.yaml"

task_map:
  - id: 1
    name: "Input validation schema"
    deliverable: "src/auth/schemas/login-schema.ts"
    validates: [AC-4]
    dependencies: []
  - id: 2
    name: "Auth service login method"
    deliverable: "src/auth/services/auth-service.ts"
    validates: [AC-1, AC-2, AC-3, AC-4, AC-5]
    dependencies: [1]
  - id: 3
    name: "Auth controller login endpoint"
    deliverable: "src/auth/controllers/auth-controller.ts"
    validates: [AC-1, AC-2, AC-3]
    dependencies: [2]
  - id: 4
    name: "Rate limiting middleware"
    deliverable: "src/auth/middleware/rate-limiter.ts"
    validates: [AC-3]
    dependencies: []
  - id: 5
    name: "Tests for all acceptance criteria"
    deliverable: "src/auth/__tests__/"
    validates: [AC-1, AC-2, AC-3, AC-4, AC-5]
    dependencies: [1, 2, 3, 4]

token_budget: 12000