lore-usage

name	lore-usage
description	Use when recording architectural decisions, querying decision context, validating Lore metadata, or creating Lore-enriched commits in SSPU-AllinOne. Covers local lore status compatibility and required trailer shape.

Lore Usage

Lore Protocol records structured decision context in git commits. Use it for every agent-made commit in this repository.

Setup

lore --version
npm install -g lore-protocol
lore init

lore init is one-time per clone. Do not reinitialize unless .lore/ is missing or broken.

Query Decision Context

lore context <file>
lore constraints <file>
lore rejected <file>
lore directives <file>
lore why <file>:<line>
lore search --text "keyword"

Use these before changing code governed by existing constraints.

Create A Commit

Preferred interactive path:

lore commit -i

AI / scripted path:

printf '%s\n' '{
  "intent": "fix(ci): 修复 Scorecard 固定 SHA",
  "body": "Pin the action to the peeled v2.4.3 commit so source verification resolves to the upstream repository.",
  "trailers": {
    "Constraint": ["Scorecard action must be pinned to the commit object, not the annotated tag object."],
    "Confidence": "high",
    "Scope-risk": "narrow",
    "Tested": ["python scripts/ci/validate_github_governance.py"]
  }
}' | lore commit

Keep the commit title in normal repo format: type(scope): 中文摘要.

Trailer Rules

Lore trailers must be contiguous at the end of the commit message. Do not place ordinary body text after trailers.

Useful trailers:

Trailer	Values	Purpose
Constraint	free text	External rule or invariant that shaped the change
Rejected	`	`
Confidence	low / medium / high	Author confidence
Scope-risk	narrow / moderate / broad	Blast radius
Reversibility	clean / migration-needed / irreversible	Undo difficulty
Directive	free text	Future maintainer warning
Tested	free text	Verification run
Not-tested	free text	Known verification gap

Lore-id is generated by Lore. Preserve it when amending unless Lore regenerates it.

Status And Validation

lore-protocol@0.5.0 may not include a built-in lore status command. Use the repository helpers:

pwsh ./scripts/lore/status.ps1

bash ./scripts/lore/status.sh

Equivalent manual checks:

git status --short --branch
lore doctor
lore validate HEAD~1..HEAD

For a PR range, validate the exact base/head range when known:

lore validate origin/develop..HEAD

Common Pitfalls

• Do not confuse branch prefix bugfix/ with commit type fix.
• Do not run lore validate without a range when only the new commits need checking.
• If the local lore status shim fails, use scripts/lore/status.ps1 or scripts/lore/status.sh and mention the shim gap only if it affects the user.
• Keep Tested: and Not-tested: honest; a skipped platform build is a Not-tested: entry, not implied coverage.