Context Intelligence

Context Intelligence

Forgeflow now includes local-only context helpers that reduce token load before agents are spawned. The goal is to give each agent the smallest useful packet of current files, project memory, and scope constraints.

Examples using scripts/forgeflow/ run from the ForgeFlow source checkout. In an application repository, resolve the installed helper path and keep the application as the working directory. Codex installs helpers under ${CODEX_HOME:-$HOME/.codex}/forgeflow/scripts/forgeflow/; Claude Code uses:

~/.claude/forgeflow/scripts/forgeflow/

What It Adds

Capability	Helper	Purpose
Review context packs	scripts/forgeflow/build-context-pack.js, scripts/forgeflow/check-context-contract.js	Builds bounded reviewer packets and synthesis input from the current change, including latest insights, latest failure-digest context when present, compact architecture/ownership/invocation intelligence when present, quality-gated lean guidance when present, role-specific agent context contracts, and compact topology-guided review focus for JS/TS changes. The context-contract checker validates generated packets against required sections, size limits, and advisory-boundary wording. Pass --root <repo> when the helper is launched from outside the target checkout.
Insight injection view	scripts/forgeflow/render-insight-injection.js	Explains the latest packet artifact decisions, optional baseline diff, per-agent signal contracts, quality-gate controls, and next clearing command so users can see which insight blocks are included, metadata-only, or skipped before agent-heavy work.
User profile guidance	scripts/forgeflow/show-user-profile.js, scripts/forgeflow/check-user-profile.js, scripts/forgeflow/record-user-profile.js, scripts/forgeflow/render-profile-bootstrap.js, scripts/forgeflow/render-profile-review.js, scripts/forgeflow/check-profile-compliance.js	Records, checks, shows, bootstraps, reviews, and compliance-checks local advisory user operating preferences and project experience preferences. The bootstrap helper previews explicit preference records, can show prompt templates with --prompts, returns a machine-readable next profile action, reports setup readiness for required operating prompts and recommended project-style prompts, and writes only with --write; it never infers preferences from behavior or project history. Context packs include a compact profile block only when the profile quality gate passes; warning or failed checks produce a gate note instead of raw profile text. Project intelligence raises profile-review as a next-work candidate when conflicts or suggestions need attention, and profile review renders injection eligibility, safe next steps, explicit confirmation prompts, accept/reject/supersede/defer resolution options, and a resolution flow without mutating profile state.
Code topology	scripts/forgeflow/build-code-topology.js	Builds a static JS/TS import graph with fan-in/fan-out hotspots, changed-file neighbors, topology-guided review focus, unsupported-language scope, and import-gap details for unresolved or dynamic imports. It resolves relative imports, source-suffix modules, extensionless TSX re-exports, tsconfig/jsconfig path aliases, package.json imports aliases such as #/*, common @/ and ~/ src aliases, and literal dynamic imports when the target source file exists. Code-map output can also read local exact-gap acceptances from .forgeflow/<project>/code-map-accept.json.
Memory index	scripts/forgeflow/index-memory.js	Indexes local Forgeflow memory so helpers can find relevant history cheaply.
Compact memory context	scripts/forgeflow/build-memory-context.js	Produces a concise, explainable project-memory summary for research, plan, consult, and implement workflows. It labels selected records and reports why records were selected or suppressed, including lifecycle, relevance, duplicate, per-source, and size-limit counts.
Scope manifests	scripts/forgeflow/build-scope-manifest.js	Creates implementation scope packets and file ownership hints for agent waves.
Context telemetry	scripts/forgeflow/summarize-context-telemetry.js	Summarizes estimated baseline, compact, and saved tokens from generated artifacts.
Budget checks	scripts/forgeflow/check-context-budget.js	Warns or fails when compact context exceeds configured token budgets.
Budget seed	scripts/forgeflow/seed-budget-config.js	Creates .forgeflow-budget.json without overwriting existing config.
Local artifact safety	scripts/forgeflow/file-safety.js	Refuses symlinked memory inputs and symlinked output destinations before context, memory, or learning helpers read or write local artifacts.
Health repair	scripts/forgeflow/health-check.js	Creates safe project-local Forgeflow state and seeds budget config when requested.
Runtime inventory	scripts/forgeflow/runtime-inventory.js	Provides shared command and runtime-helper inventory reads for coverage tests, health inventory checks, helper owner-surface grouping, command/helper counts, installed helper names, managed-registry counts, parity status, canonical consolidation checks, coordination-pressure guidance, and install/update/release/docs registry consolidation. Wrapper contract and wrapper-batch helpers are grouped under the command-wrapper owner surface.
Command capability matrix	scripts/forgeflow/render-command-capability-matrix.js	Renders a read-only policy-aware matrix of command wrapper, Pi alias, OpenCode command, and skill coverage so required host-surface gaps are visible without launching host applications.
Command interface evidence	scripts/forgeflow/command-interface-evidence.js	Audits explicitly supplied, schema-bounded sanitized command-chain observations for aggregate repetition and outcome evidence. It does not discover history, read raw diagnostics, create wrappers, or make performance claims; optional reports stay under the named local Forgeflow session directory.
Wrapper drift plan	scripts/forgeflow/render-wrapper-drift-plan.js	Groups command-wrapper drift into safe mechanical, manual, and high-risk buckets without editing command files.
Guided repair	scripts/forgeflow/render-guided-repair.js	Composes offline version status, health inventory, and installed runtime helper verification into a non-mutating repair plan with manual settings guidance and an explicit downstream smoke follow-up.
Release readiness	scripts/forgeflow/render-release-readiness.js	Runs the local release-check command list, verifies runtime helper sources are present, managed, regular files, and inside the checkout before install, groups blockers by readiness area, can compare against a prior JSON baseline with --baseline or the saved local snapshot with --compare-last, can update that snapshot with --save-current, and never tags, pushes, publishes, or calls GitHub.
Release follow-through	scripts/forgeflow/render-release-follow-through.js	Summarizes post-publish release verify, update verify, runtime-consumability follow-through, install-readiness blockers, and informational follow-ups without tagging, pushing, publishing, repairing installs, or calling GitHub.
Release consumption rollup	scripts/forgeflow/render-release-consumption-rollup.js	Rolls post-release follow-through into a consumed-or-attention summary, leaves downstream smoke opt-in with --with-smoke, and only writes a local snapshot when --save is supplied.
Release consumption loop	scripts/forgeflow/render-release-consumption-loop.js	Shows the ordered post-release update, smoke, and release-consumption loop with a complete or attention badge plus a downstream efficiency trial checklist without running update, repair, smoke, or snapshot writes.
Support bundle	scripts/forgeflow/render-support-bundle.js	Writes a local support/debug bundle with version, health, smoke, plan-only release readiness with post-publish verification, code-map acceptance health, docs drift, project trends, a snippet-free redaction preview, and consolidated next actions.
Context advisor	scripts/forgeflow/advise-context.js	Reports trimming recommendations, advisory trim plans, auto-trim advisor rollups when trimming is recommended, copy-ready next actions, review-wave suggestions, and previous-run trend deltas, preferring canonical context/latest telemetry when the same artifact also exists in the project context root. Budget-violation recommendations include target compact tokens, reduce-by estimates, focused-packet command suggestions, and a stop rule for raw-required failure evidence and proof files.
Project decision brief	scripts/forgeflow/render-project-decision-brief.js	Reads existing project learnings, latest insights, health timeline, and code topology artifacts into a concise next-work decision brief with recent changes, avoid-first, validate-first, and high-care file guidance without refreshing or writing state.
Lean audit	scripts/forgeflow/render-lean-audit.js	Runs a read-only repo-wide audit for avoidable dependencies, one-caller abstractions, delegating wrappers, future-proofing, and lean shortcut debt. Findings include replacement guidance, confidence, estimated net-line impact, and hard-boundary skip reasons. It writes only .forgeflow/<project>/context/lean-audit.{md,json} with --write.
Lean decision	scripts/forgeflow/render-lean-decision.js	Produces compact minimum-sufficient-solution guidance with do-first, avoid-first, validate-with, do-not-simplify, and upgrade-when fields. /consult, /implement, Codex consult/implement skills, and generated project-intelligence brief stubs carry this advisory section into handoffs when available. The JSON form includes an implementation-note candidate so record-implementation-notes.js --lean-decision can capture the ceiling and upgrade trigger.
Lean demo report	scripts/forgeflow/render-lean-demo-report.js	Summarizes local Lean Prime, host adapter, command parity, skill, and benchmark scaffold readiness for demos. It writes only .forgeflow/<project>/context/lean-demo-report.* with --write.
Lean debt	scripts/forgeflow/render-lean-debt.js	Scans local project files for forgeflow: markers and combines them with lean-decision and implementation-note ceiling records. It flags missing upgrade triggers, stays read-only by default, and writes only .forgeflow/<project>/context/lean-debt.{md,json} with --write.
Lean behavior eval	scripts/forgeflow/render-lean-behavior-eval.js	Evaluates generated output for read-only lean behavior probes: calibration boundaries, requested explanation preservation, one runnable check for non-trivial logic, dependency justification, stdlib/native/reuse evidence, and explicit requirement preservation. It does not run generated code or prove correctness.
Lean adapter contract	scripts/forgeflow/render-lean-adapter-contract.js	Validates the local lean adapter target matrix, plugin hook wiring, managed helper inventory, and lean command wrappers without installing adapters or editing host settings.
Lean adapter drift	scripts/forgeflow/render-lean-adapter-drift.js	Compares committed host adapter instruction copies with canonical generated lean rule output and required safety invariants.
Lean adapter smoke	scripts/forgeflow/render-lean-adapter-smoke.js	Parses committed adapter manifests and imports the OpenCode plugin wrapper with a temporary config directory to catch structural adapter drift.
Lean config	scripts/forgeflow/lean-config.js	Resolves lean profile precedence across explicit requests, project policy, FORGEFLOW_LEAN_DEFAULT_MODE, user-level config, and balanced fallback. User config lives under the platform Forgeflow config directory.
Lean correctness	scripts/forgeflow/render-lean-correctness.js	Runs executable local canaries that accept known-good snippets and reject known lazy-wrong snippets for common shortcut traps.
Lean eval pack	scripts/forgeflow/render-lean-eval-pack.js	Runs local deterministic lean eval fixtures against the behavior probes for calibration, explanation, checks, dependency avoidance, reuse evidence, and explicit requirement preservation. It does not call models, run generated code, install dependencies, or use the network.
Lean hook contract	scripts/forgeflow/render-lean-hook-contract.js	Exercises the lean activation hook as a subprocess when the local runner permits process spawning and reports sandbox denial as an explicit environment-blocked warning.
Lean host adapters	scripts/forgeflow/render-lean-host-adapters.js	Validates committed lean host adapter artifacts for plugin, extension, instruction, and skill-tier hosts without installing them.
Lean host CLI probes	scripts/forgeflow/render-lean-host-cli-probes.js	Checks PATH for optional host CLI executable names and prints manual probe commands without running host CLIs. Optional evidence JSON can mark manually verified probes.
Lean host command parity	scripts/forgeflow/render-lean-host-command-parity.js	Checks that pi registered lean commands have matching Forgeflow command wrappers and OpenCode command files.
Lean host packages	scripts/forgeflow/render-lean-host-packages.js	Renders a host package manifest for plugin, adapter, instruction, and skill-tier lean targets. Default output is read-only; --write stores only .forgeflow/<project>/lean-packages/.
Lean mode	scripts/forgeflow/render-lean-mode.js	Shows or persists the lean guidance profile. Profiles are off, lite, balanced, strict, and ultra; --write saves project policy under .forgeflow/<project>/context/lean-policy.{md,json}, and --user --write saves a user-level default. Context packs default to balanced after project, env, and user config are checked.
Lean OpenClaw skill	scripts/forgeflow/render-lean-openclaw-skill.js	Checks or regenerates the committed OpenClaw lean skill from the canonical lean rule text. It is read-only unless --write is supplied.
Lean portability pack	scripts/forgeflow/render-lean-portability-pack.js	Generates or checks portable lean rule copies for generic agents, Cursor, Windsurf, Cline, Copilot, Copilot CLI, Kiro, OpenCode, Gemini/Antigravity, OpenClaw-style skills, and skill-style adapters. It is read-only by default and writes only .forgeflow/<project>/lean-portability/ with --write.
Lean prime	scripts/forgeflow/render-lean-prime.js	Composes lean mode, status, report, and telemetry quality into one first-run checklist with the next command needed to make lean context injection ready. It is read-only by default. --prime-task writes decision and plan artifacts; --write-plan saves a plan, and --write-report saves the local report.
Lean rule builder	scripts/forgeflow/lean-rule-builder.js	Provides the canonical compact lean rule text used by session guidance and portability targets so adapter copies can be drift-checked against one source.
Lean review	scripts/forgeflow/render-lean-review.js	Reports read-only over-engineering-only findings from a diff with explicit delete, stdlib, native, reuse, yagni, shrink, and prose-bloat tags. Findings include static project evidence, confidence, replacement guidance, estimated net lines, why-safe/why-not-safe evidence, and proof steps. It suppresses obvious semantic false positives into skipped-boundary records, skips hard-boundary scopes, and emits schema-compatible findings for evidence checks without applying fixes. Static evidence is advisory and does not prove runtime behavior.
Lean session	scripts/forgeflow/render-lean-session.js	Renders compact always-on lean session guidance plus a LEAN:<profile> statusline string for hooks or adapters. It is display-only and does not edit settings, install hooks, mutate context, change routing, commit, push, or call the network.
Lean skills	scripts/forgeflow/render-lean-skills.js	Checks or regenerates committed skills/forgeflow-lean*/SKILL.md packages from canonical lean rule text for skill-capable hosts.
Lean markers	scripts/forgeflow/lean-markers.js	Parses optional forgeflow: lean, forgeflow: upgrade when, forgeflow: no-new-deps, forgeflow: stdlib-first, forgeflow: native-first, and forgeflow: reuse-first breadcrumbs from added lines. /forgeflow-lean-review reports marker summaries and issues, but markers are advisory and cannot justify removing required behavior.
Lean lab	scripts/forgeflow/render-lean-lab.js	Compares baseline, balanced, strict, and ultra guidance modes across repeatable local task-pack result JSON. It reports sample size, validation pass rate, LOC, files touched, review churn, context tokens, optional cost/latency, and follow-up fixes. It refuses rankings until each mode has visible sample size and passing validation evidence, stays read-only by default, and writes only .forgeflow/<project>/context/lean-lab.{md,json} with --write.
Lean benchmark	scripts/forgeflow/render-lean-benchmark.js	Compares local baseline and lean-guided aggregate metrics from benchmark JSON or lean-report JSON: files, lines, validation signals, review findings, prose warnings, ceiling captures, follow-up signals, and context-token savings. It is read-only by default and writes only .forgeflow/<project>/context/lean-benchmark.{md,json} with --write.
Lean benchmark results	scripts/forgeflow/render-lean-benchmark-results.js	Validates aggregate benchmark result metadata, sample size, correctness gates, cost and latency metrics, and session-cost caveats before allowing performance claims.
Lean benchmark runner	scripts/forgeflow/render-lean-benchmark-runner.js	Renders an opt-in benchmark runner scaffold with task arms, aggregate comparison commands, and explicit model-runner placeholders. Default output never calls models or the network; --run requires FORGEFLOW_BENCHMARK_ALLOW_NETWORK=1 and a local promptfoo executable.
Lean output budget	scripts/forgeflow/output-contract.js --lean-file <path>	Warns when generated lean handoffs or review notes exceed the code/result-first shape or use more than three concise narrative bullets. The check is advisory and explicitly preserves raw command output, diffs, failure evidence, review evidence, and user-requested explanations.
Lean report	scripts/forgeflow/render-lean-report.js	Summarizes local aggregate lean-delivery signals: diff size, reuse and avoid-first counts, validation minimums, simplification ceiling capture, lean-review findings, prose-budget warnings, context-token savings, and telemetry quality. It is read-only by default and writes only .forgeflow/<project>/context/lean-report.{md,json} with --write. Context packs inject lean guidance only when lean mode permits it and lean-decision, lean-report, latest-insights, profile, operating-model, and telemetry gates pass.
Lean robustness eval	scripts/forgeflow/render-lean-robustness-eval.js	Runs deterministic known-good versus known-lazy-wrong checks for common shortcut correctness traps such as leap years, binary search, nested flattening, URL/IP/email validation, and Luhn validation.
Lean rule canary	scripts/forgeflow/render-lean-rule-canary.js	Checks load-bearing lean invariants across canonical rules, session text, docs, and portability targets so safety carve-outs and one-check guidance do not drift silently.
Lean status	scripts/forgeflow/render-lean-status.js	Shows the effective lean mode, context-injection gates, helper availability, automatic consult/implement/review/ship wiring, and one next command to clear the highest-priority blocker. It is read-only and never rebuilds context, edits settings, changes routing, commits, pushes, or calls the network.
Architecture docs	scripts/forgeflow/render-architecture-docs.js	Renders advisory Markdown/JSON architecture documentation from existing code topology, project intelligence, operating model, and project-learning artifacts. Default output is read-only; --write stores local .forgeflow/<project>/context/architecture.md and .json only.
Invocation hints	scripts/forgeflow/render-invocation-hints.js	Renders advisory runtime entrypoint and invocation hints from package scripts, package entry fields, bins, common config files, route-like paths, topology, and architecture evidence. Default output is read-only; --write stores local .forgeflow/<project>/context/invocation-hints.md and .json only. It never executes scripts, starts servers, installs dependencies, traces runtime behavior, or claims a full call graph.
Ownership map	scripts/forgeflow/render-ownership-map.js	Renders advisory owner-surface recommendations from local topology, architecture, project operating-model, and optional CODEOWNERS evidence. Default output is read-only; --write stores local .forgeflow/<project>/context/ownership-map.md and .json only. It never edits CODEOWNERS, calls GitHub, assigns reviewers, or claims permission proof.
Dogfood report	scripts/forgeflow/render-dogfood-report.js	Reviews Phase 8-11 evidence, context-pack signals, invalid artifacts, and deferred automation boundaries into a keep, refine, or consider-promote decision. Default output is read-only; --write stores local .forgeflow/<project>/context/dogfood-report.md and .json only. It never patches files, calls GitHub, pushes, publishes, batches fixes, or promotes automation automatically.
Dogfood refresh plan	scripts/forgeflow/render-dogfood-refresh-plan.js	Converts missing or invalid dogfood evidence into ordered local refresh commands. It is read-only and does not run commands, write artifacts, spawn agents, edit files, commit, push, call GitHub, or promote automation.
Dashboard readiness API	services/dashboard/readiness.js, services/dashboard/server.js	Serves GET /api/readiness for the optional local dashboard. It reads existing local project-health, latest-insights, context-budget, release-readiness, dogfood-report, and dogfood-refresh-plan evidence into compact cards. It does not refresh artifacts, write files, run shell commands, spawn agents, call GitHub, export telemetry, or expose absolute project artifact roots.
Dashboard readiness panel	services/dashboard/public/index.html	Displays the readiness API as text-labeled status cards, stale or missing evidence states, a copy-only next-action command, and the read-only boundary. It stacks on narrow viewports and never runs commands from the browser.
Project operating model	scripts/forgeflow/build-project-operating-model.js	Builds local advisory JSON and Markdown from project intelligence, topology, learnings, review outcomes, validation patterns, and user profile signals. /forgeflow-project-model displays it directly, appends compact history snapshots for drift comparison, and context packs inject a compact verify-before-use version with read-first, avoid-first, validate-first, high-care file, review-policy, and proof-boundary guidance.
Context retention	scripts/forgeflow/render-context-retention.js	Reviews latest context artifacts, agent packets, broad context files, code-map history, and context-advisor history for stale or oversized local guidance. The broad bucket excludes nested latest and agent-packet buckets to avoid double-counted advisory noise. Add --preview-cleanup to list manual stale-file and history-trim candidates. The command is read-only and only recommends manual refresh, archive, or retention cleanup.
Context wave plan	scripts/forgeflow/render-context-wave-plan.js	Reads the latest context telemetry, file manifest, synthesis input, and topology hints, then recommends staged review waves when compact packets exceed the target token budget. It flags incomplete zero-file packets, prioritizes path risk, topology hubs, changed-neighborhood hints, and proof files, adds per-wave budget status, proof contracts, and verification commands, and stays read-only unless --write-wave-files is explicit.
Context wave build	scripts/forgeflow/build-context-wave.js	Writes deterministic wave file lists and rebuilds only the selected focused context packet into .forgeflow/<project>/context/latest/waves/<wave>/context-pack, then reports post-build budget status, violations, write boundary, verification command, and focused-packet handoff. It uses explicit file-list input, avoids shell execution, and does not spawn reviewers or edit source files.
Review wave prep	scripts/forgeflow/render-review-wave-prep.js	Converts the context wave plan into the first focused review-wave command so broad changes can be reviewed in budget without spawning reviewers or rebuilding packets.
Next-work ranking	scripts/forgeflow/render-next-work-ranking.js	Reads current project intelligence and related context-budget, failure-digest, outcome, profile, and hot-file signals, then ranks next-work candidates with confidence, demotion conditions, validation hints, advisory proof boundaries, and copy-ready outcome capture prompts.
Efficiency gap plan	scripts/forgeflow/render-efficiency-gap-plan.js	Combines next-work ranking, learning status, live context-advisor budget state, outcome capture readiness, failure-digest readiness, runtime inventory pressure, and telemetry sparsity into five ranked safe phases. It is read-only and does not record outcomes, infer preferences, execute failed commands, edit files, commit, push, or spawn agents.
Workflow readiness	scripts/forgeflow/render-workflow-readiness.js	Consolidates review-wave readiness, outcome calibration, explicit profile setup, telemetry quality, runtime inventory parity, and paused high-risk wrapper work into one read-only next-action queue.
Outcome capture plan	scripts/forgeflow/render-outcome-capture-plan.js, scripts/forgeflow/render-workflow-ending-capture.js	Shows which local outcome evidence streams are missing and prints after-action recorder prompts for next-work outcomes, review outcomes, and agent feedback without writing records. The workflow-ending helper narrows that plan to the one event-specific recorder prompt to consider at the end of a review, next-work action, or agent-feedback event, then repeats the required evidence values, matching learning-capture nudge, and observed-evidence stop rule.
Agent drift	scripts/forgeflow/check-agent-drift.js	Compares agent prompts against canonical shared intelligence sections, with mode-specific Architect expectations and adapted sections treated as informational.
Implementation notes recorder	scripts/forgeflow/record-implementation-notes.js	Appends Coordinator-consolidated note candidates to the local implementation notes artifact.
Implementation notes checker	scripts/forgeflow/check-implementation-notes.js	Audits notes structure, sensitive-content patterns, and ship-summary note rendering.
Project learnings checker	scripts/forgeflow/check-project-learnings.js	Audits project-learning guidance for safety, usefulness, size, freshness, duplicates, and proof-boundary text.
Project learning recorder	scripts/forgeflow/record-project-learning.js	Appends structured local learning candidates with optional confidence, evidence-count, application-guidance, and lifecycle metadata.
Pilot evidence recorder	scripts/forgeflow/record-pilot-evidence.js	Creates a local maintainer-pilot evidence note under .forgeflow/<project-name>/pilot-evidence/.
Pattern learnings rollup	scripts/forgeflow/rollup-pattern-learnings.js	Scans cross-project learnings and project-learning candidates, clusters known/candidate patterns with source-mix labels, marks manual promotion candidates, and records pattern-log freshness for reports.
Pattern review	scripts/forgeflow/render-pattern-review.js	Renders dry-run promotion candidates with sample citations, redaction checklist, and manual-promotion proof boundary.
Learning status	scripts/forgeflow/show-learning-status.js, scripts/forgeflow/learning-signal-policy.js	Summarizes project learnings, user profile, agent feedback, review outcomes, next-work outcomes, first-run results, and project operating-model readiness into one advisory health view with fix-first, watch, healthy lanes, signal-quality scoring with configurable age/reinforcement decay, trusted-source and weakest-source rollups, a single next quality action, exact outcome-capture commands, event-specific workflow-ending capture prompts, and telemetry evidence-ladder boundaries for missing calibration streams. The policy helper can compare a proposed JSON policy without writing it.
Learning action router	scripts/forgeflow/render-learning-action-router.js	Reads learning status and telemetry quality, then routes the weakest source to one concrete local capture/check command. It is read-only and does not record outcomes, approve work, edit files, commit, push, or export local evidence.
First useful win	scripts/forgeflow/render-first-useful-win.js	Summarizes early public-safe value evidence from first-run results, pilot evidence, agent feedback, and learning status, then prints a runtime-specific first-use path for install health, profile bootstrap, first task reporting, workflow-ending capture, and shareable summary.
First task report	scripts/forgeflow/render-first-task-report.js	Summarizes first real work-item success signals, blockers, next-work outcomes, review outcomes, and learning status into an adoption next-action report.
First task adoption loop	scripts/forgeflow/render-first-task-adoption-loop.js	Turns first-task and useful-win evidence into a repeat, fix, defer, or expand decision without exposing raw local outcome records.
Next-action contract	scripts/forgeflow/next-action-contract.js	Audits helper next, next_action, and next_command fields for command-only copy-pastable values, keeping explanatory text in separate reason fields.
Output contract	scripts/forgeflow/output-contract.js	Spot-checks representative helper output for status, next, reason, and advisory boundary fields.
Review-auto classifier, sandbox proposal, apply, and status	scripts/forgeflow/check-review-evidence-schema.js, scripts/forgeflow/classify-review-auto.js, scripts/forgeflow/render-review-auto-evidence.js, scripts/forgeflow/build-review-autofix-proposal.js, scripts/forgeflow/run-review-autofix-sandbox.js, scripts/forgeflow/apply-review-autofix-proposal.js, scripts/forgeflow/show-review-autofix-status.js	Validates captured findings shape, path hazards, multi-file findings, and obvious safety hazards, previews safe, risky, and blocker buckets from captured review findings JSON, writes local evidence, builds deterministic exact-replacement proposals for the first allowlisted executor classes, runs proposals in an isolated temp sandbox, can explicitly apply one selected validated proposal after tracked-worktree, source-match, and validation checks, and summarizes proposal/apply state with the next safe action. Failed apply validation rolls back the changed file. The path never commits, pushes, publishes, calls GitHub, dispatches workers, or batches fixes.
Command argument parser	scripts/forgeflow/command-args.js	Validates a small command-argument subset against an explicit allowlist, including boolean flags and value/path flags, without executing commands or expanding shell syntax.
Command wrapper contract	scripts/forgeflow/command-wrapper-contract.js, scripts/forgeflow/render-command-wrapper-batch.js	Inventories command wrappers for helper fallback, repair guidance, safe argument forwarding, and Node environment scrubbing. Existing drift is reported as a baseline with issue counts by type and ranked next-batch instructions so wrapper consolidation can proceed without broad command rewrites, and the batch helper ranks the next small cleanup set without editing command files.
Command index	scripts/forgeflow/render-command-index.js	Generates a compact command index from command frontmatter plus runtime-inventory command discovery so docs and support surfaces can stay thin without duplicating long command lists.
Project health timeline	scripts/forgeflow/show-project-health-timeline.js	Renders a read-only local timeline, comparable deltas, and project-map evolution from code-map history, context-advisor history, latest-insights readiness, and learning-signal quality.
Pilot evidence rollup	scripts/forgeflow/rollup-pilot-evidence.js	Summarizes local pilot evidence notes into support-category counts, setup friction, project-intelligence readiness, living project-map status, agent-feedback signal, and an explained next-action decision.
Project learnings rollup	scripts/forgeflow/rollup-project-learnings.js	Refreshes durable project guidance from implementation notes, review outcomes, and ship metadata.
Project learnings display	scripts/forgeflow/show-project-learnings.js	Refreshes project learnings, optionally runs the quality gate and context-pack smoke, and prints the current-project insight view used by /forgeflow-learnings --project.
Latest insights packets	scripts/forgeflow/build-context-pack.js	Includes the current project-learning insight view in agent packets only after the project-learning quality check passes, and writes a gate report.
Latest insights state	scripts/forgeflow/latest-insights-state.js	Provides the shared readiness/freshness check used by health, report, and trends.
Privacy boundary	scripts/forgeflow/privacy-boundary.js	Centralizes sensitive-content detection, public-safe blocker normalization, and shell argument quoting for local learning, pilot, feedback, adoption, and implementation-note helpers.
Agent feedback rollup	scripts/forgeflow/rollup-agent-feedback.js	Summarizes local agent-feedback.jsonl by reviewer, signal, promotable count, corrective count, skipped invalid/private lines, filtered advisory examples, correction themes, manual-promotion candidates, and stale markers.
Project code map	scripts/forgeflow/show-code-map.js	Renders a compact maintainer-facing map from topology, hotspots, sections, changed sections, import gaps, provenance, trend deltas, living project-map categories, and artifact paths.
Living map review guidance	scripts/forgeflow/build-context-pack.js	Injects compact living project-map categories into reviewer packets and synthesis input as prioritization guidance only, with the static-analysis caveat that categories are not findings, runtime proof, or dependency severity.
Resolved edge summary	scripts/forgeflow/show-code-map.js	Shows relative, alias, literal dynamic, source-suffix, and JS/JSX compatibility edge counts, plus compact alias and dynamic examples so users can explain topology edge-count changes.
Import-gap triage	scripts/forgeflow/show-code-map.js	Groups import gaps into likely expected gaps versus gaps needing review, with categories for assets/data, non-literal dynamic imports, source suffix resolution, aliases, local missing modules, and test fixtures.
Safe command-output reduction	scripts/forgeflow/compact-command-output.js, scripts/forgeflow/capture-command-output.js	Compacts allowlisted human-narrative output only, optionally writes a failure digest from provided output, and preserves diffs, patches, SHAs, exact file lists, and unsafe command output raw with an explicit reason.
Failure digest	scripts/forgeflow/build-failure-digest.js	Writes a compact failure digest with Git provenance, raw-required status, omitted-line counts, detected file/line references, and compact output. Trends and reports label first-run missing digest state as informational until the first failed command is captured.
Noisy command advisor	scripts/forgeflow/advise-noisy-command.js	Suggests narrower invocations and capture modes for noisy commands such as unbounded find, recursive listings, broad test runs, and broad build/typecheck/lint output.
Validation failure capture	scripts/forgeflow/render-validation-failure-capture.js	Maps a failed validation command to the safest capture mode, failure-digest path, and first-run capture prompt without executing commands or writing digests; correctness-critical output stays raw-required.
Project trends	scripts/forgeflow/show-project-trends.js	Summarizes code-map trend status, operating-model drift, living project-map categories, import-gap status, artifact freshness, latest-insights readiness/freshness, latest failure-digest provenance/freshness, project-learning consumption, and advisor health from existing local artifacts, with optional --refresh first and a direct refresh recommendation when stale. Operating-model drift is advisory and does not block work by itself.
Stale artifact plan	scripts/forgeflow/render-stale-artifact-plan.js	Converts stale trend, latest-insights, failure-digest, and context-budget signals into minimal slash-command refresh steps plus build-aftercare guidance without refreshing or deleting local artifacts.
Validation plan	scripts/forgeflow/render-validation-plan.js	Maps changed files to focused validation commands, flags when full suite or source smoke are required, exposes the first failure-capture action, and includes compact failure-capture commands for failed checks without executing or writing digests.
Project intelligence rollup	scripts/forgeflow/build-project-intelligence.js	Writes .forgeflow/<project-name>/context/project-intelligence-rollup.{json,md} with readiness state (ready, needs-refresh, needs-triage, or blocked), trust state, freshness, Git provenance, top risks, hot files, validation patterns, advisory agent-feedback summary, aggregate review-outcome learning signals, next-work outcome confidence, recommended next actions, next-work brief, advisory next-work item candidates, and review-prep guidance from trends and project learnings. Next-work candidates include evidence strength, confidence score and reason codes, what-to-change, how-to-prove, stop-when, start, validation, and proof-boundary fields so weak or stale signals stay advisory. First-run missing failure digests stay informational until a failed command has been captured, first-run fallback guidance starts with install health and project orientation, and next-work ranking uses an explicit policy that favors current actionable signals over readiness or history-only noise. Add --next-work for a compact human-readable view of only the advisory next-work candidates. It refreshes project learnings and compact code-map context before synthesis unless a trends refresh already did that work.
Forgeflow report	scripts/forgeflow/render-forgeflow-report.js	Combines local telemetry, false-positive thresholds, pattern-log freshness, context savings, project trends, import-gap status, latest-insights readiness/freshness, latest failure-digest status/freshness, and direct next-action recommendations into one report, with optional --refresh first.
Forgeflow skills	scripts/forgeflow/render-forgeflow-skills.js	Checks or regenerates committed core skills/forgeflow-*/SKILL.md packages for skill-capable hosts. It is read-only unless --write is supplied.
Telemetry quality	scripts/forgeflow/render-telemetry-quality.js	Summarizes local metrics events plus review, agent-feedback, and next-work outcome counts so calibration can distinguish ready evidence from sparse evidence. It reports trusted sources, weakest sources, confidence, and one next quality action using the same vocabulary as learning status. It is read-only and does not backfill, export, or infer local records.
Release notes draft	scripts/forgeflow/render-release-notes.js	Collects plugin version, matching changelog, recent commits, changed files, issue context from commit subjects, an optional local { "issues": [...] } metadata file, optional release evidence JSON, dirty state, and release-gate commands into a public-safe Markdown or JSON release-note draft.
Release readiness	scripts/forgeflow/render-release-readiness.js, scripts/forgeflow/render-release-verify.js, scripts/forgeflow/render-release-follow-through.js, scripts/forgeflow/render-release-consumption-rollup.js, scripts/forgeflow/render-post-release-install-verify.js	Runs local release readiness checks, release-to-install preflight, optional baseline comparison, optional snapshot writing, optional post-publish verification for local tag/changelog/release-note/source-smoke/update-smoke/installed-runtime-dogfood evidence, installed-version and runtime-drift consumability evidence, compact shareable post-publish summaries, optional post-publish snapshot comparison, post-release follow-through with install-readiness blockers, release-consumption confidence, optional follow-through snapshot writing, compact release-consumption rollups, optional downstream smoke, post-release install verification, and explicit --github read-only release/tag evidence. Post-release install verification treats mode-only install drift as informational instead of repair-required.
Update verification	scripts/forgeflow/render-update-verify.js	Verifies installed version state and runtime drift after update or repair, then prints ready, restart, or repair guidance plus drift guidance that separates missing version metadata, source/install drift, and runtime drift needing repair without mutating installed files.
Smoke check	scripts/forgeflow/smoke-check.js	Defaults to downstream readiness checks for health, trends refresh, report refresh, and code map. Warn/fail checks include reason, evidence, clearing guidance, and next actions in JSON and Markdown. Code-map smoke reports production, expected, local-accepted, and needs-review import-gap counts separately, so expected gaps remain informational when no gaps need review. Use --mode source for source-tree release guards plus packaged and installed-runtime dogfood self-tests, or --mode full for both groups.
Pilot script	scripts/forgeflow/render-pilot-script.js	Prints the default bounded maintainer trial script or a first-real-task new-user path with --path new-user, plus a public-safe result template that connects smoke, report, code-map, evidence recording, and pilot rollup.
First-run guide	scripts/forgeflow/render-first-run-guide.js	Prints a compact net-new user path for install verification, project orientation, profile readiness, one bounded work item, and stop conditions.
First-run simulator	scripts/forgeflow/render-first-run-simulator.js	Simulates a fresh first-run path by checking plugin version evidence, runtime-specific first-use steps, and source-smoke readiness without installing, updating, repairing, or writing evidence.
First useful win	scripts/forgeflow/render-first-useful-win.js	Summarizes aggregate first-run, pilot, agent-feedback, and learning evidence, then prints a Claude Code or Codex/source first-use path for install health, profile bootstrap, first task reporting, workflow-ending capture, and a shareable useful-win summary.
First-run result	scripts/forgeflow/record-first-run-result.js	Records public-safe local first-run health, smoke, profile, decision, friction, next action, and notes under .forgeflow/<project>/first-run-results/.
First-run rollup	scripts/forgeflow/rollup-first-run-results.js	Summarizes aggregate first-run runtime, health, smoke, profile, decision, and friction counts while keeping raw result files local.
Next-work outcome	scripts/forgeflow/record-next-work-outcome.js	Records local advisory feedback on whether a next-work recommendation was useful, ignored, incorrect, or blocked; project intelligence uses the aggregate as weak calibration signal only.
Adoption pack	scripts/forgeflow/render-adoption-pack.js	Prints fit criteria, first-trial steps, existing pilot-evidence rollup counts, recommended next action, public-safe summary, small-team handoff checklist, proof boundary, and repeat/expand/fix/defer rubric.

