@harness-forge/cli 0.1.0

package/docs/commands.md

@@ -0,0 +1,202 @@
+# Commands
+
+Harness Forge exposes install, catalog, repo-intelligence, flow, and
+maintenance commands through the `hforge` CLI.
+
+## Interactive front door
+
+- `hforge` with no arguments opens guided onboarding in an interactive
+  terminal when the repo does not yet contain `.hforge/`
+- `hforge` with no arguments opens the project hub when the repo already has a
+  Harness Forge runtime
+- `hforge init --interactive` forces the guided onboarding flow
+- `hforge init --root <repo> --agent codex --setup-profile recommended --yes`
+  is the direct non-interactive equivalent
+- `hforge init --root <repo> --agent codex --dry-run` previews the same setup
+  plan without writing files
+
+## Core command groups
+
+- `install` for initial target bootstrap
+- `init` for deterministic first-run runtime initialization
+- `bootstrap` for autodiscovery-driven installation into the current repo
+- `shell setup` and `shell status` for optional PATH integration without forcing a global npm install
+- `status` for current workspace state
+- `refresh` for shared runtime regeneration after install or maintenance work
+- `task` for task-runtime inspection
+- `pack` for task-pack inspection
+- `review` for runtime and decision-health summaries
+- `export` for operator-facing runtime handoff bundles
+- `commands` for the agent-visible CLI and npm command catalog
+- `catalog` for bundles, targets, profiles, and recommendations
+- `recommend` for repo-intelligence and evidence-backed setup guidance
+- `scan`, `cartograph`, `classify-boundaries`, and `synthesize-instructions`
+  for self-service repo analysis and target-aware instruction planning
+- `target inspect`, `target list`, and `capabilities` for Codex, Claude Code,
+  Cursor, and OpenCode support inspection
+- `template validate` and `template suggest` for template and workflow flows
+- `flow status` for recoverable Speckit state
+- `recursive plan`, `recursive inspect`, `recursive adr`, `recursive resume`,
+  `recursive finalize`, `recursive compact`, and `recursive repl` for optional
+  recursive-runtime operation on difficult work
+- `observability summarize` and `observability report` for local metrics and
+  effectiveness review
+- `parallel plan`, `parallel status`, and `parallel merge-check` for shard
+  planning and merge safety
+- `doctor`, `audit`, `sync`, `diff-install`, `upgrade-surface`, and `prune`
+  for lifecycle diagnostics
+- `backup`, `repair`, `restore`, `upgrade`, `migrate`, and `uninstall` for the
+  broader maintenance surface
+
+## Common examples
+
+Use bare `hforge` after `shell setup`, after a global install, or by replacing
+it with the workspace-local launcher under `.hforge/generated/bin/`.
+
+```bash
+npx @harness-forge/cli
+npx @harness-forge/cli shell setup --yes
+npx @harness-forge/cli init --root . --agent codex --setup-profile recommended --yes
+npx @harness-forge/cli init --root . --agent codex --dry-run
+npx @harness-forge/cli bootstrap --root . --yes
+hforge shell status --json
+hforge init --root . --json
+hforge bootstrap --root . --yes
+hforge refresh --root . --json
+hforge task list --root . --json
+hforge task inspect TASK-001 --root . --json
+hforge pack inspect TASK-001 --root . --json
+hforge review --root . --json
+hforge export --root . --json
+hforge commands --json
+hforge catalog --json
+hforge recommend tests/fixtures/benchmarks/typescript-web-app --json
+hforge scan . --json
+hforge cartograph . --json
+hforge classify-boundaries . --json
+hforge synthesize-instructions . --target codex --json
+hforge target inspect codex --json
+hforge capabilities --target claude-code --json
+hforge template validate --json
+hforge template suggest bugfix
+hforge flow status --json
+hforge recursive plan "investigate billing retry behavior" --task-id TASK-001 --json
+hforge recursive inspect RS-123 --json
+hforge observability summarize --json
+hforge observability report . --json
+hforge parallel plan specs/005-enhanced-skills-embedding/tasks.md --json
+hforge parallel status --json
+hforge parallel merge-check --json
+hforge doctor --json
+hforge audit --json
+hforge diff-install --json
+hforge sync --json
+hforge upgrade-surface --json
+hforge prune --json
+```
+
+## Maintainer source-checkout examples
+
+When developing Harness Forge itself from a source checkout, the equivalent
+repo-local entrypoint remains:
+
+```bash
+node dist/cli/index.js --help
+node dist/cli/index.js recommend . --json
+node dist/cli/index.js cartograph . --json
+node dist/cli/index.js target inspect codex --json
+```
+
+## Script-level validation and reporting
+
+The published package supports direct `npx` execution without a manual local
+build. Git-sourced installs use npm `prepare` to build automatically during
+installation.
+
+```bash
+npm run commands:catalog
+npm run smoke:cli
+npm run bootstrap:current
+npm run recommend:current
+npm run cartograph:current
+npm run instructions:codex
+npm run target:codex
+npm run target:claude-code
+npm run target:opencode
+npm run validate:release
+npm run validate:local
+npm run validate:compatibility
+npm run validate:skill-depth
+npm run validate:framework-coverage
+npm run validate:doc-command-alignment
+npm run validate:runtime-consistency
+npm run observability:summary
+npm run knowledge:coverage
+npm run knowledge:drift
+npm run flow:status
+npm run observability:report
+```
+
+## Operational docs
+
+- `commands/plan.md`
+- `commands/test.md`
+- `docs/maintenance-lifecycle.md`
+- `docs/flow-orchestration.md`
+
+## Useful self-service workflows
+
+### Understand a repo before installing
+
+```bash
+hforge recommend . --json
+hforge cartograph . --json
+hforge classify-boundaries . --json
+```
+
+### Generate target-aware guidance for your runtime
+
+```bash
+hforge target inspect codex --json
+hforge target inspect claude-code --json
+hforge target inspect opencode --json
+hforge synthesize-instructions . --target codex --write --json
+```
+
+### Review local effectiveness and parallel readiness
+
+```bash
+hforge observability summarize --json
+hforge observability report . --json
+hforge parallel plan specs/005-enhanced-skills-embedding/tasks.md --json
+hforge parallel status --json
+hforge parallel merge-check --json
+```
+
+### Escalate difficult work into a recursive runtime session
+
+```bash
+hforge recursive plan "investigate billing retry behavior across the route and service" --task-id TASK-001 --json
+hforge recursive inspect RS-123 --json
+hforge recursive compact RS-123 --json
+hforge recursive finalize RS-123 --json
+```
+
+The `recursive plan` entrypoint writes a durable draft session under
+`.hforge/runtime/recursive/sessions/`, reports the session id, the active
+budget policy, the seeded handles, and the current promotion state, and leaves
+ordinary non-recursive task/runtime flows untouched.
+
+### Inspect the hidden runtime after initialization
+
+```bash
+hforge
+hforge status --root . --json
+hforge refresh --root . --json
+hforge task list --root . --json
+hforge review --root . --json
+hforge export --root . --json
+```
+
+When the repo already contains `.hforge/`, the no-argument `hforge` entrypoint
+acts like a lightweight project hub and routes to these common workflows.

