Repository navigation
Support Protocol Buffers - #11
Merged
Merged
Conversation
Original prompt: > please sync your liyi repo to latest and check if any local branches are still worth keeping > okay, delete the branches and check how much of next-steps is still TODO > well, please check the actual state of the codebase > okay, please update the docs in a branch > please commit and check the other docs for staleness. > yes please push (but don't open a PR yet). Human note: archived the original prompts and added the AIGC trailer; the agent originally just wrote the commit summary and nothing else in this commit message. The contents are all authored by the agent though. AI-assisted-by: GPT-5.5 (OpenClaw) Signed-off-by: WANG Xuerui <[email protected]>
Record the current check.rs shape and the intended public API extraction before changing linter code. The roadmap is deliberately temporary: it should either be deleted or folded back into the maintained roadmap after the registry refactor lands. Original prompt: > please pick a lowest hanging fruit from the current liyi next-steps, > is it LSP refactoring or injection refactoring? > okay, please first investigate the codebase and make a throwaway > roadmap in the docs/ directory and commit it before the real work. Human note: canonicalized model name and wrapped long lines in the commit message. AI-assisted-by: GPT-5.5 (OpenClaw) Signed-off-by: WANG Xuerui <[email protected]>
This is pure throwaway info not intended for human consumption (except for Git historians maybe), so no translation is needed. Let's conserve tokens by removing the Chinese translation from it... Signed-off-by: WANG Xuerui <[email protected]>
Record the streamlining plan for docs/liyi-design.md before editing it. The document accumulated duplicated reasoning, three overlapping milestone vocabularies (MVP/post-MVP, 0.1/0.2+, future direction), and revision-history narration over many rounds of multi-model review. The roadmap fixes the canonical "Deferred" vocabulary, lists the revision-history narration to strip, and catalogues the content- redundancy cuts as an ordered, one-commit-per-change sequence. The note is deliberately temporary and will be deleted once the series lands. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. > Before we begin, what do you think of the multiple mentions of > version numbers (MVP/post-MVP/post-0.1/post-0.2/...) in the doc? I > think most of them can be simplified a bit. > I agree with "deferred". As usual, let's document the revision > roadmap in a throwaway English-only doc first, then work through > everything (the versioning simplification plus the 1-12 bullet > points), one commit per each logical change. Additionally, please > document somewhere that this methodology of discussion -> English-only > throwaway roadmap -> implementation is to be used for major feature or > refactoring work. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Make the discussion -> English-only throwaway roadmap -> implementation workflow an explicit, repeatable expectation for major feature and refactoring work, rather than ad-hoc practice. Adds a "Planning major changes" subsection under Content workflows in both the English and Chinese contributing guides, covering the temporary docs/throwaway-*.md note convention (English-only, SPDX header, Status line) and the one-commit-per-logical-change implementation rule. Original prompt: > Additionally, please document somewhere that this methodology of > discussion -> English-only throwaway roadmap -> implementation is to > be used for major feature or refactoring work. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The design doc carried three overlapping schemes for out-of-scope work
(MVP/post-MVP, post-0.1/0.2+, "future direction"/"later release") plus
bare "in 0.1" hedges that add nothing because the whole document is the
0.1.0 design. Standardize on a single grep-friendly token, "Deferred",
distinguishing concrete next-steps ("Deferred to 0.2.0": LSP, MCP,
triage, challenge, --json) from speculative ideas ("Deferred
(speculative)": guarded_by, depends_on, import-reqif). Drop the
redundant "in 0.1"/"for 0.1" qualifiers where the sentence stands
without them.
Version numbers that are data are kept: schema "version" fields, the
liyi migrate 0.1->0.2 discussion, JSON Schema $id URLs, and the
tree_path grammar version. Risk #4's remaining version hedges are left
for the tree_path-brittleness compression commit.
Original prompt:
> Before we begin, what do you think of the multiple mentions of
> version numbers (MVP/post-MVP/post-0.1/post-0.2/...) in the doc? I
> think most of them can be simplified a bit.
> I agree with "deferred". As usual, let's document the revision
> roadmap in a throwaway English-only doc first, then work through
> everything (the versioning simplification plus the 1-12 bullet
> points), one commit per each logical change.
AI-assisted-by: Claude Opus 4.8 (GitHub Copilot)
Signed-off-by: WANG Xuerui <[email protected]>
Many rounds of multi-model review left changelog-style framing embedded in the specification: a "Design v8.12" header, a "v8.4 update:" prefix, two "Generalization update" paragraphs narrating how --prompt "used to be narrower," and dated parentheticals on Risk headings and analysis notes (2026-03-06, 2026-03-11, 2026-03-31, 2026-05-29). A spec should read in the present tense and describe the current design, not its edit history. Fold each into present-tense prose and drop the version stamps and dates. No substantive claim is removed. The document tagline date and the example generated-timestamps in sample output are left as-is (metadata and data, not narration). Original prompt: > I agree with "deferred". As usual, let's document the revision > roadmap in a throwaway English-only doc first, then work through > everything (the versioning simplification plus the 1-12 bullet > points), one commit per each logical change. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The Redmine->JIRA migration, read-only Confluence pages, and superseded design-docs litany was told in full at least three times: the abstract thesis in "The Idea", the concrete anecdote in "Origin", and again in the "Adoption Story" plus the project-management comparison. Keep the canonical full-color telling in "Origin" (where the billing/payment backstory gives it weight) and the abstract thesis in "The Idea", and compress the two redundant full retellings into cross-references. The unique "5%-of-decisions live in the most fragile layer" point is kept, just trimmed. No claim is lost. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The Adoption Story's closing pitch repeated, nearly word-for-word, the
two sentences that open "The Idea" ("captures the intent that exists in
people's heads ... doesn't compete with what your framework already
declares; it captures what your framework can't"). Keep the canonical
statement of the framework-vs-business-logic gap in "The Idea" and the
focused treatment in "Cross-cutting concerns", and trim the verbatim
restatement from the pitch so it carries only its unique closing thought
(review compression, staleness, adversarial testing).
Original prompt:
> please go through the liyi-design.md and identify streamlining
> chances -- the document underwent multiple rounds of reviews and
> iterative improvement from multiple models, and there may well be
> redundant reasoning and info here and there.
AI-assisted-by: Claude Opus 4.8 (GitHub Copilot)
Signed-off-by: WANG Xuerui <[email protected]>
The opening of "The Idea" had two consecutive paragraphs making the same
move: "AI writes your code. You can't read it all." and "AI agents write
most code. Humans review it but can't read it all." Merge them into a
single paragraph that keeps every distinct point — the AI-authorship
premise, the ephemerality of intent ("code is a fact; what it was meant
to do is a memory"), the 立意 value proposition, and the framework-gap
clause.
Original prompt:
> please go through the liyi-design.md and identify streamlining
> chances -- the document underwent multiple rounds of reviews and
> iterative improvement from multiple models, and there may well be
> redundant reasoning and info here and there.
AI-assisted-by: Claude Opus 4.8 (GitHub Copilot)
Signed-off-by: WANG Xuerui <[email protected]>
…item 4)
The "liyi never calls an LLM / the binary is the index, the agent is the
brain" principle is stated canonically in the Triage section
("Architectural principle" plus "Why the LLM is not in the binary").
The remaining mentions are contextually-appropriate one-liners (the
"What This Is / Is Not" lists are deliberately self-contained), so this
is a light touch rather than a large consolidation: the "What This Is"
triage bullet re-explained the principle in full, so replace its trailing
restatement with a cross-reference to the canonical statement.
Original prompt:
> please go through the liyi-design.md and identify streamlining
> chances -- the document underwent multiple rounds of reviews and
> iterative improvement from multiple models, and there may well be
> redundant reasoning and info here and there.
AI-assisted-by: Claude Opus 4.8 (GitHub Copilot)
Signed-off-by: WANG Xuerui <[email protected]>
The same five-axis comparison against Augment Code's Intent (durability, trust model, CI enforcement, adversarial testing, vendor neutrality) was spelled out twice: once in the "Why this and not X" bullet and again, at greater length and with the comparison table and funding context, in Risk #2 "Platform competition". Keep Risk #2 as the authoritative treatment and shrink the comparison bullet to its identifying description plus the four-tag summary, cross-referencing Risk #2 for the axis-by-axis detail. No distinct claim is lost. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Risk #6 (Agent reliability spectrum) and "The cognitive load inversion" section both make the "unreliable agents make the linter more valuable, not less" argument. The cognitive-load section is the canonical treatment (it develops the --prompt inversion, the MUST/SHOULD/REFERENCE tiers, and the value-proposition reframing in full). Keep Risk #6's unique content -- the five-problem diagnosis of why AGENTS.md is poorly optimized for weak models, and the action item -- and compress its second paragraph, which re-derived the cognitive-load section's "Implications", into a one-line statement plus cross-reference. Risk #6 already points to that section for the remedy. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The roadmap flagged a duplicated friction/conspicuousness table across "Source-Level Intent" and "Security Model", but the table exists only once (Security Model -> Two paths, two trust profiles). The real overlap is that the Source-Level Intent section previews the trust-model tradeoff that Security Model analyzes in full. Keep the mechanics framing in Source-Level Intent and cross-reference Security Model for the friction/conspicuousness analysis and the forgery threat model, so the canonical treatment lives in one place. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Risk #4 (source_span brittleness) re-explained the line-shift blast radius and the tree_path determinism story already covered in full by "Per-item staleness via source_span" and "Structural identity via tree_path". Collapse the duplicated mechanics into a one-paragraph layered-mitigation summary plus a cross-reference, and keep the unique residual-friction note (the lockfile-conflict analogy for items without a tree_path). Also drop the leftover "in 0.1" / "Rust in 0.1" / "Mitigation in 0.1" version hedges, consistent with the milestone vocabulary cleanup -- tree_path and Rust support are current behavior, not deferred. Original prompt: > please go through the liyi-design.md and identify streamlining > chances -- the document underwent multiple rounds of reviews and > iterative improvement from multiple models, and there may well be > redundant reasoning and info here and there. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The "Adoption paths: greenfield vs. brownfield" narrative re-enumerated the _hints signal set (body size, docstring presence, trivial suggestion) that the "liyi init" command reference and the "_hints -- cold-start inference aids" section already cover in full, with the latter owning the canonical signal table and lifecycle. Compress the brownfield paragraph to a short characterization plus cross-reference, keeping its unique adoption-narrative content (incremental review strategy, linter-as-progress-tracker). Also drop the "VCS-derived signals are planned for a future release" clause, which conflicted with the _hints section that already lists commits/fix_commits as example signals -- the cross-referenced section is now the single source of truth for what hints contain. Original prompt: > Which of the softer/optional cuts (items 9-12) should I do? > [selected: items 9, 10, 11, 12] AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The "--prompt extends beyond coverage gaps to stale/shifted/unreviewed/ requirement-changed items" enumeration appeared twice: once as "--prompt scope" in the --prompt mechanics section and again as "--prompt as operational contract" in the cognitive-load section. Keep the scope enumeration in the mechanics section (its natural home) and compress the cognitive-load instance to its unique framing -- --prompt as the operational contract carrying the *what* while behavioral rules remain human-facing documentation of the *why* -- with a cross-reference for the diagnostic set. Original prompt: > Which of the softer/optional cuts (items 9-12) should I do? > [selected: items 9, 10, 11, 12] AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The paragraph introducing the "=trivial" sentinel spelled out the same source-vs-sidecar / no-entry-vs-entry / invisible-vs-tracked comparison that the immediately-following "When to use which" table tabulates more scannably. Trim the intro to a single motivating sentence and let the table carry the comparison. The "Who/Form/Meaning" table is left intact -- it consolidates intent forms introduced across several sections and is not redundant with its preceding prose (which covers only =doc). Original prompt: > Which of the softer/optional cuts (items 9-12) should I do? > [selected: items 9, 10, 11, 12] AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The "self-reference is not accidental" fixpoint paragraph re-listed the dogfooding facts its own section intro (~28 lines above) had just stated: the design doc's @liyi:requirement blocks tracked via @liyi:related edges, and CI running liyi check on its own source. Drop those repeated clauses ("Beyond the dogfooding above, ...") and keep the paragraph's unique fixpoint instances -- the AGENTS.md instruction being itself a spec, and intent-first orchestration being liyi applied to its own development. The two standalone "Dogfooding" bullets (testing strategy vs. success criteria) are left as-is: they serve different sections with different framings and are self-contained one-liners. Original prompt: > Which of the softer/optional cuts (items 9-12) should I do? > [selected: items 9, 10, 11, 12] AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The design-doc streamlining series (milestone vocabulary, revision- history strip, and content-redundancy items 1-12) has landed. Per the throwaway-roadmap workflow, delete the temporary planning note now that its commit sequence is complete. Original prompt: > let's document the revision roadmap in a throwaway English-only doc > first, then work through everything (the versioning simplification > plus the 1-12 bullet points), one commit per each logical change. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Re-anchor requirement spans and re-hash the three requirement blocks whose text changed during the streamlining series. Most spans simply shifted by -2 lines (content-stable, hashes unchanged); version-field- required, source-span-semantics, and span-shift-heuristic picked up new source_hash values because the milestone-vocabulary and item-8 edits altered their block prose. Produced by `liyi check --fix`; `liyi check docs/liyi-design.md` is now clean. Original prompt: > please sync sidecars after the revision AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The code didn't change and the spec didn't get changed semantically either. Signed-off-by: WANG Xuerui <[email protected]>
Update Risk #2 (Platform competition) and the three cross-references to reflect Augment Code's 2026 trajectory, verified against public sources (augmentcode.com, the auggie CLI's public repository -- documentation, changelog, and examples, not source -- the Context-Engine MCP plugin, and the review-pr GitHub Action) rather than the now-stale "Intent desktop app" framing. Root cause of the staleness: the prior text described Augment's "Intent" workspace as a live, head-to-head competitor with a tracked version (0.2.18). That product has been deprecated (its page survives only as an orphaned vercel.app preview); the company pivoted to Cosmos (org-scale agent orchestration) and repackaged its Context Engine as an MCP retrieval layer that plugs into competitors' agents. Two differentiators were factually wrong as written: - #3 claimed "Augment has no standalone linter / CI." False: the auggie CLI runs in CI (--print/--quiet) and ships PR-review actions. Reframed as hosted, non-deterministic LLM judgment behind a personal OAuth token vs. liyi's deterministic, offline, hash-based staleness gate. - #5 claimed "Augment specs live inside Augment." Narrowed: with MCP/ACP and published SDKs their tooling interoperates broadly; the durable distinction is the absence of a portable, human-reviewed spec-file convention, not tooling lock-in. Recalibrated urgency honestly: the direct intent-persistence competitor receded rather than consolidated, lowering urgency on liyi's axis, but the company is not slow or failing -- the threat moved categories (retrieval + enterprise orchestration), it did not disappear. Dropped the stale 0.2.18 version cell; kept the $227M+ funding as a disclosed floor (no newer figure confirmable). The auggie CLI is not open source -- its GitHub repository hosts only documentation and the issue tracker, while the program ships as an obfuscated bundle; this commit did not reverse-engineer or otherwise derive anything from that bundle, and all claims rest on public artifacts. Original prompt (abridged; portions concerning the auggie CLI binary redacted at the author's request, and an author self-correction folded in): > [...] In the CLI/tooling landscape they're actually *competing* for the > *agentic work entrypoint*, where it's usually `claude`, `codex`, > `copilot`, `opencode` etc. already and is a *fierce* competition. I don't > think they will ever win against those AI giant products on that front, > they've chosen the wrong battle to fight. > > Hmm, I have fetched their MCP plugin in `tmp/context-engine-plugin`. You > may want to look at it before maybe updating your opinion. > > There's a GitHub Action in `tmp/review-pr` which we can trivially do (we > already dogfood in our GHA PR workflow, just not extracted into a > standalone action repo). [...] > > [Author self-correction: the auggie utility is not open-source -- its > GitHub repo only hosts documentation and the issue tracker; earlier > references to an "open-sourced" auggie were mistaken.] > > Go ahead. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Add a sentence to Risk #2 making explicit that Augment's Context Engine, in its current iteration, is a hosted retrieval service (the MCP plugin authenticates to an Augment tenant and calls server-side embedding/retrieval models; no offline mode, subscription required) and that it is descriptive -- it answers "where is this / how does this work" against the code's current state -- which is orthogonal to liyi's prescriptive "what should this do, and has it drifted." Frames the two as potentially coexisting in one MCP host rather than as competitors. Scoped deliberately: claims only what the public MCP plugin and review-pr action evidence (hosted, credential-bound, no offline path). Avoids the unverifiable speculation that the engine "was never local from day one" and avoids an over-optimistic "so we win" framing -- the point is a different axis (descriptive retrieval vs. prescriptive intent), not a value judgment. Original prompt: > do we need to emphasize that the Context Engine in its current iteration > is entirely cloud-based, not a local component, and may not be the case > from day one, so that we're going to fare better? > > I agree. Please make a separate commit for this change. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
…roadmap The throwaway LSP refactor roadmap under-sold the main payoff of the RequirementRegistry extraction and left the registry's eventual field set ambiguous, which could mislead an implementer. Add a "Duplication to be aware of" subsection documenting that approve.rs already reimplements the pass-1 requirement pipeline with a different field set (RequirementInfo vs RequirementRecord), and note that the unified record should be a superset exposed via accessors. Annotate the RequirementRegistry struct to retain both req_dep_graph (input) and requirement_cycles (output), and list which post-pass emitters consume which collections so a refactor does not collapse requirements_referenced and source_related_refs (which would change diagnostics). Expand the deferral note for approve.rs unification with its rationale. Docs-only; no Rust changed. Original prompt: > So is the roadmap good as-is? > > Yes please make the roadmap edits first. > > Please commit first then go ahead implement it. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Tier 1 of the throwaway LSP refactor roadmap. The linter's pass-1 requirement state was prepared inline in run_check() and threaded through helpers as a handful of loose maps and sets, which an LSP server cannot cache or reuse. approve.rs independently reimplements the same pipeline, so the runtime context was effectively duplicated. Introduce a public RequirementRegistry bundling the requirements map, the side-collections (requirements_with_sidecar, requirements_referenced, source_related_refs), the dependency graph, and the precomputed cycles. Expose build_requirement_registry() (pass 1) and check_sidecars() (pass 2, taking a prebuilt registry) as the reusable library seam, and keep run_check() as the behavior-preserving CLI wrapper that now delegates through them via a small emit_registry_diagnostics() helper. Rename the private check_sidecar() to check_one_sidecar() to avoid a public/private name collision. RequirementRecord becomes public. No behavior change: run_check() remains the test oracle and all 38 golden tests plus the unit/proptest suites pass unchanged. The registry fields stay private for now; read accessors can be added when the LSP has concrete call sites. approve.rs unification is deferred per the roadmap. Sidecar specs updated for the new/renamed items. The two reviewed specs whose source changed cosmetically (RequirementRecord doc comments + pub, the check_one_sidecar rename) keep their unchanged intent and are left for human rehash; the new public API specs carry agent-written intent with reviewed unset, pending human review. Original prompt: > So is the roadmap good as-is? > > Yes please make the roadmap edits first. > > Please commit first then go ahead implement it. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Clippy's collapsible_if fired on the triple-nested if let in the YAML test helper find_pair_by_key. Collapse the kind check and the two if let bindings into a single let-chain, matching the let-chain style used elsewhere in the crate. Test-only helper; no behavior change. Original prompt: > please fix clippy warnings first in a separate commit, then investigate > the `liyi approve` bug -- reduce into a regression test case if possible > and fix it. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
`liyi approve <source.rs>` failed with "failed to parse sidecar file: expected value at line 1 column 1". The CLI help advertises that approve accepts "Sidecar files, source files, or directories", but `resolve_sidecar_targets` pushed any `is_file()` path through verbatim. A source file therefore reached `parse_sidecar`, which tried to read Rust source as JSON and failed on the first byte. The `--stale-only` path made this visible because it skips `build_requirement_registry` and goes straight to the per-target parse loop. Root cause: `resolve_sidecar_targets` only distinguished directories from files, not sidecars from source files. Fix: when a file does not end in the sidecar suffix, treat it as a source file and map it to its canonical co-located `<filename>.liyi.jsonc` via `sidecar_path_for_source`, erroring clearly if that sidecar does not exist. Sidecar files are still passed through directly. A source file is now never returned verbatim, so `parse_sidecar` never receives source code. Adds regression tests covering sidecar pass-through, source-to-sidecar mapping, and the missing-sidecar error. Original prompt: > please fix clippy warnings first in a separate commit, then investigate the `liyi approve` bug -- reduce into a regression test case if possible and fix it. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Introduce a phony `make lint` target that runs the three pre-commit lint gates matching CI: `cargo fmt --all -- --check`, `cargo clippy --workspace -- -D warnings`, and the project's own `cargo run -p liyi-cli -- check --root .` self-check. Also adds a `test` target for `cargo test --workspace`. Collapse the per-command lint instructions in AGENTS.md, CONTRIBUTING.md, and both contributing guides into a single `make lint` reference so the guidelines stay shorter and have one source of truth for the gate. Original prompt: > BTW please consolidate pre-commit lint steps you have run into a phony `make lint` rule, so that various contributing guidelines including AGENTS.md can be a bit shorter. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Signed-off-by: WANG Xuerui <[email protected]>
Update both language editions of the review-compression evidence doc to the 2026-05-31 snapshot (53 source files, 15,682 source lines, 173 specs, 30.5x reduction) and document a newly observed phenomenon: GitHub Actions workflows and schema.rs exhibit review *inflation* rather than compression. The inflation is counter-intuitive but important. Most code is a translation of a formal system, so the source is its own specification and intent prose compresses hard. Contractual and ops-heavy code is the opposite: its correctness depends on implicit knowledge (least-privilege rationale, operational invariants, version contracts) that the formal artifact deliberately omits, so the sidecar becomes the only written record and inflates past 100%. Inflation therefore flags the files where skipping the spec is most dangerous. Original prompt: > now update the Review Compression document with latest data -- I > noticed a new insight that the GHA workflows and `liyi/src/schema.rs` > have *review inflation* instead of compression, and this is > counter-intuitive but important: contractual and ops-heavy code rely on > implicit knowledge much more than regular code that's basically > translation of formal systems. > > please mirror the changes to the Chinese version too and commit them AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The 30.5x compression figure is measured on liyi's own codebase, which is the most favorable possible subject rather than a representative sample. Without an explicit caveat the number is easily misread as a general claim about intent-spec review compression. Add a "Threats to validity" section (both language versions) naming the three confounds that make the result a best case: reverse causality (the code was LLM-compiled from a pre-existing design doc, so specs sit upstream of source instead of being recovered from it), the greenfield luxury of 100%-reviewed specs, and the exclusion of bootstrapping cost entirely. The section states the narrow honest claim and points to the brownfield experiment that would actually speak to existing-project adoption. Original prompt: > Maybe yes, our own evidence is actually an outlier because we're > practicing our own convention from day one -- polished design doc from > the start and everything bootstrapped i.e. LLM-"compiled" from it. Most > brownfield projects need any doc to be written at all. > > yeah, please, document it in both language versions and commit it, and > see if the FLOSS maintenance perspective has a place in the design doc. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Maintainers of open-source projects triaging AI-generated contributions are a distinct audience for the convention, and the question of whether liyi helps absorb that load was not addressed in the design doc. Add an "open-source maintenance perspective" subsection to the Adoption Story. It argues the structural case from the inflation finding (pure LLM inference compresses where compression is cheap and misses the implicit-contract code where review matters most), resolves the cold-start double-edged sword into an inference-then-promote pipeline whose durable wedge is the reviewed-intent ratchet, restates the guesser-must-not-be-the-verifier boundary as a trust property (so the liyi binary should not call an LLM), frames presentation tools like Sourcery as a layering opportunity rather than a rival, and names the honest open risk: promotion cost on adversarial external PRs is the number this audience needs and the evidence does not yet provide. Links to the evidence doc's new threats-to-validity section. Original prompt: > Do you think the project would help in smoothing acceptance of > AI-written code in open-source projects that so often have burned out > maintainers [...] the tool needs requirement docs to be written and > intents extracted *before* the tide of AI slop arrives [...] maybe we > can have a GHA (or other CI) workflow that *calls LLM to infer intents* > [...] The `liyi` binary should not call LLM [...] As for Sourcery > reviews, they are *not* only comprised of suggestions; they *edit your > PR description* [...] they probably need steering for sensing and > outputting the implicit contracts and knowledge if they can reliably do > it at all. > > yeah, please, document it in both language versions and commit it, and > see if the FLOSS maintenance perspective has a place in the design doc. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
…rement The LSP library refactor (extracting the public RequirementRegistry pass API) fulfils the `lsp-check-refactor-exposes-registry` requirement in docs/lsp-design.md, but no item referenced it, so `liyi check` reported the requirement as unreferenced. Add a `@liyi:related` edge from `build_requirement_registry` to that requirement and record it in the sidecar so the now-implemented requirement is tracked. Original prompt: > now check if the LSP library refactor roadmap is complete, and continue if not, commit along the way. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
The public RequirementRegistry pass API has landed, so next-steps items 2.3 and 2.4 are complete. Mark them done with a status note mirroring 2.2, and delete docs/throwaway-lsp-refactor-roadmap.md, which by its own header was a temporary planning note to be removed once the refactor landed. Its done criteria and API shape are now captured by the lsp-design.md requirements and the next-steps status note. Original prompt: > now check if the LSP library refactor roadmap is complete, and continue if not, commit along the way. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Running the gates previously gave no clear pass/fail signal: `make lint` always prints the linter's full item listing, so confirming success meant redirecting output to a log and echoing `$?`. Add a final success banner to each gate (`lint: all gates passed`, `test: passed`, `verify: all gates passed`) — Make aborts at the first failure, so the banner only prints on a clean run and is a reliable success signal without inspecting the exit code. Add a combined `verify` target that runs the lint gates plus the test suite. Update AGENTS.md, CONTRIBUTING.md, and both contributing guides to point at `make verify` and explain the banner convention so the check is reproducible by hand and by agents. Original prompt: > Okay. I noticed you were using `make lint > /tmp/lint.log 2>&1; echo "EXIT=$?"; ...` tricks so often, maybe you need to consolidate that into the Makefile and agent contribution instructions so that this part can be automated. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Agents pipe `make lint` into a log and grep the exit code to avoid drowning in the linter's full item listing and to conserve their context window. Bake that pattern into the Makefile instead: `lint-short`, `test-short`, and `verify-short` run the same gates as their full counterparts but suppress normal output, printing only a banner on success. On failure they print a bounded tail of the offending gate plus the full `make <gate>` target to re-run for complete diagnostics, so a failing agent is told exactly how to get the details rather than re-deriving a redirect-and-echo pipeline. Call this out explicitly for AI agents in AGENTS.md, both contributing guides, and the CONTRIBUTING.md checklist, while steering human contributors to the full `make verify` / `make lint`. Original prompt: > Not exactly -- I mean you and other AI agents do this presumably because you are trying to conserve tokens for your user, and for yourselves to not drown in error logs should anything go awry. This is horrifying only for agents and not for the (experienced) human contributors, so you could add a phony rule like `make verify-short` that has various quiet options and/or `tail` built in, and in case that fails, prompt the invoker to call the full command respectively. This should be explicitly called out for agents consuming the AGENTS.md and contributing guide. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
Signed-off-by: WANG Xuerui <[email protected]>
Signed-off-by: WANG Xuerui <[email protected]>
Wire tree-sitter-proto into the tree_path structural-identity system so .proto files participate in `liyi init` discovery and `liyi check` resolution like the other built-in languages. - Add lang_proto module: name extraction for message/enum/service/rpc and field/oneof/map_field members, doc-comment detection, and the Protobuf LanguageConfig (kind map, "." body sentinel, transparent message_body/enum_body containers). - Register Proto in the Language enum, config(), detect_language(), language_from_name(), and language_to_name(). - Only treat *named* nodes as item nodes. Proto's grammar emits anonymous keyword tokens whose kind() collides with a named node kind (the 'rpc' keyword token reports kind() == "rpc", same as the named rpc node); requiring is_named() stops those zero-width tokens from shadowing the item they introduce. Original prompt: > Please implement tree_path and `liyi init` etc. support for the Protobuf file format, with the already introduced `tree-sitter-proto` crate. Please commit as you work. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
`liyi init <file>` silently wrote an empty `"specs": []` scaffold when
the file's extension mapped to no supported tree-sitter grammar, making
an un-analyzable file indistinguishable from a genuinely empty one — the
same silent-zero-items failure mode noted in the brownfield field notes.
When discovery is requested but `detect_language` returns None, the CLI
now prints a note after creating the sidecar:
note: unsupported file format (.xyz); no items discovered
— wrote an empty scaffold for manual authoring
This is a presentation-layer change only: `init_sidecar`'s library API is
unchanged, so no test churn. Verified the note prints for an unsupported
extension and stays silent for a supported one.
The `main` spec is `=doc`; its docstring (the intent) is unchanged and
the added behavior is consistent with "dispatches to sub-commands," so
the reviewed spec was re-anchored against the shifted source rather than
unreviewed.
Original prompt:
> Yeah, you can document the desensitized findings, plus maybe improve
> the signaling of `liyi init` (let it report "unsupported file format;
> items not discovered" somehow would suffice I think). Please commit
> separately.
AI-assisted-by: Claude Opus 4.8 (GitHub Copilot)
Signed-off-by: WANG Xuerui <[email protected]>
`measure-intent-ratio.py` previously counted prose lines as `characters ÷ 80`, which silently understates the on-screen review surface for CJK-heavy intent: a fullwidth character occupies two terminal columns but counted as one. The new `--display-width`/`-w` flag computes prose volume in terminal columns (via `unicodedata.east_asian_width`, W/F = 2 columns), so corpora whose intent prose is mostly Chinese are measured the way a human actually reads them. The default character basis is retained for backward comparison; the report labels which basis it used. `main()` now separates the positional ROOT argument from the flag so either invocation order works. Original prompt: > in case you forgot, the majority of the inferred intents are in > Chinese, and one Chinese character takes 2 rows to display on a > terminal, so maybe the equivalent number of prose lines should get > adjusted. Human note: changed scope from "docs" to "meta" like a previous commit. AI-assisted-by: Claude Opus 4.8 (GitHub Copilot) Signed-off-by: WANG Xuerui <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.