When present, .forgeflow/<project-name>/implementation-notes.md is included in the memory index. This lets later consult, implement, review, and ship phases see prior decisions, spec gaps, tradeoffs, deviations, follow-ups, and validation notes without loading the full raw notes file into every prompt.

Explainable Memory Selection

Memory helpers select only focused, active local records. Their output includes selection and suppression counts so a reader can tell whether records were omitted because they were stale or superseded, unrelated to the task, duplicate, over a per-source limit, or outside the configured size limit. Selected records carry a current, active, or verify label; no matching evidence is reported as no strong local memory hits, not as advice.

This is retrieval explanation, not a claim that selected memory is true. Current files, tests, and direct evidence still win when they disagree with a memory record.

Project memory and user-profile memory remain separate. Memory-selection diagnostics describe project-local records only; they do not expose, search, or change user-profile preferences. All artifacts stay local under .forgeflow/ unless a team deliberately chooses to sync selected state.

An optional Obsidian vault connection publishes curated project notes and adds shared guidance to memory retrieval. Each checkout maps to the same explicit project ID, while vault paths and generated indexes remain local. Source fingerprints, revision history and conflict checks prevent transferred notes from becoming fresh validation evidence.

Context helpers treat .forgeflow/ as local state but still guard it: memory indexing and fallback memory reads refuse symlinked sources, predictable output files refuse symlinked destinations, and context/scope summaries include untracked files so newly created work is visible to reviewers. In CI mode, context-pack generation fails predictably when generated telemetry exceeds the configured context budget instead of silently handing out an over-budget packet.

