@structor-dev/cli 0.1.0

package/template/ai/templates/fixtures/issues/valid-ready.md.tpl

@@ -0,0 +1,105 @@
+---
+id: HARNESS-FIXTURE-001
+status: Ready for Agent
+risk: medium
+autonomy: pr_ready
+model_policy: standard
+repos:
+  - {{HARNESS_REPO_NAME}}
+allowed_paths:
+  - ai/HARNESS.md
+forbidden_paths:
+  - workspace/**
+requires_human_approval: false
+---
+
+# Valid Ready Fixture
+
+## Summary
+
+Update harness guidance without touching protected surfaces.
+
+## Context
+
+This fixture proves that a concrete issue brief can pass validation.
+
+## Goals
+
+- Keep the fixture mechanically valid.
+
+## Non-Goals
+
+- Do not change consumer repos.
+
+## Scope
+
+### In Scope
+
+- `ai/HARNESS.md`
+
+### Out of Scope
+
+- `workspace/**`
+
+## Path Contract
+
+### Allowed Paths
+
+- `ai/HARNESS.md`
+
+### Forbidden Paths
+
+- `workspace/**`
+
+## Requirements
+
+- Preserve harness-only scope.
+
+## Bootstrap Requirements
+
+- Read `ai/HUB.md`.
+
+## Proposed Approach
+
+- Make a narrow documentation update.
+
+## Agent Execution Protocol
+
+- Stay inside allowed paths.
+
+## Success Criteria
+
+- Governance validation passes.
+
+## Validation
+
+- `node scripts/validate-governance.mjs`
+
+## Validation Evidence Required
+
+- Report command outcomes.
+
+## Risk and Autonomy
+
+Protected surfaces require current human approval. `auto_merge` is future-facing
+metadata and does not imply current execution by this repo.
+
+## Review Routing
+
+- Use `ai/skills/review-governance-drift.md`.
+
+## Dependencies
+
+- None.
+
+## Rollback / Recovery
+
+- Revert the documentation change.
+
+## Open Questions
+
+- None.
+
+## Notes for the Agent
+
+No protected surface is in scope.

package/template/ai/templates/issue-template.md.tpl

@@ -0,0 +1,107 @@
+---
+id: <ISSUE-ID>
+status: Backlog
+risk: medium
+autonomy: pr_ready
+model_policy: standard
+repos:
+  - {{HARNESS_REPO_NAME}}
+allowed_paths:
+  - <path-or-glob>
+forbidden_paths:
+  - <path-or-glob>
+requires_human_approval: false
+---
+
+# <Issue Title>
+
+## Summary
+
+Describe the work in one short paragraph.
+
+## Context
+
+Explain why the change is needed and what existing behavior matters.
+
+## Goals
+
+- Describe the intended outcomes.
+
+## Non-Goals
+
+- Describe what must remain out of scope.
+
+## Scope
+
+### In Scope
+
+- List allowed surfaces.
+
+### Out of Scope
+
+- List forbidden surfaces.
+
+## Path Contract
+
+### Allowed Paths
+
+- `<path-or-glob>`
+
+### Forbidden Paths
+
+- `<path-or-glob>`
+
+## Requirements
+
+- State concrete functional and technical requirements.
+
+## Bootstrap Requirements
+
+- State what the agent must read or check before editing.
+
+## Proposed Approach
+
+- Describe the implementation sequence.
+
+## Agent Execution Protocol
+
+- Keep changes scoped to allowed paths.
+- Stop and ask before protected surfaces or remote mutations.
+
+## Success Criteria
+
+- State the observable finish line.
+
+## Validation
+
+- `node scripts/validate-governance.mjs`
+
+## Validation Evidence Required
+
+- List commands and outcomes in the final report.
+
+## Risk and Autonomy
+
+Protected surfaces require current human approval. `auto_merge` is future-facing
+metadata and does not imply current execution by this repo.
+
+## Review Routing
+
+- Route review to the relevant harness docs and skills.
+
+## Dependencies
+
+- List dependencies or say none.
+
+## Rollback / Recovery
+
+- Describe how to revert the change safely.
+
+## Open Questions
+
+- List unresolved questions or say none.
+
+## Notes for the Agent
+
+Keep Markdown, JSON, and YAML sources canonical. Generated views are review
+artifacts.

package/template/ai/templates/task-brief-template.md.tpl

@@ -0,0 +1,185 @@
+---
+id: TASK-ID
+status: backlog
+risk: medium
+autonomy: pr_ready
+model_policy: standard
+model: runtime-selected
+repos: []
+allowed_paths: []
+forbidden_paths: []
+requires_human_approval: false
+---
+
+# Title
+
+## Summary
+
+What needs to change and why.
+
+## Context
+
+Relevant harness docs, contracts, and repo state.
+
+## Goals
+
+- Goal 1
+
+## Non-Goals
+
+- Non-goal 1
+
+## Scope
+
+### In Scope
+
+- In scope item
+
+### Out of Scope
+
+- Out of scope item
+
+### Repos Affected
+
+- Repo name
+
+## Path Contract
+
+### Allowed Paths
+
+- Path the agent may edit
+
+### Forbidden Paths
+
+- Path the agent must not touch
+
+### Protected Contracts
+
+- Existing public APIs, CLI commands, validation commands, and generated
+  artifact shapes must remain backward compatible unless explicitly stated.
+
+## Requirements
+
+### Functional Requirements
+
+- Functional requirement
+
+### Technical Requirements
+
+- Technical requirement
+
+### UX / Content Requirements
+
+- UX or content requirement, if applicable
+
+### Data / API Requirements
+
+- Data or API requirement, if applicable
+
+## Bootstrap Requirements
+
+Before implementation, the agent must:
+
+- Read the relevant repo entrypoint and routed harness docs.
+- Identify canonical repo names and ownership boundaries.
+- Identify validation commands and safe dry-run checks.
+- Report missing, stale, or contradictory harness files before editing.
+
+Expected evidence:
+
+- Context files read.
+- Bootstrap or path-contract check output, if available.
+- Any mismatch or ambiguity found.
+
+## Proposed Approach
+
+- Preferred solution
+- Alternatives considered
+- Key trade-offs
+
+## Agent Execution Protocol
+
+Before changing files, the agent must state:
+
+- Files expected to change.
+- Contracts expected to remain unchanged.
+- Validation commands it will run.
+- Risks or ambiguities found.
+
+The agent must not proceed if the plan conflicts with the Path Contract, risk
+and autonomy, or Open Questions sections.
+
+## Success Criteria
+
+- Observable end state
+- Acceptance criteria
+- Definition of done
+
+## Validation
+
+- Command or check 1
+
+## Validation Evidence Required
+
+- Commands run
+- Exit codes
+- Relevant output excerpts
+- Failures or skipped checks with reasons
+- Files changed
+- Manual checks performed
+- Known residual risks
+
+## Risk and Autonomy
+
+- Risk: `low` / `medium` / `high`
+- Autonomy: `report_only` / `pr_ready` / `auto_merge`
+- Model policy: `cheap` / `standard` / `reasoning` / `frontier` /
+  `review_only`
+- Model: keep `runtime-selected` unless the task owner explicitly requires a
+  provider-specific model. Choose the active runtime's current appropriate
+  model: cheaper models for low-risk mechanical work, stronger reasoning
+  models for cross-file implementation, and frontier models for high-risk,
+  architecturally heavy, or cross-repo work.
+- Human approvals required
+- Protected surfaces touched, if any
+- Rollout or rollback notes
+- `auto_merge` is future-facing metadata only unless a separate runner is
+  explicitly authorized.
+
+## Review Routing
+
+Required reviewers:
+
+- Architecture reviewer: yes/no
+- Security reviewer: yes/no
+- UX/content reviewer: yes/no
+- Cross-repo consistency reviewer: yes/no
+
+Reviewer focus:
+
+- What reviewers should inspect.
+- What reviewers can ignore.
+
+## Dependencies
+
+- Upstream dependencies
+- Downstream dependencies
+- External blockers
+
+## Rollback / Recovery
+
+How to recover if validation fails.
+
+## Open Questions
+
+- None yet.
+
+## Notes for the Agent
+
+- Ask for clarification before changing files if anything is ambiguous and the
+  brief does not authorize a safe default.
+- Keep the change as small as possible.
+- Prefer existing patterns, contracts, commands, and repo conventions.
+- Do not widen scope to nearby cleanup.
+- Do not make speculative architecture changes.
+- Do not silently skip validation.

package/template/ai/workspace/LOCAL-STACK.md.tpl

@@ -0,0 +1,21 @@
+# Local Stack
+
+This document records stable local assumptions for `{{PROJECT_NAME}}`.
+
+## Harness
+
+- Primary validation: `node scripts/validate-governance.mjs`
+- Workspace layout check: `node scripts/check-workspace.mjs`
+- Workspace bootstrap: `node scripts/bootstrap-workspace.mjs`
+
+## Consumers
+
+Consumer validation commands are configured in `harness.config.json` and owned
+by the consumer repos.
+
+{{CONSUMER_REPOS_LIST}}
+
+## Rule
+
+Do not require external services, production data, or remote mutations for
+harness validation.

package/template/ai/workspace/REPOS.md.tpl

@@ -0,0 +1,19 @@
+# Workspace Repos
+
+This workspace uses `{{HARNESS_REPO_NAME}}` as the harness repo.
+
+## Harness
+
+- `{{HARNESS_REPO_NAME}}`: policy, routing, contracts, review templates, generated views, and validation scripts.
+
+## Consumers
+
+{{CONSUMER_REPOS_LIST}}
+
+Consumer repos own product implementation, runtime behavior, app dependencies,
+and product-specific validation.
+
+## Boundary
+
+The harness may describe repo ownership and expected checks. It must not become
+the implementation source of truth for consumer applications.

package/template/ai/workspace/SESSION-BOOTSTRAP.md.tpl

@@ -0,0 +1,27 @@
+# Session Bootstrap
+
+Before editing, confirm the current checkout and task boundary.
+
+Use `ai/workspace/REPOS.md` when the repo owner or workspace role is unclear.
+
+## Checks
+
+1. Run `git status --short --branch`.
+2. Confirm the target repo owns the files being edited.
+3. Read `ai/context.md` and route through `ai/HUB.md`.
+4. Check whether the task touches protected surfaces.
+5. Choose validation from `ai/workspace/TEST-STRATEGY.md`.
+
+## Worktrees
+
+For Codex worktrees or copied consumer checkouts, run:
+
+```bash
+node scripts/check-worktrees.mjs --include-canonical
+```
+
+If a consumer checkout has stale harness pointers, repair it with:
+
+```bash
+node scripts/bootstrap-codex-worktree.mjs <checkout-path>
+```

package/template/ai/workspace/SYSTEM-MAP.md.tpl

@@ -0,0 +1,19 @@
+# System Map
+
+`{{PROJECT_NAME}}` is organized around a separate harness repo and one or more
+consumer repos.
+
+## Relationship
+
+- Harness repo: `{{HARNESS_REPO_NAME}}`
+- Consumer repos: {{CONSUMER_REPO_NAMES_JSON}}
+
+The harness defines shared engineering policy and review expectations. Consumer
+repos define application architecture, runtime commands, data models, and
+deployment behavior.
+
+## Routing
+
+Start from `ai/HUB.md`, then load only the docs that match the task. Use
+`ai/workspace/REPOS.md` for repo ownership and `ai/workspace/TEST-STRATEGY.md`
+for validation ownership.

package/template/ai/workspace/TEST-STRATEGY.md.tpl

@@ -0,0 +1,22 @@
+# Test Strategy
+
+## Harness-Owned Checks
+
+- `node scripts/check-template-governance.mjs`
+- `node scripts/check-task-template.mjs`
+- `node scripts/check-knowledge-manifest.mjs`
+- `node scripts/check-plans.mjs`
+- `node scripts/check-review-skills.mjs`
+- `node scripts/check-contract-manifests.mjs`
+- `node scripts/check-html-views.mjs`
+- `node scripts/validate-governance.mjs`
+
+## Consumer-Owned Checks
+
+Consumer repos own app-specific install, lint, test, build, browser, database,
+and service checks.
+
+## Evidence
+
+Report exactly which commands ran, from which repo, and whether each passed,
+failed, or was skipped with a reason.

package/template/consumer/.claude/CLAUDE.md.tpl

@@ -0,0 +1,14 @@
+# {{CONSUMER_NAME}} Claude Project Memory
+
+Use this file with the root `../CLAUDE.md` entrypoint when Claude Code starts
+inside this repository or a worktree.
+
+@../CLAUDE.md
+
+Read the harness first through the root Claude guide.
+
+The {{PROJECT_NAME}} engineering harness is the policy source of truth. If this
+repo is checked out as a worktree, also look for workspace-level guidance in
+the parent folders before relying only on local files.
+
+Keep this pointer short.

package/template/consumer/AGENTS.md.tpl

@@ -0,0 +1,23 @@
+# {{CONSUMER_NAME}} Agent Guide
+
+This consumer repository is governed by the {{PROJECT_NAME}} engineering
+harness.
+
+## Harness
+
+Read the harness first:
+
+1. `{{HARNESS_RELATIVE_PATH}}/AGENTS.md`
+2. `{{HARNESS_RELATIVE_PATH}}/ai/AGENTS.md`
+3. `{{HARNESS_RELATIVE_PATH}}/ai/HUB.md`
+4. `{{HARNESS_RELATIVE_PATH}}/ai/context.md`
+
+## Local Purpose
+
+{{CONSUMER_PURPOSE}}
+
+## Local Validation
+
+{{CONSUMER_VALIDATION_LIST}}
+
+Keep this file short. Canonical policy belongs in the harness.

package/template/consumer/CLAUDE.md.tpl

@@ -0,0 +1,15 @@
+# {{CONSUMER_NAME}} Claude Guide
+
+This consumer repository is governed by the {{PROJECT_NAME}} engineering
+harness.
+
+Read:
+
+1. `{{HARNESS_RELATIVE_PATH}}/CLAUDE.md`
+2. `{{HARNESS_RELATIVE_PATH}}/ai/AGENTS.md`
+3. `{{HARNESS_RELATIVE_PATH}}/ai/HUB.md`
+4. `{{HARNESS_RELATIVE_PATH}}/ai/context.md`
+
+Local purpose: {{CONSUMER_PURPOSE}}
+
+Keep this file short. Canonical policy belongs in the harness.

package/template/scripts/bootstrap-codex-worktree.mjs.tpl

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  buildRepairPlan,
+  formatInspection,
+  gitMetadataForPath,
+  inspectCheckout,
+  writeRepairPlan,
+} from "./lib/worktree-bootstrap.mjs";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const targetArg = args.find((arg) => !arg.startsWith("--"));
+
+if (!targetArg) {
+  console.error("Usage: node scripts/bootstrap-codex-worktree.mjs <worktree-path> [--dry-run]");
+  process.exit(1);
+}
+
+const targetPath = path.resolve(targetArg);
+const metadata = await gitMetadataForPath(targetPath);
+if (!metadata.gitRoot) {
+  console.error(`Refusing to repair ${targetPath}: target is not inside a git checkout.`);
+  process.exit(1);
+}
+
+const inspection = await inspectCheckout({ targetPath: metadata.gitRoot, harnessRoot: repoRoot });
+console.log(formatInspection(inspection, { harnessRoot: repoRoot }));
+
+if (inspection.valid) {
+  console.log("Worktree bootstrap is already valid.");
+  process.exit(0);
+}
+
+const repairPlan = buildRepairPlan({ inspection, harnessRoot: repoRoot });
+if (!repairPlan.repairable) {
+  console.error(`Refusing to repair ${inspection.targetPath}: ${repairPlan.reason}`);
+  process.exit(1);
+}
+
+console.log("Files to write:");
+for (const write of repairPlan.writes) console.log(`- ${write.targetPath}`);
+
+if (dryRun) {
+  console.log("Dry run complete. No files were written.");
+} else {
+  await writeRepairPlan(repairPlan);
+  console.log("Worktree bootstrap repair complete.");
+}