package/docs/content-architecture.md

@@ -0,0 +1,3 @@
+# Content architecture
+
+The install pipeline now separates package root (manifests, templates, runtime assets) from workspace root (the user repository that receives installed files).

package/docs/flow-orchestration/parallel-execution.md

@@ -0,0 +1,7 @@
+# Parallel Execution
+
+Parallel execution builds on the existing flow orchestration surface instead of
+creating a separate recovery silo.
+
+Use the runtime scripts to create a plan, inspect shard status, and evaluate
+merge readiness before combining work.

package/docs/flow-orchestration.md

@@ -0,0 +1,63 @@
+# Flow Orchestration
+
+Speckit flow state is the re-entry surface for spec-driven delivery. It turns a
+folder of artifacts into a recoverable working state with an explicit stage,
+last artifact, blockers, and next action.
+
+## Runtime commands
+
+```bash
+node scripts/runtime/flow-status.mjs --json
+hforge flow status --json
+hforge parallel plan specs/<feature>/tasks.md --json
+hforge parallel status --json
+hforge parallel merge-check --json
+```
+
+## Canonical state file
+
+- `.specify/state/flow-state.json`
+
+## Required state fields
+
+- `featureId`
+- `currentStage`
+- `status`
+- `lastArtifact`
+- `nextAction`
+- `updatedAt`
+
+## Supported stages
+
+| Stage | Meaning | Primary artifacts |
+| --- | --- | --- |
+| `clarify` | The work is still being framed. | `spec.md`, checklist answers |
+| `specify` | The feature has a spec but not yet a technical plan. | `spec.md` |
+| `plan` | Design decisions and contracts are being established. | `plan.md`, `research.md`, `contracts/` |
+| `tasks` | The execution backlog is being generated or reviewed. | `tasks.md` |
+| `implement` | Tasks are actively being completed. | code changes, tests, docs |
+| `validate` | Implementation is complete and end-to-end validation is underway. | release output, quickstart checks |
+
+## Artifact lineage
+
+The runtime should make it easy to trace:
+
+`spec -> plan -> research/contracts -> tasks -> implementation -> validation`
+
+Lineage should point back to real files in `specs/<feature-id>/` instead of
+guessing from timestamps or chat history.
+
+## Recovery rule
+
+If a session is interrupted, inspect `.specify/state/` first. Agents should
+resume from the last known stage and artifact instead of re-deriving state from
+partial memory.
+
+## Issue-export convention
+
+When tasks are exported into issues or tracked externally:
+
+- preserve the originating feature id
+- preserve task ids and dependencies
+- keep the current stage and next action visible
+- reference the same artifact lineage recorded in flow state

