This repository was archived by the owner on Oct 13, 2026. It is now read-only.
Repository navigation
Breaking
The plugin is renamed from intent-engineering to expectation-fit (#41). There is no /ie-* shim: after updating, the /ie-* commands are gone. Use the /fit-* names
from this table:
| Before (intent-engineering 0.8.x) | Now (expectation-fit 0.9.0) |
|---|---|
/ie-review |
/fit-review |
/ie-audit |
/fit-audit |
/ie-validate-plan |
/fit-validate-plan |
/ie-plan-assist |
/fit-plan-assist |
/ie-from-pr-learnings |
/fit-from-pr-learnings |
/ie-init |
/fit-setup |
ie-<lens>-reviewer agents |
fit-<lens>-reviewer agents |
intent-engineering@intent-engineering-marketplace |
expectation-fit@expectation-fit-marketplace |
.intense/ config folder |
.expectation-fit/ (legacy .intense/ still read through 0.9.x; removal planned for 1.0) |
INTENSE_CONFIG_DIR |
EXPECTATION_FIT_CONFIG_DIR (legacy variable still read through 0.9.x; removal planned for 1.0) |
| Reports in a tracked folder by default | Reports default to .expectation-fit/reports/ (git-ignored) |
Fixed
fit-reviewdefines empty, plan-only and docs-only diffs (#59). An empty diff
dispatches no lens (even one set toon) and still writes the normal report with a
"Nothing to review" line. Ready is never claimed while untracked files exist: the
verdict is Not ready, andmode:agentrepliesskippedwith the untracked count. With
no untracked files either, the report says "Nothing to review" andmode:agentreplies
skippedwith verdictnull.FILESnow comes from the head the
lenses read, so remote scopes see the right change. A plan-only diff hands off to one
fit-validate-planrun over all changed docs, which now accepts several paths as one
set with one report and one flow per document. A docs-only diff keeps the same lens team and adds a claim-check
line to the intent.- The
fit-reviewfix step applies only gated fixes and checks for copies (#60).
Stage 5 step 7 and the subagent-template apply rules say that observations are never
applied. Thefix(fit-review)commit and the Applied section hold only fixes that
passed the step 7 gate; callers commit other fixes separately. Before a fix that
replaces text, the step searches for other copies and reclassifies the fix to manual
when it cannot fix them all in the touched file. The shared rules tell lenses that a
fix which prints or runs untrusted text must say how it makes that text safe. New
refusal case inevals.json. - The merge stage lists every dropped finding and verifies before apply (#47). Coverage
has a Rejected list (title, file:line, lens, severity, confidence,why) in place of
counts by anchor, and a Re-grades log for every orchestrator change to severity or
confidence. Caller constraints limit whatfit-reviewfixes, never what it reports
(accepted_by_caller). Agreement between lenses no longer raises confidence, in the
skill and the Grok workflow. Dedup merges findings on one defect within 3 lines even
when titles differ, and keepsgated_autoonly when every copy has it. Interactive
fit-reviewre-reads each finding with a read-only sub-agent before it applies, and
evals.jsongains the refusal case. - Reports no longer look cleaner or more complete than the run was (#46). The Lens
status table inreferences/report-template.mdgives each word one meaning and adds
ok(ran, findings shown) next toclean(ran, no finding shown);skippednow means
only "selected but could not analyze", andnot_selectedcovers the rest. Both
runtimes setcleanorokafter the confidence gate. The all-clear line reads "No
findings surfaced in this pass", the Header names every catalog lens with a reason,
Coverage prints a READ line per lens and an optional Cost line, and a partial read
blocks the all-clear line and Ready.fit-reviewhands the diff to lenses as
$RUN/diff.patch.check-contracts.rbchecks that every Grok status word has a row. - Lens runs without subagents or file writes have rules, and reports show how lenses ran (#43).
references/subagent-template.mdnow names the agent to dispatch per lens
(expectation-fit:fit-<lens>-reviewer, or a general agent that reads the agent file),
forbids one agent for two lenses, defines a compact reply, covers hosts that forbid
file writes, and adds a single-agent fallback section that all three orchestrators use.
Convention and architecture lenses open observations withConfig: <source>. The
report Header carriesExecution: subagents | single-agent, and a lens whose returned
lensdiffers from the dispatched one fails. Newlenses:<list>token onfit-review,
fit-validate-planandfit-audit.check-contracts.rbties the template's agent
prefix to the plugin name inplugin.json. - Off-schema findings are repaired, not dropped, and mode:agent has a full example (#53).
The shared merge steps moved fromfit-reviewStage 5 into a new "Merge and gate"
section ofreferences/report-template.md, and all three orchestrators point there.
Step 1 now repairs word severities, off-anchor confidences, unknownfix_classvalues
andfile:linevalues, and Coverage lists each repair and drop. The template and every
lens agent list the allowed values. Themode:agentsection has a complete example,
field rules, and verdict words per context, and the reply stays raw JSON.base:now
works with a PR target. The config docs state that nested maps merge at every depth.
check-contracts.rbchecks the allowed values, the example fields thatfit-review
Stage 6 names, and that no skill cites afit-reviewStage for a shared rule.
Changed
- Renamed to Expectation Fit (#41). The plugin is now
expectation-fit(marketplace
expectation-fit-marketplace). Skills and agents use thefit-prefix:fit-review,
fit-audit,fit-validate-plan,fit-plan-assist,fit-from-pr-learnings, and
fit-setup(wasie-init). Project config moves to.expectation-fit/, and the env var to
EXPECTATION_FIT_CONFIG_DIR. The old.intense/folder andINTENSE_CONFIG_DIRstill
work for at least one release; Coverage names the legacy folder and/fit-setup upgrade
offers the move. The Grok runtime is now.grok/workflows/fit-review.rhai. Published
reports from before the rename stay indocs/intent-engineering/as history. - Run scratch and reports stay out of git by default (#42). The default report folder
is now.expectation-fit/reports/(wasdocs/expectation-fit/). Each run folder and
the default report folder get a one-line*.gitignore, so a run adds nothing to
git status. To keep committing reports, setartifacts.report_dir: docs/expectation-fit.
This repo's dogfood runs can passout:docs/intent-engineering/. Other contract
changes inconfig-resolution.md: relativerun_dir,report_dirandout:resolve
from the project base, and theReport:line prints an absolute path.fit-review
andfit-auditload config before they build their file lists and exclude the run,
report andout:folders by pathspec.mode:agentwrites a report file only with
out:(elseartifact_pathisnull), and cleanup runs after the report step. The
legacy single-bucket mode is gone: a top-levelreport_diris now an alias for
artifacts.report_dir, and/fit-setup upgradecarries it over./fit-setup
question 6 warns that reports under a publisheddocs/site are public. - Reports name the plugin copy and the reviewed commit (#45). Version is now 0.9.0 in
plugin.jsonandmarketplace.json, so installs leave the stale 0.8.0 cache; the
plugin README has an Upgrade section.report-template.mddefines oneProvenance:
line (plugin version and root, repo, branch, commit, dirty flag, run id) that every
review, audit and plan report carries, plus matchingmode:agentJSON keys. A
published report is a point-in-time record: later status goes in a dated addendum,
and Applied names the real fix SHA.completed_atcarries a UTC offset. Lens prompts
get the absolute plugin root through a{plugin_root}slot instead of a literal
variable. Lenses takelinefromgrep -nor a Read, and orchestrators check each
line against its evidence quote before dedup (unverified lines go to Coverage).
fit-reviewpinsREVIEWED_SHAandBASE_SHAin Stage 1, diffs remote scopes
against the pinned commit, treats the current branch aslocal-alignedwhen
origin/<branch>is an ancestor of HEAD, and skips apply when HEAD moved.
fit-auditshows commits ahead of the default branch;fit-validate-planwarns when
the checkout is behind its upstream. The Grok workflow resolves one absolute plugin
root (or pauses), and its report carries the Provenance andRuntime:lines. - Re-runs build on the last report (#52). New shared token
prior:<report-path>
(review, audit, validate-plan): the prior report'sfixedanddeclinedrows reach
every lens through one<prior>slot, and a Shared rule forbids re-raising them
without new evidence. Findings tables gain aStatuscolumn (open,fixed <sha>,
declined: <reason or link>), also as a JSONstatusfield; interactive
fit-reviewsets it at run time and never auto-applies a prior declined item. The
review verdict now follows severity (Not ready with an open P0/P1, Ready with fixes
with an open P2, else Ready; a failed lens still blocks Ready), andfit-reviewstops
re-running at Ready.base:<head_sha of the last report>is documented as the delta
re-review; a SHA that is not an ancestor of HEAD falls back to a full-branch review.
The canonical path block takes the raw scope and applies one slug rule, and each
out:row says to pass a folder.fit-validate-planstampsplan_sha256, shows lens
coverage in the verdict, and withprior:marks each prior gap closed or open, adds a
Prior column and asupersedesline with the round. A Shared rule keeps decisions the
document marks as settled closed.
Fixed
- Config settings no longer fail silently or vary by run (#49). The defaults drop the
deadsilent-failureoverride example, and Coverage lists any unknown
severity_overrideskey as ignored (newfit-revieweval case 5). Lens toggles are
quoted, so YAML 1.1 loaders read strings, andcheck-contracts.rbfails on a bare
on. The curated workflow gate rule is mechanical (whole-file body tokens, no
pull_request:token, no "when unsure" rule). Auto discovery lists candidates with
git ls-files, so agent worktrees are not read. - Every run shows config health and a next step (#54). A defaults run ends its Config
line with "Next: run /fit-setup to save repo rules once." (the Grok workflow adds the
same observation). A legacy top-levelreport_dirnames/fit-setup upgrade. Coverage
lists the three per-file source lines. Onlyconfig:and the config env var change
discovery./fit-setupwrites a project header instead of(GLOBAL DEFAULTS), names
the legacy folder on upgrade, and both/fit-setupand/fit-from-pr-learningsend
with the git state of.expectation-fit/. Project notes are limits for every lens;
only the convention lens reports a broken note. Both READMEs recommend/fit-setup
once a repo is reviewed more than once. - Settled decisions and repo rules reach every lens (#55).
tensioncan name a
principle against a settled decision (for example plan KTD-6). A tension finding stays in
Findings, is listed in Tensions, and is never auto-applied. Every lens now gets repo
CLAUDE.md/AGENTS.mdpaths andconventions.notes;sourcesandautostay with the
convention lens. This changes the #26 view that only the convention lens holds local
authority. The lens template has an optional<known-context>block and a "Respect
known context" rule;fit-review plan:quotes plan decision lines verbatim to every lens,
and Coverage saysPlan: <path>orPlan: none. Newfit-revieweval case 6. - Grok
fit-reviewworkflow reads the right code and cannot claim a false Ready
(#44). Prompts say agents have no shell and limit what they read. The script, not an
agent, builds the diff:basemust be a commit SHA, and a ref name, a missing base, or
a non-path target with spaces pauses the run.scope_modeis set by the script. The
target is a JSON-encoded label, and the config agent sees the changed files for the
experience rule. The confidence gate runs before verify. Skeptics returnconfirmed,
not_realorunverifiable; any unverifiable or failed verify sets Not ready. Confirmed
findings keep the skeptic's reason and evidence, andend_linedefaults toline. A
lens that reportsfailed:gets status failed. The convention lens docs now match the
lens catalog. Copy the file to~/.grok/workflows/after each pull. - Lens catalog lists full doc paths, and the contract check catches drift (#51). The
"Resource docs it reads" column names every doc as a full path underresources/
(8 bare names fixed), andcheck-contracts.rbsection 4 now fails on a doc that does
not exist there.AGENTS.mdforbids repo-only paths in shipped files, says a smell-card
guard may qualify a finding but not suppress a whole class, and replaces the old local
install path with aclaude -p ... --plugin-dirdev loop.README.mdinstalls from
GitHub. - Repo upkeep: dogfood gaps become issues, and the site drops release facts (#61).
"Dogfood as you go" inAGENTS.mdadds a contributor step to file each confirmed plugin
gap as a public-safe issue. The PR template andscripts/README.mdno longer send
follow-ups towip/.docs/index.htmllinks to/releases/latestand/releases
and names no current version or check count. The "New architecture stack" bullet names
every place that lists the stacks. /fit-from-pr-learningsreadsfit-reviewdeclines and says when to run (#62).
Run it after the PR merges (a commit on an open PR branch restarts CI and review bots);
one run can take severalpr:tokens. Inpr:mode it reads the newestfit-review
report for the PR head branch inartifacts.report_dir. Only a decline whose reason
holds beyond the PR becomes aconventions.notesline, citing the report path and
finding number, and the Step 4 confirm still gates every note. The report Header names
the report read. New eval case 4.- Lens judgment (#48). The
gated_autorubric now excludes changes that outside
callers can see (public classes, signatures, defaults, documented CLI flags), so
/fit-reviewnever applies them. A new eval case pins this. Lenses getRepo root,
BaseandPlanlines in scope, check the base before they blame the change, and put
pre-existing and no-change items in observations. A failed or empty search is unknown:
an unconfirmed absence claim caps at confidence 50 (template and Grok skeptic). The
template has one shared severity rubric, andfindings-schema.jsonpoints to it. The
simplicity lens searches the requirements before a YAGNI cut. - Predictability escape classes (#58). New smells for a comment, docstring or test
name that claims code missing at HEAD (least-astonishment.md), a destructive step
that runs before its last check (error-handling.md), and a config writer that
coerces any input shape (defaults-and-configuration.md). The predictability lens now
reads the "Surprising defaults" section ofdefaults-and-configuration.md(agent,
lens catalog, Grok workflow and principle index). - Experience lens covers CLI, docs and developer output (#57).
lens-catalog.mdis
the one selection rule: it now lists CLI output, error and recovery messages, exit
codes, the stdout/stderr split and changed README or upgrade steps, and a library or
gem counts when it ships any of these.fit-review,fit-audit,fit-validate-plan,
the Grok config prompt andways-of-working.yamlpoint to it, and
check-contracts.rbfails on a restated skip rule.ux-interaction-smells.mdhas a
new "CLI and developer output" section (clig.dev added to Sources), a traced
framework-default guard, and a tighter live-region shape.accessibility.mdlimits
role="tab"to in-page panels. - Architecture lens policy and tool fixes (#50). The
pythonarch pack now needs a
web or worker framework; a plain Python CLI or library returnsSKIPPED:unless
lenses.architecture: on. brakeman is no longer listed as an architecture tool, and
fit-setupand the README no longer suggesttools.architecture: prefer. All six
stack docs andfindings-schema.jsongain along-methodsmell id (Rails gains a
"General metrics" section). Underenrich, the lens runs a present tool, notes once
per run which tools ran, and Coverage shows that note. "Pattern-bearing location" is
defined once inresources/patterns/README.md, and the lens never reports a
preferred or blocked rule as met (newfit-auditeval case 4). Behavior change:
approvednow silences blocked, instead_of and unidentified findings on its path,
but smell findings still show and net-new blocked use still gets P1 (before, review
and audit suppressed every architecture finding on an approved path). Each
unidentified-patternsuggested_fixnow holds a ready-to-pasteapprovedentry. - Mechanical
fit-validate-planverdict (#56). The verdict is Revise first when any
P0 or P1 survives the gate or a selected lens failed; otherwise Ready to implement.
A markdown reply ends with oneVerdict: … Lowest score: … Blocking: … Failed lenses: … Report: …line (new eval case 4). Several documents run as separate flows (one
lens dispatch and one report section each) inside one run and one report (#59). Plan lenses search the whole document before they call a rule missing,
search call sites before they call code unused, and word a fix that rests on unseen
framework behavior as a test. Caller checks go in aCheck | Resulttable in
Coverage.findings-schema.jsongives plan meanings for P0 and P1. The skill
description and the README place it after document review and before implementation.
Added
- Experience lens dogfood + fold-back (issue #23). Ran the experience lens
read-only on a real Hotwire/Rails app (ongela) and folded the false positives
back intoresources/agnostic/ux-interaction-smells.md: sibling-consistency
and framework-default guards, a Hotwire caveat on the double-submit signal, a
backdrop-click carve-out, a nested-attributes delete carve-out, and a
three-tier error-path model. Report:
docs/intent-engineering/2026-08-14-experience-dogfood-ongela.md. - Second experience-lens dogfood on a larger app (fizzy, issue #23). Confirmed
the ongela guards held and added six new smells plus a cross-surface guard:
bodylesshead :4xxdead-ends, live regions with noaria-live, accessible
name/action mismatch, static-role-vs-conditional-behavior drift, autosave that
cannot observe failure, implicit-submit-only controls, and a cross-surface /
affordance confidence guard. Report:
docs/intent-engineering/2026-08-16-experience-dogfood-fizzy.md. - Optional Grok
ie-reviewworkflow (.grok/workflows/ie-review.rhai).
Config-selected lenses, then one skeptic per finding, fail-closed. Report
goes to run scratch. Does not replace the/ie-reviewskill or apply
product-code fixes. First live run:
docs/intent-engineering/2026-08-12-workflow-ie-review.md.
Changed
- GitHub Pages site refresh. Light and dark themes, a finding (not a
gradient hero) as the central visual, hashed CSS/JS, an Open Graph image,
and HTML views of the published reports at/reports.html. - Experience lens: per-stack notes + template-diff auto-selection (issue #38,
follow-up to #23). Hotwire recognition notes name the concrete signals the dogfoods
surfaced; the authoritative selection rule inlens-catalog.mdnow treats a surface as
present whenever the diff touches a template/view/component/client-controller path for
any architecture-supported stack, so a mixed backend+frontend change no longer skips
experience review. - README, plugin README, AGENTS.md, PLAN.md, and the GitHub Pages site
(docs/index.html) now describe the optional Grokie-reviewruntime. - Grok
ie-reviewafter that dogfood pass: onecomplete()shape, severity-ordered
verify cap, file+line dedup, reject list, in-script confidence gate, unique
default report path. - Grok
ie-reviewremaining report items: config agent, template-shaped lens
prompts, normalized dedup plus agreement bump, schema enums, skipped/clean/failed
statuses, read-only merge, Layer A lens JSON in scratch. No write-capable
publisher. Script owns the verdict.