@litfamily/lithermes 1.0.8 → 1.0.9

package/assets/lithermes-plugin/skills/lit-humanizer/examples/slides/after.md

@@ -0,0 +1,19 @@
+# Water-quality pilot
+
+## 1. Sampling period
+The pilot ran from 1 June through 30 June 2026.
+
+## 2. Three river sites
+Staff collected samples at North Bridge, Market Bend, and South Weir.
+
+## 3. Sample count
+Each site contributed 24 samples; the total was 72.
+
+## 4. Lab flags
+The lab flagged 2 North Bridge samples and 3 South Weir samples for a second review. None from Market Bend were flagged.
+
+## 5. Follow-up
+The second review is scheduled for 8 July. The pilot has no assigned owner for the field follow-up.
+
+## 6. Scope
+The pilot records results at these three sites. It does not estimate river-wide conditions or establish a health effect.

package/assets/lithermes-plugin/skills/lit-humanizer/examples/slides/before.md

@@ -0,0 +1,19 @@
+Let's dive in to the water-quality pilot.
+
+## Slide 1 — Sampling period
+The pilot ran from 1 June through 30 June 2026.
+
+## Slide 2 — Locations
+Staff collected samples at three river sites: North Bridge, Market Bend, and South Weir.
+
+## Slide 3 — Sample count
+The team collected 24 samples at each site, for 72 samples total.
+
+## Slide 4 — Lab flags
+The lab flagged 2 samples from North Bridge and 3 from South Weir for a second review. No samples from Market Bend were flagged.
+
+## Slide 5 — Follow-up
+The lab scheduled the second review for 8 July. The pilot has not assigned an owner for the field follow-up.
+
+## Slide 6 — Boundary
+The pilot records sample results at the three sites. It does not estimate river-wide conditions or establish a health effect.

package/assets/lithermes-plugin/skills/lit-humanizer/examples/troubleshooting/after.md

@@ -0,0 +1,11 @@
+# Upload requests return 429
+
+The API allows 60 requests per minute per account. A 429 response includes a Retry-After header with the number of seconds to wait before sending another request.
+
+Read that header and pause for the stated interval. For example, if the value is 30, wait 30 seconds before retrying:
+
+~~~sh
+curl -i -X POST https://api.example.test/uploads
+~~~
+
+The rate limit resets every minute. Check the account's request count in the dashboard if 429 responses continue after the wait. Contact support if repeated 429 responses persist.

package/assets/lithermes-plugin/skills/lit-humanizer/examples/troubleshooting/before.md

@@ -0,0 +1,11 @@
+Certainly! Here is a comprehensive guide to resolving upload errors.
+
+If the API returns 429, it means that the request rate is too high. The service accepts up to 60 requests per minute for each account. The response includes a Retry-After header with the number of seconds before another request can be sent.
+
+First, it is important to check whether your client reads this header. Then, you can implement a robust retry strategy. The following example uses a 30-second delay:
+
+~~~sh
+curl -i -X POST https://api.example.test/uploads
+~~~
+
+If errors continue, check your account's request count in the dashboard. The rate limit resets every minute. Contact support if your client receives repeated 429 responses after following these steps. Let me know if you'd like me to provide an example in another language.

package/assets/lithermes-plugin/skills/lit-humanizer/references/README.md