package/docs/generated-artifacts.md

@@ -0,0 +1,129 @@
+# Generated Artifacts
+
+Interactive onboarding does not create a separate visible artifact family of
+its own. It plans and writes the same hidden `.hforge/` runtime, state, and
+generated surfaces that the direct CLI path uses, but it now adds a guided
+review-before-write step and a completion summary around those artifacts.
+
+Harness Forge allows generated derivative files, but only when provenance is
+explicit and recoverable.
+
+## Required provenance
+
+- mark generated markdown with `generated: true`
+- include `canonical_source` in metadata
+- keep the canonical authored or imported source in the repository
+
+## Hidden AI layer families
+
+- `.hforge/library/skills/` is the canonical hidden installed skill library
+- `.hforge/library/rules/` is the canonical hidden installed rules surface
+- `.hforge/library/knowledge/` is the canonical hidden installed knowledge-pack surface
+- `.hforge/templates/` is the canonical hidden installed task and workflow template surface
+- `.hforge/runtime/` remains the generated shared runtime and repo-intelligence layer
+- `.hforge/state/` and `.hforge/generated/` remain install and helper state surfaces
+- `.hforge/agent-manifest.json` is the generated machine-readable agent contract for custom runtimes
+
+## Current generated or derived surfaces
+
+- `manifests/catalog/compatibility-matrix.json` is generated from targets,
+  profiles, hooks, workflows, skills, languages, and framework metadata
+- `manifests/catalog/seeded-knowledge-files.json` is generated from the seeded
+  archive mapping
+- `manifests/catalog/engineering-assistant-import-inventory.json` is authored
+  governance data for the engineering-assistant port, not a generated artifact
+- `docs/authoring/engineering-assistant-port.md` is curated provenance for the
+  engineering-assistant import, not a runtime skill entrypoint
+- `manifests/catalog/enhanced-skill-import-inventory.json` is authored
+  governance data for imported skill packs, not a generated artifact
+- `docs/authoring/enhanced-skill-import.md` is curated provenance for imported
+  skill packs, not a runtime skill entrypoint
+- `.hforge/runtime/index.json` is generated workspace runtime state that
+  records the shared runtime surfaces, installed targets, target bridges, runtime schema version, and package version selected for an
+  installed workspace
+- `.hforge/runtime/README.md` is generated workspace documentation that
+  explains how installed discovery bridges route into the shared runtime
+- `.hforge/agent-manifest.json` is generated workspace metadata that tells
+  custom agents which files are bridges, which roots are canonical hidden AI
+  content, which launchers are available locally, and which command catalog to
+  trust
+- `.hforge/runtime/repo/repo-map.json` is generated baseline repo cartography
+  for the installed workspace runtime
+- `.hforge/runtime/repo/recommendations.json` is generated recommendation output
+  derived from repo intelligence
+- `.hforge/runtime/repo/target-support.json` is generated target support
+  summary for the installed workspace runtime
+- `.hforge/runtime/repo/instruction-plan.json` is generated target-aware
+  instruction planning output for installed runtimes
+- `.hforge/runtime/repo/scan-summary.json` is generated stack and validation
+  signal output from the runtime scan
+- `.hforge/runtime/findings/validation-gaps.json` is generated validation-gap
+  output for the installed workspace runtime
+- `.hforge/runtime/findings/risk-signals.json` is generated risk-signal output
+  for the installed workspace runtime
+- `.hforge/runtime/tasks/TASK-XXX/file-interest.json` is generated ranked
+  task-aware file context for an active task
+- `.hforge/runtime/tasks/TASK-XXX/impact-analysis.json` is generated blast-radius
+  analysis derived from selected task context, including architecture-significance
+  assessment metadata
+- `.hforge/runtime/tasks/TASK-XXX/task-pack.json` is the structured summary for
+  a canonical runtime task folder, including decision refs and ASR coverage when
+  the task is architecture-significant
+- `.hforge/runtime/tasks/TASK-XXX/recursive-session.json` links an ordinary
+  task runtime folder to the latest recursive session created for hard work on
+  that task
+- `.hforge/runtime/decisions/ASR-*.json` and companion markdown files are
+  generated architecture-significant requirement records captured from task-time
+  runtime analysis
+- `.hforge/runtime/decisions/index.json` is the machine-readable runtime index
+  for decision records written into the hidden AI layer
+- `.hforge/runtime/decisions/coverage-summary.json` is reserved for runtime
+  decision-coverage maintenance summaries
+- `.hforge/runtime/cache/working-memory.json` is compact runtime cache state for
+  resumable active work
+- `.hforge/templates/runtime/registry.json` is the canonical hidden runtime
+  template registry for task-time artifacts
+- `.hforge/runtime/recursive/sessions/RS-XXX/session.json` is the durable draft
+  or active recursive session identity, budget, handles, and tool surface
+- `.hforge/runtime/recursive/sessions/RS-XXX/memory.json` is compact
+  recursive-session working memory for the current investigation
+- `.hforge/runtime/recursive/sessions/RS-XXX/trace.jsonl` is append-only
+  recursive trace output for operator auditability
+- `.hforge/runtime/recursive/sessions/RS-XXX/summary.json` is the deterministic
+  recursive handoff summary, even while the session is still draft
+- `.specify/state/flow-state.json` is runtime state, not an authored source
+- `.hforge/state/install-state.json` is generated install-state and runtime-version metadata, not authored product content
+- `.hforge/state/post-install-guidance.txt` is generated operator guidance for init, install, and recovery flows
+
+## Artifact lineage rules
+
+- every flow record should point back to `spec.md`, `plan.md`, `contracts/`,
+  and `tasks.md` when they exist
+- generated compatibility and knowledge reports must remain traceable to the
+  authored manifests they summarize
+- generated shared-runtime state must remain traceable to install planning,
+  target adapter metadata, and workspace-selected bundles
+- generated shared-runtime baseline artifacts must remain traceable to
+  recommendation, scan, cartography, and instruction-synthesis inputs
+- generated decision records must remain traceable to task packs, impact
+  analysis, and the architecture-significance assessment that caused them
+- generated recursive-session artifacts must remain traceable to the linked task
+  runtime folder when a task id is present
+- release validation should fail when a generated artifact points to a missing
+  source
+
+## Issue-export convention
+
+When implementation tasks are exported to issues:
+
+- keep the originating feature id in the issue body or metadata
+- preserve task ids from `tasks.md`
+- include the current flow stage and the next recommended action
+- keep the export reproducible from the canonical task list
+
+## Drift policy
+
+- generated derivatives must be reproducible from canonical sources
+- authored summaries must not be silently overwritten by import or generation
+- runtime state can be refreshed, but authored docs and manifests require
+  explicit review