Review context packs include a compact User Profile Guidance section when ~/.claude/forgeflow/user-operating-profile.jsonl or .forgeflow/<project-name>/project-experience-profile.jsonl has usable entries and the profile quality check passes. Global entries describe how the user likes Forgeflow to operate across projects; project entries describe look, feel, copy, accessibility, or project workflow preferences for the current repo. The profile block is advisory only and cannot override explicit current-turn instructions, correctness, security, accessibility, validation evidence, or product judgment. If the profile quality check warns or fails, context packs include a gate note instead of raw profile text.

Review context packs include a compact Project Code Map section when .forgeflow/<project-name>/context/project-code-map.md or code-topology.json exists. This gives agents project-level hotspot and section guidance even when the current change is not a JS/TS diff.

When JS/TS files are in scope, review context packs also write code-topology.json, code-topology-review-focus.md, and code-topology-telemetry.json, then include a compact Code Topology section in each agent packet. The context-pack topology JSON uses changed-neighborhood scope to keep changed files, read-next neighbors, topology-guided focus hints, hotspot nodes, import-gap examples, section hints, unsupported-language scope, and Git provenance without storing the full repo graph in the review artifact. Code-map refreshes retain compact snapshots in .forgeflow/<project-name>/context/code-map-history.jsonl, allowing the map to report previous-run deltas such as new hotspots, unresolved import changes, and changed-section churn. The living project-map block turns those deltas into categories: baseline for a first snapshot, missing-history when no comparable history exists, new hotspot, cooling hotspot, import-gap growth/reduction per metric, changed-section churn, graph-growth score, and stable structure. Each category includes one next action. Import gaps are still shown when they come from fixtures or tests, but trends/report/smoke only escalate production-scope gaps. If .forgeflow/<project-name>/context/latest/failure-digest.md exists, context packets include a compact Latest Failure Digest section and synthesis-input.json links its freshness metadata so agents can start from the last summarized failure without rereading large logs, while seeing when the digest is stale for the current checkout. synthesis-input.json and build-context-pack.js --json expose a code_topology_summary/code_topology object with hotspot paths, read-next neighbors, topology-guided review focus, provenance, and history metadata for the current review surface. Treat all topology/code-map content as static import and section guidance only, not a runtime call graph.