@@ -0,0 +1,16 @@
+# LitHumanizer references
+
+Use the router in `SKILL.md` first. Load only the guide needed for the edit.
+
+| Need | Read |
+|---|---|
+| Process and meaning-preserving rewrite | [rewrite-playbook.md](rewrite-playbook.md) |
+| Deliverable vs chat boundaries | [deliverable-channels.md](deliverable-channels.md), then [taxonomy.md](taxonomy.md) |
+| English line, content, or structure | [en-patterns.md](en-patterns.md), [en-patterns-content.md](en-patterns-content.md), [en-patterns-structure.md](en-patterns-structure.md) |
+| Full English pass | [en-patterns-checklist.md](en-patterns-checklist.md) |
+| Korean pattern families | [ko-patterns.md](ko-patterns.md), [ko-patterns-a-d.md](ko-patterns-a-d.md), [ko-patterns-e-j.md](ko-patterns-e-j.md) |
+| Korean metrics | [ko-metrics.md](ko-metrics.md); counts are advisory |
+| Code, comments, README, changelog, commit, or PR prose | [code-patterns.md](code-patterns.md) |
+| Bundled always-on reminder | [always-on-rule.md](always-on-rule.md) |
+
+`rules.json` supplies the Python detector. `scripts/detect.py` accepts text, DOCX, PPTX, and PDF when the host provides `pdftotext`. `scripts/extract_office_text.py` exposes extraction alone. `scripts/ko_metrics.py` reports descriptive Korean signals. Examples are paired under `../examples/`; reusable report and slide text skeletons are under `../assets/`.

package/assets/lithermes-plugin/skills/lit-humanizer/references/always-on-rule.md

@@ -0,0 +1,9 @@
+# Always-on rule: lit-humanizer
+
+Apply to new text you write in chat or files. Check only new or changed model text; preserve existing file text and exact user quotations. Skip code fences, inline code, and internal records. Load the full skill for long deliverables, explicit rewrites, or Korean deep work.
+
+Block only clear drafting residue: evidence/source label lines, stacked caveats, model disclaimers, and chatbot sign-offs. Warn on vocabulary, contrast, triads, and rhythm; revise only when voice and genre improve.
+
+Use footnotes or reference lists for citations, never label-only lines. State material risk once, plainly, in chat, not in the deliverable body. Keep internal evidence, plans, ledgers, handoffs, status, and JSON detailed.
+
+Review code comments, commit/PR/README text, and code shape. Remove narration or a one-use wrapper only if behavior and trust-boundary checks stay intact. Preserve facts, numbers, names, quotes, citations, and meaningful qualifiers. Run the detector on new text; fix blocks.

package/assets/lithermes-plugin/skills/lit-humanizer/references/code-patterns.md