package/docs/hooks/catalog.md

@@ -0,0 +1,44 @@
+# Hook Catalog
+
+Harness Forge treats hooks as typed runtime policies with explicit support,
+failure behavior, and observability fields. The machine-readable source of
+truth lives in `manifests/hooks/index.json` and
+`schemas/hooks/hook.schema.json`.
+
+## Hook families
+
+| Hook | Stage | Mode | Failure policy | Codex | Claude Code | Cursor | OpenCode |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `quality-gate.release-smoke` | `validate` | `blocking` | `stop-and-report` | full | full | partial | partial |
+| `checkpoint.flow-summary` | `implement` | `advisory` | `warn-and-continue` | full | full | emulated | emulated |
+| `scan.repo-intelligence` | `specify` | `advisory` | `warn-and-continue` | full | full | partial | partial |
+
+## Typed hook contract
+
+Every shipped hook manifest must declare:
+
+- `family`, `triggerStage`, and `mode`
+- execution ordering and failure semantics
+- required inputs and expected outputs
+- workflow families plus fallback guidance for runtimes without native parity
+- target compatibility per harness
+- observability fields that explain what happened
+
+## Support model
+
+- Codex: hook manifests are first-class, but execution remains
+  documentation-driven because Codex does not expose the same native hook
+  runtime as Claude Code.
+- Claude Code: full support for the shipped hook surfaces.
+- Cursor and OpenCode: portability only. We document the policies and include
+  compatibility metadata, but we do not claim native parity.
+- Ported workflows such as `engineering-assistant` must explicitly label hook
+  behavior as native, translated, manual, or documentation-only.
+
+## Operator guidance
+
+1. Treat `blocking` hooks as release or safety gates.
+2. Treat `advisory` hooks as high-signal diagnostics, not hard stops.
+3. Use `docs/target-support-matrix.md` and
+   `manifests/catalog/compatibility-matrix.json` when deciding whether a hook
+   promise is native, partial, or emulated for a given target.