When present, .forgeflow/<project-name>/project-learnings.md should be treated as guidance, not proof. Agents may use it to anticipate likely pitfalls and local patterns, but every current finding still needs evidence from current code, tests, and artifacts. The project-learning display helper refreshes the current checkout's compact code topology before rollup, so structural hotspots, changed-section files, and code-map trend deltas can become Hot Files And Modules, Risk Areas, and next-work guidance without relying on stale topology. Project intelligence also reads aggregate review-outcome learning signals so false positives, missed issues, stale guidance, and manual promotion candidates can influence review-prep and next-work guidance without exposing raw outcome records. If the quality check returns warn or fail, context packs replace the insights with a compact warning and do not inject the guidance. Use /forgeflow-learnings --project --check to refresh the artifact, run the quality gate, smoke-test context-pack injection, and inspect the same gate from the command surface.

Recommended Flow

For normal review, start with /review in Claude Code or $forge-review in Codex. The workflow prepares context when helpers are available. To inspect or prepare packets explicitly:

node scripts/forgeflow/build-context-pack.js --root . --json
node scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json
node scripts/forgeflow/advise-context.js --root .forgeflow --record --json

If a packet is too large, use the focused-wave path in Context Budget Examples. Refresh stale project guidance before relying on it, while preserving a deliberately focused packet. Source-release smoke (--mode source), pilot simulation, and cross-project pattern analysis are separate maintainer or adoption operations; they are not a prerequisite for reviewing an application.