@@ -0,0 +1,468 @@
+# Code and developer-writing patterns
+
+Treat comments, docstrings, commit messages, pull requests, READMEs, and changelogs as prose. Treat executable structure as code review, not style cleanup. A shorter implementation is not automatically better.
+
+## Safety boundary
+
+Keep validation at untrusted input boundaries, checks that prevent corruption, error handling that preserves data, permission checks, accessibility behavior, cleanup on failure, and checks for real platform variation. Remove a branch only when the upstream type or contract guarantees the value. A detector warning is not static-analysis proof.
+
+## CODE-01 | Comments that narrate the next line
+
+- What / why: A comment repeats the operation without explaining why it exists.
+- Detect: Compare the comment with the next statement. If the code fully answers it, remove the comment.
+- False positives: Keep rationale, invariants, protocol notes, compatibility reasons, and surprising constraints.
+- Evidence: weak as an authorship clue; useful as a maintenance check.
+
+JavaScript / TypeScript:
+
+~~~js
+// Bad
+// Increment the attempt counter.
+attempt += 1;
+
+// Better
+attempt += 1;
+~~~
+
+~~~ts
+// Bad
+// Return the user name.
+return user.name;
+
+// Better
+// Preserve the API's null result for deleted users.
+return user.name ?? null;
+~~~
+
+Python:
+
+~~~python
+# Bad
+# Add one to the retry count.
+retries += 1
+
+# Better
+retries += 1
+~~~
+
+~~~python
+# Bad
+def load(path):
+    """Load a file."""
+    return path.read_text()
+
+# Better
+def load(path):
+    """Read UTF-8 config text; callers validate its schema."""
+    return path.read_text(encoding="utf-8")
+~~~
+
+Shell:
+
+~~~sh
+# Bad
+# Create the output directory.
+mkdir -p "$out_dir"
+
+# Better
+mkdir -p "$out_dir"
+~~~
+
+~~~sh
+# Bad
+# Run the migration.
+./migrate.sh
+
+# Better
+# Keep the release lock until the migration exits.
+./migrate.sh
+~~~
+
+## CODE-02 | Comments or docstrings that describe edit history
+
+- What / why: A permanent comment explains what an earlier version did instead of the current behavior.
+- Detect: Search for references to the edit itself or a previous implementation.
+- False positives: Migration notes and changelogs are about change by design.
+- Evidence: weak; location and purpose determine whether history belongs there.
+
+~~~js
+// Bad
+// Replaced the old loop that scanned every record.
+return recordsById.get(id);
+
+// Better
+// Map lookup stays constant-time as the record set grows.
+return recordsById.get(id);
+~~~
+
+~~~python
+# Bad
+# This used to call the network twice before we changed it.
+return cached_response
+
+# Better
+# Reuse the cached response so retries do not issue a second request.
+return cached_response
+~~~
+
+## CODE-03 | Defensive checks that duplicate a proven contract
+
+- What / why: A local branch repeats a type or invariant already guaranteed at that call site.
+- Detect: Trace the value from input to this line. Check runtime boundaries, deserialization, plugin calls, and public APIs separately.
+- False positives: Never remove input checks just because a type annotation exists if data can arrive from JSON, a user, disk, environment variables, a network, or another runtime.
+- Evidence: weak; requires repository knowledge.
+
+~~~ts
+// Before: simplify only when the internal module contract guarantees a number.
+function label(count: number): string {
+  if (typeof count !== "number") throw new TypeError("count must be numeric");
+  return String(count);
+}
+
+// After: valid only for an internal typed call site, not parsed or external input.
+function label(count: number): string {
+  return String(count);
+}
+~~~
+
+~~~python
+# Before: redundant only if an internal caller already validated this value.
+def format_count(count: int) -> str:
+    if not isinstance(count, int):
+        raise TypeError("count must be an integer")
+    return str(count)
+
+# After: valid only inside that established boundary.
+def format_count(count: int) -> str:
+    return str(count)
+~~~
+
+Shell inputs usually cross a trust boundary. Keep validation:
+
+~~~sh
+# Preserve this guard for an environment-supplied path.
+case "$target_dir" in
+  ""|"/"|"$HOME") printf '%s\n' "unsafe target" >&2; exit 2 ;;
+esac
+rm -rf -- "$target_dir"
+~~~
+
+A shell guard is not redundant merely because the caller usually supplies a safe value. Remove only a check proven unreachable by an explicit internal invariant.
+
+## CODE-04 | One-use pass-through wrappers
+
+- What / why: A one-call helper adds a name but no behavior, contract, test seam, or reuse.
+- Detect: Search for other call sites and inspect whether the helper expresses an important domain concept.
+- False positives: Keep wrappers that enforce policy, isolate an external dependency, or give a stable test seam.
+- Evidence: weak; repository architecture decides.
+
+JavaScript / TypeScript:
+
+~~~js
+// Before
+function getUser(id) {
+  return database.getUser(id);
+}
+const user = getUser(id);
+
+// After, when no policy or reuse exists
+const user = database.getUser(id);
+~~~
+
+~~~ts
+// Keep this wrapper: it enforces authorization before returning a profile.
+async function getProfile(actor, id) {
+  await requireAccess(actor, id);
+  return profiles.get(id);
+}
+~~~
+
+Python:
+
+~~~python
+# Before
+def read_config(path):
+    return Path(path).read_text()
+
+config = read_config(path)
+
+# After, when no contract or reuse exists
+config = Path(path).read_text()
+~~~
+
+~~~python
+# Keep this wrapper: it pins encoding and maps a missing file to a domain error.
+def read_policy(path):
+    try:
+        return Path(path).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise PolicyMissing(path) from exc
+~~~
+
+Shell:
+
+~~~sh
+# Before
+run_tests() {
+  npm test
+}
+run_tests
+
+# After, for one direct call with no options or contract
+npm test
+~~~
+
+~~~sh
+# Keep a helper that verifies the receipt before reporting success.
+verify_receipt() {
+  node scripts/verify-receipt.mjs "$1"
+}
+~~~
+
+## CODE-05 | Speculative configuration
+
+- What / why: A new option is added without a user, supported consumer, or defined behavior.
+- Detect: Require a concrete call site, default, validation rule, and documentation for each option.
+- False positives: Keep settings that already exist in the host contract or that the task explicitly requests.
+- Evidence: weak; this is a scope-control review.
+
+~~~ts
+// Bad: imaginary option with no consumer
+const config = { retryMode: "smart", fallbackRegion: "auto" };
+
+// Better: expose only the supported retry value
+const config = { retries: 2 };
+~~~
+
+~~~python
+# Bad: accepted but never changes behavior
+def connect(endpoint, experimental_pooling=False):
+    return Client(endpoint)
+
+# Better: remove the unused setting or implement its contract
+def connect(endpoint):
+    return Client(endpoint)
+~~~
+
+~~~sh
+# Bad: undocumented environment knob with no reader
+export LIT_AUTO_REPAIR_MODE=smart
+
+# Better: remove it until a supported caller defines its meaning
+node scripts/check.mjs
+~~~
+
+## CODE-06 | Over-broad exception handling
+
+- What / why: A catch-all hides errors the code does not know how to recover from.
+- Detect: List expected exceptions and the recovery action for each. Keep cleanup in finally blocks.
+- False positives: A process boundary may need a broad handler that logs and exits; preserve it when it prevents partial state or gives a clear failure.
+- Evidence: weak; behavior and data-safety determine the review.
+
+~~~js
+// Bad
+try {
+  await writeReceipt();
+} catch {
+  return "ok";
+}
+
+// Better: report write failure instead of inventing success
+await writeReceipt();
+return "ok";
+~~~
+
+~~~js
+// Keep cleanup even when errors propagate.
+try {
+  await acquireLock();
+  await updateIndex();
+} finally {
+  await releaseLock();
+}
+~~~
+
+~~~python
+# Bad
+try:
+    parse_manifest(path)
+except Exception:
+    return {}
+
+# Better: recover only from the expected missing optional file
+try:
+    parse_manifest(path)
+except FileNotFoundError:
+    return {}
+~~~
+
+~~~sh
+# Bad: masks the original command failure
+command || true
+
+# Better: propagate failure with context
+command || { printf '%s\n' "migration failed" >&2; exit 1; }
+~~~
+
+## CODE-07 | Log spam and duplicate state reporting
+
+- What / why: Adjacent logs repeat one success or expose details that do not help diagnose a failure.
+- Detect: For each log, ask what action the operator can take from it and whether it contains secrets.
+- False positives: Keep long-job progress, failure context, structured audit events, and privacy-safe status needed for support.
+- Evidence: weak; operational context decides.
+
+~~~js
+// Bad
+console.log("starting");
+console.log("started");
+console.log("complete");
+
+// Better
+console.log("Index rebuild complete");
+~~~
+
+~~~python
+# Bad: prints the same safe status on every loop iteration
+for _ in range(100):
+    print("waiting")
+
+# Better: report progress at a useful interval
+for step in range(100):
+    if step % 10 == 0:
+        print(f"checked {step} items")
+~~~
+
+~~~sh
+# Bad: dump an entire environment to debug one missing variable
+env
+
+# Better: report presence without exposing values
+test -n "$API_ENDPOINT" || printf '%s\n' "API_ENDPOINT is unset" >&2
+~~~
+
+Never log credential values, private user data, or full configuration to reduce debugging effort.
+
+## CODE-08 | Commit subjects and trailers
+
+- What / why: A commit title should say what changed; generated-by trailers do not describe behavior and are forbidden by the family rule.
+- Detect: Read the subject without the diff and confirm it names a concrete change.
+- False positives: Keep conventional prefixes required by the repository; do not add model attribution.
+- Evidence: block for generated attribution under the user's explicit writing policy; ordinary subject style is repository-specific.
+
+~~~text
+Bad: Update things and improve stability
+Better: fix: preserve empty optional model fields
+~~~
+
+~~~text
+Bad: Changes
+Better: docs: explain the offline install path
+~~~
+
+~~~text
+Bad trailer: Generated by an AI assistant
+Better: No generated-by trailer; describe the change in the subject
+~~~
+
+## CODE-09 | Pull request descriptions that narrate effort
+
+- What / why: A PR should explain behavior, reason, scope, and checks, not praise the author or repeat that work was done.
+- Detect: Remove process claims and retain reproducible behavior plus actual evidence.
+- False positives: Keep an explicit risk, migration step, or test limit.
+- Evidence: weak for style; generated attribution remains prohibited.
+
+~~~text
+Bad: This exciting change thoughtfully improves the whole system.
+Better: The installer now preserves an existing model route when updating the plugin.
+~~~
+
+~~~text
+Bad: I carefully updated the files and checked everything.
+Better: Changed the config parser and install probe. Tests: npm test. Manual probe: upgrading from schema 45 preserved the route.
+~~~
+
+Do not claim a check that did not run. If it failed, report the failure and its scope.
+
+## CODE-10 | README instructions that hide prerequisites or limits
+
+- What / why: Promotional lead-in delays the command or omits a real constraint.
+- Detect: Check that a reader can identify prerequisites, command, expected result, and recovery path.
+- False positives: Keep necessary security warnings and compatibility notes.
+- Evidence: weak; a usability check, not a detector.
+
+~~~md
+Bad: This powerful tool makes setup seamless and easy for everyone.
+Better: Install Node 20 or later, then run npm install.
+~~~
+
+~~~md
+Bad: Start the server and use the package.
+Better: Set LIT_ENDPOINT, run npm start, then open the local URL printed by the command. The server stores its cache in .litfamily/cache.
+~~~
+
+## CODE-11 | Changelog inflation or missing version facts
+
+- What / why: A changelog announces significance instead of naming behavior, or leaves version and compatibility boundaries unclear.
+- Detect: Verify release number, changed behavior, migration impact, and links against the actual release.
+- False positives: Preserve the project's established format and user-facing rationale.
+- Evidence: weak; facts and release convention matter.
+
+~~~md
+Bad: A groundbreaking update that transforms the experience.
+Better: 1.4.0 — Keep the existing endpoint when applying an in-place update.
+~~~
+
+~~~md
+Bad: Several fixes and improvements.
+Better: 1.4.1 — Fix export when a filename contains a space.
+~~~
+
+## CODE-12 | Preserve API contracts when simplifying
+
+- What / why: A rewrite can remove a guard or error path callers rely on even when the result looks shorter.
+- Detect: Trace inputs, outputs, exceptions, file writes, and host compatibility before editing.
+- False positives: Defer a style cleanup if the contract is unclear.
+- Evidence: safety invariant rather than a writing-pattern score.
+
+~~~ts
+// Bad: a type assertion accepts untrusted JSON without checking its shape.
+const data = JSON.parse(rawText) as Manifest;
+~~~
+
+~~~ts
+// Better: validate the parsed value at the trust boundary.
+const data = validateManifest(JSON.parse(rawText));
+~~~
+
+~~~python
+# Bad: malformed data is treated like a missing optional file.
+try:
+    return parse_config(path)
+except (FileNotFoundError, ValueError):
+    return default_config
+~~~
+
+~~~python
+# Better: default only when absent; let a corrupt file raise its parse error.
+try:
+    return parse_config(path)
+except FileNotFoundError:
+    return default_config
+~~~
+
+~~~sh
+# Better: keep path validation before a destructive operation.
+validate_target "$target_dir"
+rm -rf -- "$target_dir"
+~~~
+
+## Quick review list
+
+- Comments state why, what invariant, or which compatibility rule; they do not narrate the next obvious line.
+- Docstrings describe public behavior, accepted inputs, errors, and side effects.
+- Commit subjects identify one change. No generated-by trailers.
+- PRs state behavior, scope, actual checks, and unresolved risks.
+- READMEs put prerequisites and working commands before generic claims.
+- Changelogs name the version and user-visible change.
+- Code simplification preserves trust boundaries, data safety, errors, and platform checks.
+- For JS/TS, Python, and shell, check that static types and runtime input guarantees agree before removing a guard.