package/docs/install/targets.md

@@ -0,0 +1,29 @@
+# Target install notes
+
+The package now ships `targets/codex/runtime/.codex/` and
+`targets/claude-code/runtime/.claude/` so runtime surfaces are real instead of
+implied.
+
+Installed workspaces also compile a shared runtime under `.hforge/runtime/`.
+Installed workspaces keep the canonical AI content under `.hforge/library/`
+and `.hforge/templates/`. Target-native entry points such as `AGENTS.md`,
+`CLAUDE.md`, `.agents/skills/`, and `.codex/` should be treated as thin
+bridges back to that hidden AI layer rather than as separate knowledge
+systems.
+
+The runtime now hydrates baseline repo-intelligence artifacts during bootstrap:
+
+- `.hforge/runtime/repo/repo-map.json`
+- `.hforge/runtime/repo/recommendations.json`
+- `.hforge/runtime/repo/instruction-plan.json`
+- `.hforge/runtime/findings/risk-signals.json`
+
+Canonical target support truth lives in
+`manifests/catalog/harness-capability-matrix.json`.
+
+Use it when you need to answer:
+
+- which capabilities are native, translated, emulated, or documentation-only
+- what fallback behavior degraded support requires
+- whether a support claim is still aligned with the generated
+  `docs/target-support-matrix.md` surface

