llmrecog

llmrecog is a source-bounded semantic recognition DSL and local-first tool. It records what an input supports without turning that recognition into a new hypothesis, conclusion, decision, or execution plan.

Its User may be a human or an external LLM-based agent such as a coding agent. Both use the same explicit commands and typed input/output contracts. llmrecog does not contain, select, or call an LLM or model provider.

unstructured or weakly structured input
                  |
                  v
        source-grounded recognition
                  |
                  v
       structured semantic state

The project has a design baseline, a frozen executable contract for text profile 0.1, and a private read-only dogfood path for parse, validate, show, bounded explanation, focused audit, query, materialization, and fail-closed local source verification. The private draft review route now composes those checks over a User-supplied draft, with optional external Producer v1 evidence, and returns a User-neutral review-readiness result. Its deterministic core evaluates all five contract-0.1 constraint kinds, and the Phase 5 local- verification slice is accepted locally. Public CLI Contract 1 and its package surface are now implemented and rehearsed locally through the same application/ core seams. No retained release candidate, package publication, compatibility release, or formatter exists. The source extension is .recog. ADR 0017 additionally freezes private consumer-neutral typed recognition- reference and grounding-check schemas. ADR 0018 and the private grounding check route now add reproducible direct-record projection identity, rooted read-only reference resolution, and factored claim evaluation. Repeated protocol-v19 dogfood, its feedback, and the dogfood-first roadmap acceptance are complete locally. ADR 0019 accepts public CLI Contract 1 and the minimal package boundary for the first beta; its implementation remains local and unpublished.

Product boundary

The three related projects have intentionally different responsibilities.

| Layer | Primary question | Owns | Does not own | | --- | --- | --- | --- | | llmrecog | What does the input support as meaning? | entities, relations, properties, intent, normalization, ambiguity, provenance, source-bounded constraints | hypotheses, deliberative inference, conclusions, decisions | | llmthink | What follows from what we know? | premises, evidence, alternatives, inference, comparison, conclusions, decisions, pending questions | claiming that an inferred result was present in the original input | | perttool | How is an accepted decision realized? | milestones, tasks, dependencies, resources, estimates, acceptance, execution state | recognizing source meaning or deciding what follows from it |

The intended flow is:

original source
  -> llmrecog recognition
  -> llmthink premise/evidence
  -> llmthink inference/decision
  -> perttool milestone/task/execution state

The arrows carry provenance. They do not grant permission to write results back into an earlier layer.

Core principles

• Source bounded: a semantic record must stay within what its cited input supports. A false statement can be recognized as a statement made by the source; it is not thereby certified as a world fact.
• Ambiguity preserving: do not pick one reading merely to simplify output.
• Factorized possibility space: represent ambiguity as variables, candidates, and constraints rather than eagerly enumerating interpretation worlds.
• Open world: absence is neither negation nor support. Unknown is a valid result.
• Two-axis candidate state: source support and constraint viability are separate. A candidate can be source-supported yet inconsistent, or solver- viable without positive source support.
• Explainable propagation: every exclusion must have a source-grounded constraint and a deterministic reason chain.
• User-neutral deterministic tool: human and external LLM-based Users call the same command and data contracts; no llmrecog runtime invokes an LLM or model provider.
• Local-first and diff-friendly: text artifacts are the source-controlled authority; no server, model provider, or database is required to inspect or validate them.

Design documents

• Requirements
• Terminology
• Architecture and responsibility boundary
• Non-goals
• Semantic model and ambiguity semantics
• Provenance and explainability
• DSL contract 0.1
• Normative EBNF and recovery contract
• Canonical formatting
• Diagnostics and reason codes
• JSON Schemas
• Contract fixture manifest
• Local source-verification fixtures
• External-producer evidence fixtures
• User-draft review fixtures
• Typed reasoning-handoff fixtures
• CLI contract
• Public CLI and package contract
• Public CLI and package implementation acceptance
• Packed beta artifact rehearsal acceptance
• 0.1.0-beta.1 release notes
• llmthink integration
• Recognition-aware llmthink grounding audit
• Boundary cases
• Phased implementation proposal
• Dogfooding roadmap acceptance
• Accepted product and release roadmap
• Design self-review
• Prior-art review
• Development setup
• Development method
• Dogfooding workflow
• Governed release procedure
• Internal dogfood protocol
• Architecture decisions

Current scope lock

Phase 5 and the private deterministic User-draft review slice are accepted locally. ADR 0013 freezes optional external-producer evidence, ADR 0015 defines the external User actor, and ADR 0016 freezes draft review plus Llmrecog.DraftReviewResult.v1. No llmrecog runtime calls an LLM or provider. Protocol v17 dogfood through that same contract is complete with no unresolved observation. ADR 0017 and ADR 0018 freeze the typed, read-only handoff contract and canonical direct-record identity. The private prototype, repeated protocol-v19 dogfood, feedback review, and dogfood-first roadmap acceptance are complete locally. Automatic repair, llmthink repository changes, retained candidate preparation, and writes remain outside the accepted slice. The accepted product-release roadmap treats completed private milestones as qualification evidence and places the first installable public surface at 0.1.0-beta.1, followed by installed-package dogfood, a compatibility-frozen release candidate, and stable 0.1.0. ADR 0014 fixes MIT, unscoped llmrecog, and intended publisher mako10k ([email protected]). ADR 0019 fixes the first public read-only command, JSON discovery, format/default, exit-status, bin/export, schema-allowlist, installation, and support contracts. That surface is implemented and its disposable packed-artifact rehearsal is accepted locally at target metadata version 0.1.0-beta.1. Candidate-source metadata now selects public access and the beta dist-tag without selecting latest; the release procedure and an exact-candidate approval still gate every external write. The roadmap, local rehearsal, candidate metadata, and release notes are not a release, date, retained candidate, publication, or external-write authority.

Development

The initialized repository uses Node.js 22 or 24, npm, strict TypeScript, ESM, the Node.js test runner, ESLint, and Prettier. The package has target metadata version 0.1.0-beta.1, one local public CLI bin, no production dependencies, and remains unpublished.

npm ci
npm run check
npm run check:package
npm run rehearse:package
git diff --check
npm run build
node dist/cli.js version --format json

See Developing llmrecog and the repository-wide guidelines. The executable contract tests validate schemas, goldens, diagnostics, EBNF coverage, boundary fixtures, and the actual private parser/model/explain/audit seams.