package/assets/lithermes-plugin/skills/lit-humanizer/references/deliverable-channels.md

@@ -0,0 +1,111 @@
+# Deliverable channels
+
+Choose the channel before rewriting. The same fact may be useful in an internal log and distracting in a reader-facing report. Keep complete provenance in internal records; put only the context that helps the intended reader in the deliverable or reply.
+
+## Requested artifact
+
+Write for the artifact’s audience, format, and voice. Keep every supported fact, name, number, date, quote, citation, and functional qualifier. If a summary omits detail, preserve the source’s direction and limits.
+
+Use footnotes, endnotes, or the reference list requested by the user. A source line directly beneath a table or figure is an accepted layout convention when it is plain and attached to the visual. Keep it within one blank line of the visual. Do not turn that allowance into a paragraph-wide exemption. A source line that also contains a limitation remains visible to the detector so the caveat does not disappear.
+
+Put a limitation next to the claim it changes and state it once. Prefer a complete sentence naming the scope, measurement, or action. Preserve an actual legal, medical, scientific, financial, or safety boundary when the user requested it or the reader needs it to use the artifact. Never upgrade a proposal or estimate into a result; never delete a negative finding to make the prose sound confident.
+
+### Patterns from real deliverables and reader-safe rewrites
+
+These pairs are short channel examples. Their after lines retain the source condition and its consequence.
+
+> Bad: A 30% gain will follow completion.
+> Better: The report lists a 30% gain as an expected outcome after completion; it is not a realized result.
+>
+> Bad: [C003] says the 30% gain is not realized.
+> Better: The source reports a 30% gain as expected, not realized. Keep the claim-to-source key in the internal record.
+>
+> Bad: Source: annual report, table 4.
+> Better: The annual report records the value in table 4.¹
+>
+> Bad: Source: annual report, table 4. Not a realized outcome.
+> Better: The annual report lists the value as an expected outcome, not a realized one.¹
+>
+> Bad: **Evidence boundary:** the site deployment was not verified.
+> Better: The public product pages do not establish deployment at a specific site.
+>
+> Bad: Evidence: no independent reproduction.
+> Better: We did not independently reproduce the result.
+>
+> Bad: Confidence: High source-backed within the packet.
+> Better: The claim is supported within the supplied packet; it was not independently checked.
+>
+> Bad: [미검증] [증거 기반]
+> Better: 표 3의 추정치는 아직 검증하지 않았습니다. 근거는 보고서 각주 2에 있습니다.
+>
+> Bad: 미확인 · 미실행 · 투자 조언 아님 · 허가 판단 결과 아님
+> Better: 원격 검증은 실행하지 않았습니다. 이 자료는 투자 조언이 아니며 허가 판단을 내리지 않습니다.
+>
+> Bad: demo synthesis and assumptions
+> Better: The architecture is proposed for the demonstration; its leading indicators and baselines are assumptions.
+>
+> Bad: This happened in this lane, using the claim ledger.
+> Better: The internal record links the result to its source. The reader-facing claim names the measured result.
+>
+> Bad: The image receipt confirms the single-frame figure.
+> Better: Figure 6 uses one verified local frame at 2.885 µs.
+>
+> Bad: I've updated the file and saved it.
+> Better: The report now includes the revised measurements.
+>
+> Bad: Let me know if you’d like another version.
+> Better: End after the requested artifact, unless a decision or action remains.
+
+A short source attribution under a table, image or figure is an exception for layout, not a new section style. The detector tests Markdown tables, Markdown images, HTML figures, figure captions, one blank line, caveat-bearing sources, and labels left in prose.
+
+## Chat reply
+
+Return the requested work without an audit preamble. Summarize the change only when useful. State one material risk plainly when it affects a decision. Mention a limitation only when the user needs it to understand what was delivered or what action remains.
+
+The reply can include a direct answer or requested explanation. Remove generic service closers and narration about editing. Do not claim a check happened unless it did.
+
+## Internal records
+
+Plans, evidence files, ledgers, handoffs, status and doctor output, and machine-readable reports may need exact paths, commands, counts, hashes, provenance, uncertainty, and failures. Keep those records detailed and structurally intact. Do not rewrite an internal fact into a smoother but less exact statement.
+
+An internal record can retain compact keys, status fields, lane names, and repeated uncertainty when its schema requires them. Do not pass those fields to a reader-facing deliverable unchanged. The product adapter should identify the intended channel before scanning.
+
+## Keep useful caveats without stacking them
+
+- One result may need one scope sentence. Keep all conditions that change its meaning.
+- If several cautions describe separate risks, give each the location or list required by the artifact; do not compress away a safety condition.
+- If a disclaimer is legally or clinically required, preserve it. Put it where the user or format asked for it.
+- If the source says that a test did not run, say which test and scope. Do not imply it passed.
+- If a source does not support a stronger claim, retain that limit. Do not fabricate a named source to replace vague attribution.
+- If a verification limitation is accurate and changes the claim, state it once in the relevant sentence. Keep the scope exact.
+
+## Internal vocabulary to reader prose
+
+Keep internal process names inside the corresponding evidence record unless the reader needs the name to reproduce or audit a result. Replace a process label with the content it points to: the specific file, source, measurement, person, date, or action. Do not replace an unknown with a plausible detail.
+
+The exact factual relation determines the rewrite. A compact label may become:
+- an attributed observation;
+- a sentence naming a proposal or assumption;
+- a source note attached to a visual;
+- a statement that an action was not run;
+- a scoped legal or safety condition;
+- or an internal record reference.
+
+## Category-1 mapping
+
+The 26 real lines and synthesis shapes are indexed in references/taxonomy.md. That file gives an individual rewrite for each line. This file defines how to place the rewritten fact:
+
+| Shape | Artifact channel |
+|---|---|
+| Source plus forecast, demo status, or assumptions | State the source and status in one factual sentence; keep the citation beside the claim. |
+| Internal keys and routing | Keep tracking details in the evidence record; cite the reader-facing source in the deliverable. |
+| Label, bracket tag, confidence or evidence boundary | Replace the heading with a sentence whose subject is the claim or measurement. |
+| Non-observation or unperformed work | Name what was not observed or run; keep the result’s scope. |
+| Disclaimer chain | Preserve each relevant condition in concise sentences; omit only irrelevant boilerplate. |
+| Source line under a visual | Keep a plain source attribution if directly attached; move the caveat into the claim sentence. |
+| Demo/self-description | Say what is proposed, assumed, simulated, measured, or unverified. Do not use a self-label as evidence. |
+| Standalone “limitations” sentence | Name the actual limitation or leave a real uncertainty explicit. Do not add a generic challenge to create balance. |
+
+## Detector boundary for ports
+
+Phase A scans the text it receives. Product ports must pass only newly generated or changed model text. Existing file text, exact user quotations, source quotations, internal records, fenced code, and inline code need the host’s explicit boundaries. A standalone script cannot infer which text was changed. When a host has no supported pre-write surface, describe the detector as advisory rather than inventing an integration hook.