# Determinism

This document defines the determinism contract for Specky. The goal is that versioned artifacts generated from the same input, configuration, and runtime context can be reproduced exactly.

## Deterministic Contract

Specky generated artifacts should be stable across repeated runs when these inputs are fixed:

- Workspace contents
- Tool input payload
- Specky configuration
- Template content
- Runtime clock
- Runtime locale and timezone
- Tool version

Audit logs and operational logs may include real timestamps, but versioned artifacts should use the deterministic runtime context.

## Runtime Context

The implementation should introduce a shared runtime context for all tools:

```ts
interface RuntimeContext {
  now(): Date;
  timezone: "UTC";
  locale: "en-US";
  deterministicMode: boolean;
  requestId: string;
}
```

Expected defaults:

| Field | Default | Deterministic Mode |
| --- | --- | --- |
| Clock | Current time | Fixed or supplied time |
| Timezone | UTC | UTC |
| Locale | `en-US` | `en-US` |
| Request ID | Random or MCP-supplied | Stable generated ID when required |

## Stable Output Rules

1. Sort filesystem-derived lists before using them in output.
2. Use stable JSON serialization for machine-readable artifacts.
3. Avoid locale-sensitive rendering in versioned artifacts.
4. Use canonical IDs from shared helpers, not ad hoc regexes.
5. Avoid embedding generated-at timestamps unless they come from the runtime context.
6. Keep temporary file randomness out of persisted artifacts.

## ID Contracts

Canonical formats:

| Entity | Format | Example |
| --- | --- | --- |
| Requirement | `REQ-CAT-001` | `REQ-CORE-001` |
| Task | `T-001` | `T-001` |
| Feature | `001-feature-name` | `001-enterprise-hardening` |

All schemas, parsers, templates, hooks, docs, and tests must use the same constants.

## Known Gaps To Close

These areas must be remediated before Specky can claim full deterministic artifact generation:

- Generated docs currently use direct `new Date()` calls in several services.
- Some file listing paths rely on unsorted `readdir` results.
- Task ID parsing has been normalized for core parsers; keep hooks, templates, and future tools aligned with the shared ID helpers.
- `DocumentConverter` currently reads files directly instead of consistently using `FileManager`.

## Validation Plan

Add tests that assert:

```text
same input + same clock + same workspace = byte-for-byte same artifact
```

Minimum deterministic test targets:

- Template frontmatter
- Full docs generation
- API docs generation
- Runbook generation
- Metrics dashboard generation
- Test stub generation
- PBT stub generation
- Transcript auto-pipeline output
- Branch governance/evidence docs generated by automation, if added

## References

- [JSON Canonicalization Scheme (RFC 8785)](https://www.rfc-editor.org/rfc/rfc8785)
- [W3C Date and Time Formats](https://www.w3.org/TR/NOTE-datetime)
- [Node.js fs.readdir API](https://nodejs.org/api/fs.html#fspromisesreaddirpath-options)