qa-flowkit 0.4.0-alpha.0

package/ROADMAP.md

@@ -0,0 +1,107 @@
+# Roadmap
+
+## Current status - Target-repo hardening
+
+QA FlowKit has moved beyond the folder-copy MVP. The portable `.qa-ai/` framework, init/bootstrap scripts, adapters, validation workflow, CI, GitHub repository hardening and public releases are in place.
+
+The current product phase is **Target-repo hardening**: the starter has been validated in a real pilot repository and the core workflow is correct. Current work should focus on stricter target-repository validation, clearer pilot migration notes, guided examples and packaging.
+
+## Completed - Portable folder MVP
+
+Goal: create a folder that can be copied into any QA/automation repository.
+
+Delivered:
+
+- `.qa-ai/` portable framework structure.
+- `qa-ai.config.yaml` generation.
+- Agent adapter generation for Claude Code, OpenCode, Codex, Cline, Continue, Aider, Goose and Gemini CLI.
+- Agent-first bootstrap through `/qa-init` for Claude Code and OpenCode.
+- Documentation, rules, templates and validation scripts.
+- Manifest-based cleanup with dry-run default.
+- CI workflow running doctor, validators and smoke tests.
+- GitHub repository hardening with branch rules, CodeQL, Dependabot and secret scanning.
+
+## Completed - Pilot repositories
+
+Goal: validate that the workflow works across different QA and automation setups.
+
+Delivered:
+
+- Pilot with WebdriverIO + Playwright API.
+- Feedback from generated Gherkin, traceability and automation planning.
+- Confirmation that the folder-copy workflow, init scripts, adapters and validators work correctly in a target repository.
+
+Follow-up:
+
+- Document friction points and migration notes from the pilot.
+- Add a second pilot when useful, preferably Selenium + Jest + BrowserStack or manual-only, to widen coverage.
+
+## Phase 2 - Stronger validators
+
+Goal: make the framework reliable without trusting prompts only.
+
+Delivered:
+
+- Parsed Gherkin structure validation for feature files.
+- Duplicate explicit test case ID validation.
+- Traceability matrix coverage validation.
+- Traceability matrix row shape and duplicate matrix entry validation.
+- Proposal-first test-management sync plan validation.
+- Test-management sync plan table shape and duplicate ID validation.
+- Test-management mapping file shape, duplicate external ID and secret-like value validation.
+- Active specialist index validation against `qa-ai.config.yaml`.
+- `doctor --strict` for fully initialized target repositories.
+
+Next:
+
+- Replace lightweight parsing with a full Gherkin parser when the project accepts dependencies or ships an npm CLI.
+- Validate dry-run TestRail/Zephyr/Xray plans against richer mapping schemas.
+
+## Phase 3 - Guided examples and public docs
+
+Goal: make adoption obvious for first-time users.
+
+Deliverables:
+
+- Example manual-only repository.
+- Example WebdriverIO + Playwright API repository.
+- Getting-started flows by user type: manual QA, automation QA, maintainers and agent-first users.
+- Troubleshooting guide for init, adapters, feature validation and CI failures.
+- Screenshots or short terminal transcripts for common workflows.
+
+## Phase 4 - npm CLI
+
+Goal: replace manual copy with `npx qa-flowkit init` while keeping the folder-copy workflow as a fallback.
+
+Deliverables:
+
+- Node package: delivered for `0.4.0-alpha.0`.
+- Non-interactive CI-friendly install: delivered through `qa-flowkit init`.
+- Update/migration command: delivered through `qa-flowkit update`.
+- Presets: reused from `.qa-ai/presets`.
+- Interactive prompts: future enhancement after the zero-dependency alpha CLI.
+
+## Phase 5 - MCP and integrations
+
+Goal: add controlled integrations with Jira, Confluence, TestRail and GitHub.
+
+Deliverables:
+
+- MCP configuration templates.
+- Read-only requirement intake tools.
+- Proposal-first write tools.
+- Audit logs.
+- Approval gates.
+
+## Phase 6 - Productization
+
+Goal: turn the starter into a stable open-source framework.
+
+Deliverables:
+
+- Public documentation site.
+- Example repositories.
+- Adapter registry.
+- Stable config contract.
+- Release automation.
+- Compatibility and migration policy.

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security Policy
+
+## Supported versions
+
+The project is currently in MVP stage. Security fixes target the latest version of `main`.
+
+## Reporting a vulnerability
+
+Do not open public issues for secrets, credential leaks or high-impact security problems. Contact the maintainers privately.
+
+## Security principles
+
+- Never commit credentials, API tokens or personal data.
+- `.qa-ai/` must not store secrets.
+- Generated `.mcp.json` files must use environment variables.
+- External writes to Jira, Confluence, TestRail or GitHub must require explicit user approval.
+- Deletion operations should be disabled by default.
+- Scripts must prefer dry-run or proposal-first behavior.

