harness-auto-docs 0.1.0

package/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,26 @@
+# Tech Debt Tracker
+
+Tracks known technical debt in `harness-engineering-auto-docs`.
+Updated automatically on each release. See `docs/QUALITY_SCORE.md` for graded gap tracking.
+
+---
+
+## Baseline (v0.1.0 — 2026-04-03)
+
+### Active debt
+
+| ID | Area | Description | Priority | Notes |
+|----|------|-------------|----------|-------|
+| TD-001 | Platform | GitLab MR support not implemented | Medium | `src/providers/gitlab.ts` throws on any call; placeholder only |
+| TD-002 | CLI | Git operations in `cli.ts` use bare `execSync` with no error recovery | Low | A failed push leaves the branch dangling; no cleanup logic |
+| TD-003 | Generator | Prompts are hardcoded strings with no versioning or regression testing | Low | Prompt quality can degrade silently across model updates |
+| TD-004 | Providers | `owner/repo` parsing from git remote URL is fragile | Low | Breaks on SSH remotes (`git@github.com:…`) and non-GitHub hosts |
+| TD-005 | Generator | Diff truncation at 8 000 chars may slice mid-hunk | Low | Large releases may produce incomplete context for the LLM |
+
+### Resolved debt
+
+_None yet — first baseline._
+
+---
+
+<!-- harness-engineering-auto-docs appends sections here on each release -->

package/docs/product-specs/index.md

@@ -0,0 +1,39 @@
+# Product Specs Index
+
+Feature specifications for `harness-engineering-auto-docs`.
+Each entry links to a spec document for a significant feature addition.
+
+<!-- harness-engineering-auto-docs appends entries here when new features are detected in a release -->
+
+## Shipped features
+
+### Auto-documentation pipeline (v0.1.0)
+
+**What it does**: On every `git tag` push, diffs the last two tags, classifies changed files,
+selects relevant documentation targets, calls an LLM to generate content, writes Markdown files,
+and opens a GitHub PR with the updates.
+
+**Trigger**: `git tag v*` → GitHub Actions workflow → `npx harness-engineering-auto-docs`
+
+**Inputs**: `AI_MODEL`, `AI_API_KEY`, `GITHUB_TOKEN` (environment variables)
+
+**Outputs**: Updated Markdown files in target repository + open GitHub PR
+
+**Supported AI models**: `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`,
+`gpt-4o`, `gpt-4o-mini`, `o3`
+
+**Supported platforms**: GitHub (via Octokit). GitLab is a stub.
+
+### Conditional documentation routing (v0.1.0)
+
+**What it does**: Only generates documentation for domains that have actual changes.
+Frontend docs only when frontend files changed; security docs only when auth files changed, etc.
+
+**Routing heuristics**: Defined in `src/core/diff.ts:groupFiles` and `src/core/relevance.ts:selectTargets`.
+
+**Core targets** (always generated): `AGENTS.md`, `ARCHITECTURE.md`, `docs/DESIGN.md`,
+`docs/QUALITY_SCORE.md`, `changelog/vX.Y.Z.md`, `docs/design-docs/vX.Y.Z.md`, design-doc-index,
+tech-debt-tracker.
+
+**Conditional targets**: `docs/FRONTEND.md`, `docs/SECURITY.md`, `docs/RELIABILITY.md`, `db-schema`,
+`product-specs-index`, `references`.

package/docs/references/anthropic-sdk-llms.txt