package/docs/installation.md

@@ -0,0 +1,98 @@
+# Installation
+
+## Front-door setup styles
+
+Harness Forge supports both a guided interactive front door and a direct
+flag-driven install path:
+
+- `npx @harness-forge/cli` opens first-run onboarding in an interactive
+  terminal or a project hub when `.hforge/` already exists
+- `hforge init --root <repo> --agent codex --yes` performs the same setup
+  through explicit flags without prompts
+- `hforge init --root <repo> --agent codex --dry-run` previews the planned
+  writes without changing the repo
+
+Use the interactive flow when you want help choosing folder, targets,
+quick/recommended/advanced setup depth, and optional modules. Use the direct
+path for CI, automation, or expert usage.
+
+## Local launcher paths
+
+Setup writes reusable workspace-local launchers under `.hforge/generated/bin/`
+so you can keep using Harness Forge after the initial `npx` run:
+
+- `.hforge/generated/bin/hforge.cmd` for Windows Command Prompt
+- `.hforge/generated/bin/hforge.ps1` for PowerShell
+- `.hforge/generated/bin/hforge` for POSIX shells
+
+Those launchers call the published package through `npx @harness-forge/cli`.
+You only need a global install if you specifically want plain `hforge`
+available everywhere on your machine.
+
+Harness Forge supports two install paths:
+
+- published package: run `npx @harness-forge/cli bootstrap --root . --yes` in the repository you want to equip, with no manual local build step
+- source checkout: run `npm install && npm run build`, then use `node dist/cli/index.js install` or `node dist/cli/index.js bootstrap`
+
+Git-sourced npm and `npx` installs are also supported through the package
+`prepare` lifecycle, which builds the CLI automatically during installation.
+
+For a deterministic first-run workspace setup before target installation, use:
+
+```bash
+npx @harness-forge/cli init --root /path/to/your/workspace --json
+```
+
+After install changes, use:
+
+```bash
+hforge refresh --root /path/to/your/workspace --json
+```
+
+Every successful install also writes a shared runtime summary under
+`.hforge/runtime/` and materializes the canonical hidden AI layer under
+`.hforge/library/` and `.hforge/templates/`:
+
+- `.hforge/agent-manifest.json` gives custom agents one machine-readable map of
+  bridge files, canonical roots, launchers, and safe command discovery
+- `.hforge/library/skills/` holds the installed canonical skill library
+- `.hforge/library/rules/` holds the installed canonical rules
+- `.hforge/library/knowledge/` holds the installed knowledge packs
+- `.hforge/templates/` holds the installed canonical task and workflow templates
+
+- `.hforge/runtime/index.json` records the durable runtime surfaces and bridge
+  paths selected for the workspace, including every installed target
+- `.hforge/agent-manifest.json` is the stable custom-agent contract that points
+  agents at `AGENTS.md`, `.hforge/runtime/index.json`, and
+  `.hforge/generated/agent-command-catalog.json`
+- `.hforge/runtime/README.md` explains how root instructions, target runtime
+  files, and portable docs route back to that shared runtime
+- `.hforge/runtime/repo/repo-map.json` records the baseline repo map hydrated
+  during bootstrap
+- `.hforge/runtime/repo/instruction-plan.json` records target-aware bridge
+  planning for installed runtimes
+- `.hforge/runtime/findings/risk-signals.json` records baseline runtime risk
+  signals discovered during bootstrap
+- `.hforge/runtime/recursive/sessions/RS-XXX/session.json` appears only when an
+  operator explicitly escalates hard work into recursive mode and records the
+  durable draft session, budget, handles, and promotion state
+
+## Shell integration vs global install
+
+If you want bare `hforge` to work after project setup, prefer:
+
+```bash
+npx @harness-forge/cli shell setup --yes
+```
+
+That writes a user-level shim and updates a supported shell profile so the
+command is available without forcing a machine-wide npm mutation from inside a
+project bootstrap.
+
+Global install is still optional:
+
+```bash
+npm install -g @harness-forge/cli
+```
+
+Use that only if you explicitly want npm-managed machine-wide availability.