package/bin/qa-flowkit.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const packagedFramework = path.join(packageRoot, '.qa-ai');
+const cwd = process.cwd();
+const targetFramework = path.join(cwd, '.qa-ai');
+
+const commandMap = {
+  doctor: 'doctor.mjs',
+  'validate-target': 'validate-target.mjs',
+  'validate-features': 'validate-features.mjs',
+  'sync-adapters': 'sync-agent-adapters.mjs',
+  help: 'qa-help.mjs',
+  clean: 'clean.mjs'
+};
+
+function printHelp() {
+  console.log(`QA FlowKit
+
+Usage:
+  qa-flowkit init [options]
+  qa-flowkit update [options]
+  qa-flowkit doctor [options]
+  qa-flowkit validate-target [options]
+  qa-flowkit validate-features [options]
+  qa-flowkit sync-adapters [options]
+  qa-flowkit help [options]
+  qa-flowkit clean [options]
+
+Examples:
+  npx qa-flowkit init
+  npx qa-flowkit init --preset manual-only --interface-language es --gherkin-language es
+  npx qa-flowkit update
+  npx qa-flowkit validate-target --allow-empty --allow-missing --no-strict-doctor
+`);
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function hasFlag(args, name) {
+  return args.includes(`--${name}`);
+}
+
+function withoutCliOnlyFlags(args) {
+  return args.filter((arg) => !['--skip-doctor'].includes(arg));
+}
+
+async function assertPackagedFramework() {
+  if (!await pathExists(path.join(packagedFramework, 'scripts', 'init.mjs'))) {
+    console.error(`Packaged QA FlowKit framework is incomplete: ${packagedFramework}`);
+    process.exit(1);
+  }
+}
+
+async function assertTargetFramework(command) {
+  if (!await pathExists(path.join(targetFramework, 'scripts'))) {
+    console.error(`Missing .qa-ai framework folder. Run "qa-flowkit init" before "qa-flowkit ${command}".`);
+    process.exit(1);
+  }
+}
+
+function runNodeScript(scriptName, args = [], { allowWarnings = false } = {}) {
+  const scriptPath = path.join(targetFramework, 'scripts', scriptName);
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    cwd,
+    stdio: 'inherit',
+    shell: false
+  });
+  const status = result.status ?? 1;
+  if (status !== 0 && !allowWarnings) process.exit(status);
+  return status;
+}
+
+async function copyPackagedFramework(target) {
+  await fs.cp(packagedFramework, target, {
+    recursive: true,
+    force: false,
+    errorOnExist: true
+  });
+}
+
+async function copyIfExists(source, target) {
+  if (!await pathExists(source)) return false;
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.cp(source, target, { recursive: true, force: true });
+  return true;
+}
+
+async function restoreIfExists(source, target) {
+  if (!await pathExists(source)) return false;
+  await fs.rm(target, { recursive: true, force: true });
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.cp(source, target, { recursive: true, force: true });
+  return true;
+}
+
+async function selectedExistingAdapters() {
+  const candidates = [
+    ['claude', '.claude'],
+    ['codex', '.codex'],
+    ['opencode', '.opencode'],
+    ['cline', '.cline'],
+    ['continue', '.continue'],
+    ['aider', '.aider'],
+    ['goose', '.goose'],
+    ['gemini', 'GEMINI.md']
+  ];
+  const names = [];
+  for (const [name, relPath] of candidates) {
+    if (await pathExists(path.join(cwd, relPath))) names.push(name);
+  }
+  if (await pathExists(path.join(cwd, '.clinerules'))) names.push('cline');
+  if (await pathExists(path.join(cwd, '.aider.conf.yml'))) names.push('aider');
+  if (await pathExists(path.join(cwd, 'AGENTS.md'))) names.unshift('generic');
+  return [...new Set(names)];
+}
+
+async function init(args) {
+  await assertPackagedFramework();
+  if (await pathExists(targetFramework)) {
+    console.error('A .qa-ai framework folder already exists in this repository.');
+    console.error('Run "qa-flowkit update" to refresh it, or remove it intentionally before running init.');
+    process.exit(1);
+  }
+
+  await copyPackagedFramework(targetFramework);
+  runNodeScript('init.mjs', withoutCliOnlyFlags(args));
+  if (!hasFlag(args, 'skip-doctor')) {
+    runNodeScript('doctor.mjs', [], { allowWarnings: true });
+  }
+}
+
+async function update(args) {
+  await assertPackagedFramework();
+  await assertTargetFramework('update');
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'qa-flowkit-update-'));
+  const backupFramework = path.join(tempRoot, '.qa-ai');
+  try {
+    await copyIfExists(path.join(targetFramework, 'state'), path.join(backupFramework, 'state'));
+    await copyIfExists(path.join(targetFramework, 'config-profiles'), path.join(backupFramework, 'config-profiles'));
+
+    await fs.rm(targetFramework, { recursive: true, force: true });
+    await fs.cp(packagedFramework, targetFramework, { recursive: true, force: true });
+
+    await restoreIfExists(path.join(backupFramework, 'state'), path.join(targetFramework, 'state'));
+    await restoreIfExists(path.join(backupFramework, 'config-profiles'), path.join(targetFramework, 'config-profiles'));
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+
+  console.log('Updated .qa-ai framework from the installed QA FlowKit package.');
+  runNodeScript('init.mjs', ['--no-adapters']);
+
+  const adapters = await selectedExistingAdapters();
+  if (adapters.length > 0) {
+    const syncArgs = ['--adapters', adapters.join(',')];
+    if (hasFlag(args, 'force')) syncArgs.push('--force');
+    runNodeScript('sync-agent-adapters.mjs', syncArgs);
+  } else {
+    console.log('No existing root adapters detected; skipping adapter sync.');
+  }
+
+  if (!hasFlag(args, 'skip-doctor')) {
+    runNodeScript('doctor.mjs', [], { allowWarnings: true });
+  }
+}
+
+async function main() {
+  const [command = 'help', ...args] = process.argv.slice(2);
+  if (['-h', '--help', 'help'].includes(command)) {
+    printHelp();
+    return;
+  }
+  if (['-v', '--version', 'version'].includes(command)) {
+    const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8'));
+    console.log(packageJson.version);
+    return;
+  }
+  if (command === 'init') {
+    await init(args);
+    return;
+  }
+  if (command === 'update') {
+    await update(args);
+    return;
+  }
+  if (command in commandMap) {
+    await assertTargetFramework(command);
+    runNodeScript(commandMap[command], args);
+    return;
+  }
+
+  console.error(`Unknown command: ${command}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/docs/qa-ai/agent-compatibility.md

@@ -0,0 +1,100 @@
+# Agent Compatibility
+
+The MVP uses `AGENTS.md` as the generic compatibility layer and syncs tool-specific adapter files where useful. No adapter should become the only source of truth; every adapter points back to `AGENTS.md`, `qa-ai.config.yaml`, `.qa-ai/rules/` and `.qa-ai/workflows/`.
+
+## Syncing adapters
+
+Default init syncs only the OpenCode adapter, keeping the first setup small:
+
+```bash
+node .qa-ai/scripts/init.mjs
+```
+
+Additional adapters can be synced explicitly:
+
+```bash
+node .qa-ai/scripts/sync-agent-adapters.mjs --adapters generic,codex,claude
+node .qa-ai/scripts/sync-agent-adapters.mjs --adapter cline --adapter continue
+```
+
+Existing adapter files are skipped unless `--force` is passed.
+
+## Agent-first initialization
+
+Claude Code and OpenCode discover project slash commands from tool-specific folders in the repository root:
+
+- Claude Code: `.claude/commands/`
+- OpenCode: `.opencode/commands/`
+
+Because those folders are outside the copied `.qa-ai/` framework folder, an agent-first setup needs one bootstrap step before the first agent session:
+
+```bash
+node .qa-ai/scripts/bootstrap-agent-adapters.mjs --agents claude,opencode
+```
+
+That script copies:
+
+```text
+.claude/commands/qa-init.md
+.opencode/commands/qa-init.md
+```
+
+After copying `.qa-ai/` and running the bootstrap script, start the agent and run:
+
+```text
+/qa-init
+```
+
+The command asks for the required initialization choices, including optional QA context folder, interface language, Gherkin language, base template, requirement source, optional framework overrides and adapter selection, then runs `node .qa-ai/scripts/init.mjs`. Use `/qa-init`, not `/init`, because `/init` is a built-in command in both Claude Code and OpenCode.
+
+Advanced users may still pass flags directly:
+
+```text
+/qa-init --preset webdriverio-playwright-api --interface-language es --gherkin-language en --adapters claude,opencode
+/qa-init --qa-context qa-ai-knowledge --adapters claude,opencode
+```
+
+Interactive command behavior:
+
+- `/qa-init` asks for optional QA context, interface language, Gherkin language, base template, requirement source, optional UI/API framework overrides, adapters and overwrite behavior. When QA context is provided, it reads `.qa-ai/workflows/context-intake.md` and proposes defaults before running init.
+- `/qa-config` imports or exports reusable `qa-ai.config.yaml` profiles and asks for overwrite approval before using `--force`.
+- `/qa-full-flow` asks for requirement source, official RF ID, configured test management project/suite and whether to stop at proposals.
+- `/qa-add-tests` asks for the new requirement/RF source, official RF ID and whether to stop at proposal artifacts before adding new `.feature` files.
+- `/qa-update-tests` asks for the updated RF source, official RF ID, existing test scope and proposal/apply mode before changing current tests.
+- `/qa-automation-plan` asks which existing tests to analyze and produces automation feasibility plus implementation planning before any automation code is written.
+- `/qa-coverage` asks for RF, requirement source or repo scope and reports functional coverage across requirements, manual tests and automated tests.
+- `/qa-help` inspects artifacts and `project.qaTrack` to recommend the next workflow phase (CLI: `node .qa-ai/scripts/qa-help.mjs`).
+- `/qa-status` summarizes configuration, feature health, QA artifacts, active specialists and recommended next steps without modifying files. It should include output from `qa-help` for the next command.
+- `/qa-clean` previews cleanup first, then asks for scope and execution approval.
+- `/qa-validate-features` uses the configured feature path unless the user asks for a custom path.
+- `/qa-doctor` runs without extra input.
+
+The framework agents under `.qa-ai/agents/` are role instructions. If a tool does not expose them as callable subagents, it must read `.qa-ai/agents/README.md`, the matching phase agent and `.qa-ai/agents/specialists/active.md` directly before doing QA workflow work. When `knowledge.enabled` is true, it must also read the configured QA knowledge summary and init decisions artifacts before planning.
+
+## Supported adapters
+
+| Adapter | Generated path | Purpose |
+|---|---|---|
+| Generic | `AGENTS.md` | Cross-agent behavior and safety policy. |
+| Claude Code | `.claude/agents/`, `.claude/commands/` | Claude-specific agent and slash command documentation. |
+| Codex Desktop | `.codex/README.md`, `.codex/prompts/` | Codex onboarding prompts and local validation commands. |
+| OpenCode | `.opencode/agents/`, `.opencode/commands/` | OpenCode agent and slash command documentation. |
+| Cline | `.clinerules`, `.cline/` | Cline behavior rules and docs. |
+| Continue | `.continue/` | Review/check documentation. |
+| Aider | `.aider.conf.yml`, `.aider/` | Aider read-list and usage notes. |
+| Goose | `.goose/recipes/qa-flowkit.yaml` | Reusable Goose workflow recipe. |
+| Gemini CLI | `GEMINI.md` | Gemini CLI project context that points back to the shared QA AI instructions. |
+
+## Required behavior for every agent
+
+- Read `AGENTS.md` before acting.
+- Read `qa-ai.config.yaml` when present.
+- Read configured QA knowledge artifacts when `knowledge.enabled` is true.
+- Read `.qa-ai/rules/` before changing workflow behavior.
+- Present a plan before modifying files.
+- Do not overwrite existing files unless explicitly approved or `--force` behavior is requested.
+- Do not perform external writes in the MVP.
+- Run `node .qa-ai/scripts/doctor.mjs` for setup checks.
+- Run `node .qa-ai/scripts/validate-features.mjs` after `.feature` changes.
+- Run `node .qa-ai/scripts/clean.mjs` as a dry-run before removing generated artifacts.
+- Never pass `--include-modified` to clean unless the user explicitly wants to discard edited generated files.

package/docs/qa-ai/architecture.md

@@ -0,0 +1,130 @@
+# Architecture
+
+## High-level architecture
+
+```text
+.qa-ai/                         portable framework copied into a target repo
+  agents/                       role prompts for QA workflow steps
+    README.md                   protocol for loading role instructions
+    specialists/available/      optional specialist instructions by tool/framework
+    specialists/active.md       generated active specialist index
+  adapters/                     tool-specific adapter templates
+  presets/                      YAML starter configurations
+  rules/                        mandatory workflow rules
+  scripts/                      dependency-light Node.js utilities
+  state/                        generated local state, including init manifest
+  templates/                    generated QA artifact templates
+  workflows/                    task playbooks
+
+qa-ai.config.yaml               target repo configuration generated by init
+AGENTS.md                       generic instruction layer when generic/all adapters are requested
+GEMINI.md                       optional Gemini CLI project context when gemini adapter is requested
+qa-ai-output/                   workflow artifact folder; starter docs are optional
+qa-ai-output/qa-knowledge-summary.md optional QA context summary written by an agent
+qa-ai-output/qa-init-decisions.md    optional approved context-based init decisions
+features/                       Gherkin source of truth for test design
+tests/                          automation code when configured
+
+.claude/commands/qa-init.md     optional Claude Code bootstrap copied before init
+.opencode/commands/qa-init.md   optional OpenCode bootstrap copied before init
+```
+
+## Script responsibilities
+
+- `bootstrap-agent-adapters.mjs` copies the minimal root `/qa-init` command files for Claude Code and OpenCode after only `.qa-ai/` has been copied.
+- `init.mjs` reads a base template, generates `qa-ai.config.yaml`, records an optional `--qa-context` folder, creates configured `qa-ai-output/`, `features/` and `tests/` folders, and syncs the OpenCode adapter by default without overwriting existing files unless `--force` is passed. Starter QA artifacts and extra adapters are opt-in.
+- `doctor.mjs` validates the framework folder, required scripts/rules/templates/agents/presets/adapters, generated target files, optional QA context configuration and configured paths. `qa-ai.config.yaml` is required in initialized target repositories and optional in the framework source repository.
+- `doctor.mjs --strict` is intended for initialized target repositories and CI. It requires `qa-ai.config.yaml`, configured workflow artifacts, configured mapping/traceability files, QA knowledge artifacts when enabled and framework config files for configured automation stacks. Optional adapters remain warnings unless explicitly generated and required by the team.
+- `clean.mjs` reads `.qa-ai/state/init-manifest.json`, previews cleanup by default, and removes only tracked generated files or empty directories when `--force` is passed.
+- `validate-features.mjs` parses configured `.feature` files for one Feature, one Scenario, acceptance criteria, required tag values, language directives, RF IDs and duplicate explicit test case IDs.
+- `validate-traceability.mjs` checks that feature RF/test identifiers are represented in the configured traceability matrix, validates the Markdown table shape and detects duplicate test case or feature-file rows.
+- `validate-sync-plan.mjs` checks that test-management sync plans remain proposal-first, mention approval, cover feature identifiers, validate Markdown table shape, detect duplicate plan IDs and validate the optional test-management mapping file shape.
+- `validate-active-specialists.mjs` checks that `.qa-ai/agents/specialists/active.md` matches the configured tools/frameworks.
+- `smoke-test.mjs` runs native Node smoke checks for init, config profiles, selected adapters, no-overwrite behavior and unsafe path rejection.
+- `sync-agent-adapters.mjs` copies selected adapter templates into target tool paths.
+
+Supported sync adapters are `generic`, `claude`, `codex`, `opencode`, `cline`, `continue`, `aider`, `goose` and `gemini`.
+
+All scripts use native Node.js APIs and are intended for Node.js 20+.
+
+Agent behavior can be customized through phase agents, specialists, shared rules and adapter templates. See [Customizing Agents](customizing-agents.md) for the recommended customization workflow and safety checklist.
+
+## Bootstrap model
+
+The framework supports two initialization modes:
+
+- Node-first: copy `.qa-ai/`, then run `node .qa-ai/scripts/init.mjs`.
+- Agent-first: copy `.qa-ai/`, run `node .qa-ai/scripts/bootstrap-agent-adapters.mjs`, then run `/qa-init` inside Claude Code or OpenCode.
+
+Agent-first bootstrap files live outside `.qa-ai/` because Claude Code and OpenCode discover slash commands from root-level tool folders. The bootstrap script copies those files from `.qa-ai/adapters/` into `.claude/commands/` and `.opencode/commands/`. The `/qa-init` command delegates to the same `init.mjs` script, so both modes produce the same target repository structure.
+
+## QA context model
+
+QA context is optional and agent-assisted. A user can provide one repository-local folder with team QA working-practice documentation:
+
+```bash
+node .qa-ai/scripts/init.mjs --qa-context qa-ai-knowledge
+```
+
+`init.mjs` validates that the folder is inside the repository, records it under `knowledge.sourcePath`, and sets `knowledge.enabled: true`. It does not interpret the documents. Claude Code, OpenCode or another agent reads `.qa-ai/workflows/context-intake.md` and `.qa-ai/agents/qa-context-intake-agent.md`, proposes init defaults, asks for approval and writes local summary/decision artifacts.
+
+## Source of truth strategy
+
+- Requirements source: configured source from `qa-ai.config.yaml`.
+- QA working-practice source: optional `knowledge.sourcePath`, summarized into `knowledge.summaryPath` and `knowledge.decisionsPath`.
+- Interface language: configured by `project.interfaceLanguage` for generated QA artifact headings and user-facing workflow text.
+- Complementary sources: PRD, RF markdown, configured documentation tools and attachments.
+- Test design source: versioned `.feature` files in the repository.
+- Test management: configured tool for execution/reporting, not as the only source of truth.
+- Traceability: `qa-ai-output/traceability-matrix.md`.
+
+## Agent workflow
+
+```text
+qa-workflow-orchestrator
+  -> requirements-intake-agent
+  -> requirements-normalization-agent
+  -> test management coverage agent
+  -> gherkin-test-design-agent
+  -> test management sync agent
+  -> automation-feasibility-agent
+  -> UI automation implementation agent
+  -> api-testing-agent
+  -> issue task agent
+  -> pr-agent
+```
+
+## Safety model
+
+The Early Product release uses prompt rules, local validation scripts, smoke tests and GitHub CI. Future versions may add full parser dependencies, strict target-repo CI templates and MCP tools.
+
+Safety principles:
+
+- Read operations are allowed.
+- Local writes require a plan.
+- Existing files are not overwritten by default.
+- Configured paths must stay inside the repository.
+- External writes require explicit approval and are not performed by the MVP scripts.
+- Updates to existing tests require approval.
+- Deletes are blocked by default.
+- Cleanup is dry-run by default and manifest-based.
+- Modified generated files are protected by hash checks unless `--include-modified` is explicitly passed.
+- Secrets are never stored in `.qa-ai/` or generated repository files.
+
+## Init manifest
+
+The init manifest is generated in the target repository:
+
+```text
+.qa-ai/state/init-manifest.json
+```
+
+Each entry stores:
+
+- Repository-relative path.
+- Entry type: `file` or `dir`.
+- Category: `generated` or `adapter`.
+- Source command or adapter.
+- SHA-256 hash for files.
+
+The manifest exists to make cleanup auditable. It intentionally records only paths created or overwritten by framework scripts. Existing files skipped by safe writes are not tracked as generated ownership.