@@ -0,0 +1,40 @@
+# @anthropic-ai/sdk
+
+## What it is
+
+`@anthropic-ai/sdk` is the official Anthropic TypeScript SDK for calling Claude models via
+the Anthropic Messages API.
+
+## How it is used in this codebase
+
+Used in `src/ai/anthropic.ts` to implement the `AIProvider` interface.
+
+```typescript
+import Anthropic from '@anthropic-ai/sdk';
+
+const client = new Anthropic({ apiKey });
+const message = await client.messages.create({
+  model,
+  max_tokens: 4096,
+  messages: [{ role: 'user', content: prompt }],
+});
+```
+
+The response content is extracted from `message.content[0]` (type `'text'`).
+
+## Model names used in this codebase
+
+- `claude-sonnet-4-6` — default recommended model (good balance of quality and speed)
+- `claude-opus-4-6` — highest quality, slower and more expensive
+- `claude-haiku-4-5-20251001` — fastest and cheapest
+
+Model is selected by the `AI_MODEL` environment variable. The prefix `claude-` routes to
+this provider (see `src/cli.ts:selectAI`).
+
+## Key constraints
+
+- `max_tokens` is hardcoded to `4096` — sufficient for the 2–4 paragraph documentation
+  sections this tool generates
+- Single-turn only — no conversation history is maintained between doc targets
+- Each doc target generates an independent `messages.create` call (via `Promise.all` in
+  `src/core/generator.ts:generateDocs`)

package/docs/references/octokit-rest-llms.txt

@@ -0,0 +1,44 @@
+# @octokit/rest
+
+## What it is
+
+`@octokit/rest` is the official GitHub REST API client for Node.js maintained by the Octokit
+organization. It wraps the GitHub REST API with typed methods, automatic pagination, and
+authentication handling.
+
+## How it is used in this codebase
+
+Used exclusively in `src/providers/github.ts` to:
+
+1. List existing pull requests on the target branch:
+   ```typescript
+   octokit.pulls.list({ owner, repo, head: `${owner}:${branch}` })
+   ```
+
+2. Update an existing PR if one already targets the same branch:
+   ```typescript
+   octokit.pulls.update({ owner, repo, pull_number, title, body })
+   ```
+
+3. Create a new PR when none exists:
+   ```typescript
+   octokit.pulls.create({ owner, repo, head: branch, base: baseBranch, title, body })
+   ```
+
+## Authentication
+
+Instantiated with a GitHub token:
+```typescript
+import { Octokit } from '@octokit/rest';
+const octokit = new Octokit({ auth: token });
+```
+
+The token is provided via `GITHUB_TOKEN` environment variable — either a GitHub Actions token
+or a personal access token with `repo` scope.
+
+## Key constraints in this codebase
+
+- `owner` and `repo` are parsed from `git remote get-url origin` output in `github.ts`
+- The parser handles HTTPS remotes (`https://github.com/owner/repo.git`) but not SSH remotes —
+  this is tracked as TD-004 in `docs/exec-plans/tech-debt-tracker.md`
+- All Octokit calls are awaited directly; no retry logic is implemented

package/docs/references/openai-sdk-llms.txt

@@ -0,0 +1,38 @@
+# openai
+
+## What it is
+
+`openai` is the official OpenAI Node.js / TypeScript SDK for calling GPT and other OpenAI
+models via the Chat Completions API.
+
+## How it is used in this codebase
+
+Used in `src/ai/openai.ts` to implement the `AIProvider` interface.
+
+```typescript
+import OpenAI from 'openai';
+
+const client = new OpenAI({ apiKey });
+const completion = await client.chat.completions.create({
+  model,
+  messages: [{ role: 'user', content: prompt }],
+});
+```
+
+The response text is extracted from `completion.choices[0].message.content`.
+
+## Model names used in this codebase
+
+- `gpt-4o` — recommended GPT model (strong reasoning, good documentation quality)
+- `gpt-4o-mini` — faster and cheaper; suitable for simpler doc targets
+- `o3` — most capable; use for complex architectural documentation
+
+Model is selected by the `AI_MODEL` environment variable. The prefix `gpt-` routes to
+this provider (see `src/cli.ts:selectAI`).
+
+## Key constraints
+
+- No `max_tokens` override — relies on model default (sufficient for 2–4 paragraph outputs)
+- Single-turn only — no conversation history maintained
+- Each doc target is an independent `chat.completions.create` call (via `Promise.all` in
+  `src/core/generator.ts:generateDocs`)