For implementation:

scripts/forgeflow/build-memory-context.js --json
scripts/forgeflow/build-scope-manifest.js --json
scripts/forgeflow/build-code-topology.js --json
scripts/forgeflow/show-code-map.js --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json
scripts/forgeflow/advise-context.js --root .forgeflow --record --json

For reporting:

scripts/forgeflow/summarize-context-telemetry.js --root .forgeflow --json
scripts/forgeflow/check-context-budget.js --root .forgeflow --warn-only --json
scripts/forgeflow/advise-context.js --root .forgeflow --record --json

Budget Config

Seed a project-local budget config:

scripts/forgeflow/seed-budget-config.js --json

The default template supports global and per-kind limits:

{
  "max_compact_tokens": 16000,
  "warn_only": true,
  "kind_limits": {
    "context-pack": 16000,
    "code-topology": 12000,
    "memory-context": 8000,
    "scope-manifest": 6000
  }
}

See Context Budget Examples for review, implementation, strict release-gate, large-diff, low-savings, and trend workflows.

Health Repair

Run the project-local health helper when a repo is missing Forgeflow state:

scripts/forgeflow/health-check.js --fix --json

It can create:

• .forgeflow/<project-name>/
• .forgeflow/<project-name>/agent-notes/
• .forgeflow/ in .gitignore
• .forgeflow-budget.json when missing

It does not overwrite an existing budget config.

Trend History

The context advisor records compact history when --record is used:

.forgeflow/context-advisor-history.jsonl

Each record includes:

• telemetry file count
• estimated compact tokens
• estimated saved tokens
• percent saved
• budget status and violation count
• recommendation actions

The advisor also scans code-map history files under .forgeflow/<project-name>/context/code-map-history.jsonl. When at least two snapshots exist, it reports compared code-map trend deltas, including new hotspots, unresolved import growth, and changed-section churn.

The next advisor run compares against the prior record and reports deltas for compact tokens, saved tokens, percent saved, and budget violations.

The advisor also reads code-topology-telemetry.json when present. Its output reports topology coverage, source-file and edge counts, unresolved imports, and skipped dynamic imports so teams can spot when topology guidance is missing or when import-graph blind spots are recurring.

Local-First Behavior

All generated context artifacts stay under .forgeflow/ by default. The state is local project memory, not hosted telemetry. Keep .forgeflow/ ignored unless your team intentionally chooses to sync selected artifacts.