package/docs/languages.md

@@ -0,0 +1,31 @@
+# Languages
+
+Harness Forge has two language-pack tiers:
+
+- seeded packs under `knowledge-bases/seeded/`
+- structured packs under `knowledge-bases/structured/`
+
+Each language pack is expected to expose docs, rules, skills, examples, and at
+least one workflow surface that can be recommended or installed intentionally.
+
+Agent runtimes should discover language packs through `.agents/skills/` and
+then execute against the canonical `skills/` surface plus any attached
+`references/` depth.
+
+## How recommendations use them
+
+- dominant repo language signals drive `lang:*` bundle recommendations
+- framework signals extend a base language recommendation with `framework:*`
+  packs
+- high-risk or weakly validated repos also receive skill, profile, and
+  validation guidance
+
+## Current emphasis
+
+- seeded packs preserve imported source knowledge with file-level traceability
+- structured packs provide deeper operational guidance where the source archive
+  was missing
+- framework packs overlay repo-shape context on top of language guidance
+
+See `docs/catalog/language-packs.md` for pack coverage and
+`docs/catalog/framework-packs.md` for framework overlays.

package/docs/maintenance-lifecycle.md

@@ -0,0 +1,62 @@
+# Maintenance Lifecycle
+
+Harness Forge maintenance should answer three questions quickly:
+
+1. what is installed
+2. what drifted or went stale
+3. what is safe to repair, prune, or upgrade
+
+## Primary commands
+
+| Command | Purpose |
+| --- | --- |
+| `doctor` | quick health check for missing paths, bundles, and surface drift |
+| `audit` | detailed install-state summary |
+| `diff-install` | compare recorded managed files against what still exists |
+| `refresh` | rewrite shared runtime summaries and baseline repo-intelligence artifacts |
+| `sync` | normalize duplicated install-state entries |
+| `upgrade-surface` | explain how to refresh an older install safely |
+| `prune` | identify duplicate recorded writes before cleanup |
+| `repair` / `restore` / `backup` | lifecycle commands from the earlier maintenance wave |
+
+## Recommended order
+
+1. run `doctor` to spot obvious drift
+2. run `audit` for the full install-state summary
+3. use `refresh` when installed targets are correct but shared runtime summaries drifted
+4. use `diff-install` and `sync` to understand state mismatch
+4. use `upgrade-surface` before refreshing an older install
+5. use `prune` only after reviewing the candidates
+
+## Example commands
+
+```bash
+hforge doctor --json
+hforge audit --json
+hforge refresh --root . --json
+hforge diff-install --json
+hforge sync --json
+hforge upgrade-surface --json
+hforge prune --json
+```
+
+## Operator expectations
+
+- maintenance commands should be diagnostic first and destructive second
+- drift should point to concrete files or bundle ids
+- upgrade guidance should tell the operator what to rerun next
+- prune should never remove state silently without explicit opt-in
+- refresh should be safe to rerun and should not require reinstalling bundles just to regenerate runtime summaries
+
+## Imported skill maintenance
+
+- review `manifests/catalog/engineering-assistant-import-inventory.json` before
+  refreshing or extending the engineering-assistant port
+- keep `docs/authoring/engineering-assistant-port.md` aligned with the actual
+  embedded scope, helper translation plan, and runtime-compatibility notes
+- review `manifests/catalog/enhanced-skill-import-inventory.json` before
+  refreshing or pruning any embedded skill-pack content
+- keep `docs/authoring/enhanced-skill-import.md` aligned with the actual
+  embedded scope and provenance
+- run `npm run validate:skill-depth` after any skill-pack refresh so missing
+  sections or sentinel references fail fast