agent-bios 0.1.0

package/claude/guides/coding-staged-workflow.md

@@ -0,0 +1,70 @@
+---
+guide_id: coding-staged-workflow
+language: en
+status: active
+use_when:
+  - meaningful development work needing execution depth, review loops, and stop conditions
+  - architecture changes, new features, cross-module or ontology changes, review-driven fixes
+  - the user asks to design ("설계") before implementation
+  - judging materiality of review findings and deciding when to stop or redesign
+  - choosing the per-domain verification mix (code, ontology, config/data, spreadsheets, docs)
+---
+
+# Coding Guidelines: Staged Workflow
+
+This guide is a scoped extension of the global Coding Guidelines. Use it for meaningful development work to choose execution depth, review loops, and stop conditions.
+
+It operates inside the existing global rules for requested scope, concept economy, LLM/tools/code boundary, verification discipline, and documentation hygiene.
+
+For trivial edits, use the lightweight inspect-edit-verify path from the global Coding Guidelines.
+
+When the user asks to "설계" or design, stay in design mode. Focus on high-level design and implementation-process design, then present the plan, tradeoffs, review gates, and implementation trigger. Move to implementation after the user asks to implement or approves the plan.
+
+## When To Use
+
+- Use this workflow for architecture changes, new features, cross-module behavior changes, ontology changes, review-driven fixes, or work that affects user-visible behavior, authority, lifecycle, validation, failure handling, or roadmap commitments.
+- Use the lightweight path for small text edits, narrow config changes, or single-file adjustments whose completion criteria and verification are obvious.
+- Increase workflow depth when new evidence shows broader risk than the initial request suggested.
+
+## Stages
+
+1. High-level design: define the goal, scope, architecture direction, affected concepts, tradeoffs, and completion criteria.
+2. Implementation-process design: turn the design into an ordered work plan with dependencies, verification points, review gates, and redesign triggers.
+3. Implementation: make the smallest viable functional changes that satisfy the approved design and process plan.
+
+## Review Loop
+
+- At each stage, run review loops as appropriate: self review, subagent review when available, and structured multi-lens review when the repository or domain supports one (concrete tool: Environment Binding below).
+- Iterate until material issues reach zero: review, identify material issues, fix them, and review again.
+- Use the severity contract for materiality — the canonical definition is the ladder below; external review tools map their levels onto it: blocker, high, and medium are material; low and info are non-material.
+- Treat blocker as primary happy-path or core-contract failure.
+- Treat high as supported user, environment, data, or execution path failure.
+- Treat medium as meaningful weakening of trust, auditability, reproducibility, completeness, or decision quality.
+- Treat low and info as non-blocking unless requested or promoted by new evidence.
+
+## Verification Menus
+
+Per-domain menus for the global Verification Discipline loop; pick the narrowest reliable mix that proves the changed behavior, meaning, or contract.
+
+- Code: a layered mix of unit tests, integration tests for E2E segments, targeted E2E for changed flows, and full E2E for release or high-risk changes.
+- Ontology: static graph checks, concept economy gates, changed-path integration checks, and competency-question E2E checks.
+- Config or data: real parsers, schema checks, fixture validation, and sample transformations.
+- Spreadsheets: static workbook checks, fixture-based output checks, cross-sheet flow checks, visual/layout checks, and real Microsoft Excel engine recalculation for formula-dependent results.
+- Docs: links, terminology, current behavior alignment, and references to isolated historical notes.
+
+## Stop Conditions
+
+- If the issue boundary expands compared with the previous review, stop and ask the user to choose redesign/rework or continuing the current iteration.
+- Consider the boundary expanded when review reveals a broader affected purpose, failure condition, impact area, concept boundary, architecture boundary, or severity class.
+- Before calling the work done, report the current stage, review results, remaining material issues, verification results, and any stop reason.
+
+## Environment Binding (edit per environment)
+
+The only section of this guide that names concrete tools. Dated; expires ~8 weeks after the date or when the bound tool changes.
+
+Binding (2026-07):
+
+| Slot | Binding | Notes |
+|---|---|---|
+| Structured multi-lens review | onto-mcp review (private MCP) | consumes/emits the severity contract defined in Review Loop |
+| Subagent review | host CLI's native review mechanism | e.g. Claude Code `/code-review` or Agent-tool reviewers |

package/claude/guides/implementation-map.md

@@ -0,0 +1,34 @@
+---
+guide_id: implementation-map
+language: en
+status: active
+use_when:
+  - creating or updating IMPLEMENTATION_MAP.html in a repo with implementation code
+  - building the single SVG service blueprint inside it
+  - deciding what belongs in the current-state dashboard vs isolated history notes
+---
+
+# Implementation Map Guide
+
+Scoped extension of the **Implementation Map** section of the global instructions. Use this when creating or updating `IMPLEMENTATION_MAP.html` for a repo with implementation code.
+
+## Purpose
+
+`IMPLEMENTATION_MAP.html` is a **current-state dashboard** — it answers "where is this work now, what decides next, and what is at risk," not "what happened." It is not a changelog, handoff log, or accumulated project diary.
+
+## Build / rebuild rules
+
+- Rebuild it around the current task, current architecture, current risks, current decisions, and current verification status.
+- Compress completed history into the smallest useful summary; keep detailed past progress, abandoned alternatives, and long completed-task lists in isolated notes (`docs/`, `design/`, `archive/`).
+- The first viewport must show current goal, phase, health, next decision, and main risk.
+- Make it a self-contained HTML view with compact visual sections for status, architecture, roadmap, decisions, risks, verification, and change impact.
+- Update it before committing, when writing a handoff, or after meaningful architecture, roadmap, risk, decision, or verification changes.
+
+## The SVG service blueprint
+
+Include exactly **one** self-contained SVG service blueprint that visualizes the whole service or implemented system at the right level of abstraction. Build it using `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/svg-visualization-guide.md`.
+
+- Keep the blueprint focused on a single judgment question; use compact nodes rather than exhaustive file or task lists.
+- Use stable lanes, a legend, fixed role colors, short labels, and explicit arrows to separate: inputs, runtime/tools, LLM work, canonical artifacts, views, gates, quality checks, postponed work, and downstream/future work.
+- Distinguish time flow from authority flow, and distinguish canonical artifacts from JSON/YAML/Markdown/HTML projections.
+- Validate SVG syntax and layout hygiene when practical; ensure text does not overlap, and keep hot-path work visually separate from postponed or excluded work.

package/claude/guides/llm-capability-boundary-examples.md

@@ -0,0 +1,123 @@
+---
+guide_id: llm-capability-boundary-examples
+parent: llm-capability-boundary
+language: en
+status: active
+use_when:
+  - looking for worked precedents of boundary and field-authority design
+  - designing cases similar to sidecar submit, structured-output hybrid, MCP schema projection, or projection enrichment
+---
+
+# LLM And Capability Boundary: Worked Examples
+
+This guide is a scoped extension of
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/llm-capability-boundary.md`.
+Each example records a problem, the structural path taken, and the learning.
+
+## Lens Sidecar To Finding Ledger
+
+Problem:
+
+- Lens markdown was heterogeneous.
+- Finding-ledger LLM had to reread and normalize noisy markdown.
+- Runtime could not strongly guarantee ids, refs, artifact paths, or validation
+  scaffolds.
+
+Structural path:
+
+- Add `submit_lens_findings` as a batched submit tool.
+- LLM submits semantic finding fields once.
+- Runtime writes `round1/{lens}.findings.yaml`.
+- Runtime owns `session_id`, `lens_id`, `candidate_id`, `source_ref`,
+  `human_output_ref`, validation, and YAML serialization.
+- Optional markdown is rendered from the sidecar.
+- When every lens output is a sidecar, runtime writes `finding-ledger.yaml`
+  deterministically.
+
+Learning:
+
+- Machine artifacts should not depend on LLM prose formatting.
+- Batched submit reduces partial-output and per-call overhead.
+- Prompt packets can become audit packets when runtime owns the artifact.
+- A tool-capable route is required; text-only fallback should fail clearly for
+  this contract.
+
+## Structured Output Hybrid
+
+Problem:
+
+- Provider strict schema can enforce short enums.
+- Long evidence refs can contain quotes or source text that make provider enum
+  schemas brittle.
+- Pure post-hoc validation catches shape but not meaning.
+
+Structural path:
+
+- Use provider strict schema for short closed fields.
+- Keep `evidence_refs` as string arrays in provider schema.
+- Compute runtime allowed refs from prompt packet projections.
+- Reject unsupported refs at submit time.
+- Use a route where artifacts are created only by runtime submit handling.
+
+Learning:
+
+- Strict schema is real enforcement only where provider support and schema shape
+  are suitable.
+- Long refs need runtime allowed-set validation.
+- Each field needs one primary authority plus enough layered checks.
+
+## MCP-Projectable Schema Boundary
+
+Problem:
+
+- MCP/Claude tool surfaces need simple, directly valid object schemas.
+- Internal artifact schemas may benefit from richer JSON Schema composition.
+- Treating every repository schema as a tool schema can over-constrain internal
+  design, while exposing composed schemas can break tool hosts.
+
+Structural path:
+
+- Expose pattern-valid canonical tool names: use `namespace_verb` snake_case
+  such as `sheets_read`, matching `^[a-zA-Z0-9_-]{1,64}$`; reuse the catalog
+  name for dispatch, audit, and allowed-tool config, and enforce it in catalog
+  or seed validation.
+- Treat MCP tool `input_schema` values and schemas intended for MCP/Claude tool
+  projection as MCP-projectable schemas.
+- For MCP-projectable schemas, prefer direct object schemas with explicit
+  fields and avoid `oneOf`, `anyOf`, and `allOf`.
+- Put variant behavior behind operation enums, deterministic dispatch, runtime
+  validation, or explicit projection adapters.
+- Internal-only schemas may use composition when it materially reduces
+  complexity, but project them into compatible direct object schemas before
+  they reach an MCP/Claude tool surface.
+
+Learning:
+
+- The compatibility rule belongs at the tool projection boundary, not as a
+  universal ban on every internal schema.
+- Tools/code should own projection and validation so the LLM cannot accidentally
+  expose an incompatible schema shape.
+
+## Issue Stance Matrix Projection
+
+Problem:
+
+- A compact projection lacked action and dependency context needed by later LLM
+  units.
+- Asking later units to reread raw artifacts would increase latency and drift.
+
+Structural path:
+
+- Enrich the runtime projection with action, dependency, threshold, singleton,
+  shared-cause, and bounded-source-ref fields from authoritative upstream
+  artifacts.
+- Keep matrix merge deterministic.
+- Validate refs against allowed source variants.
+- Track projection coverage and fallback when omitted context may matter.
+
+Learning:
+
+- Projection-first enrichment is often better than expanding LLM context.
+- Add semantic context to deterministic projections when later judgment depends
+  on it.
+- Projection quality needs coverage checks, not only schema checks.

package/claude/guides/llm-capability-boundary-patterns.md

@@ -0,0 +1,339 @@
+---
+guide_id: llm-capability-boundary-patterns
+parent: llm-capability-boundary
+language: en
+status: active
+use_when:
+  - implementing submit tools, runtime-owned fields, or output channel locks
+  - choosing provider strict schema vs runtime allowed-set validation
+  - implementing grounding, provenance, projection, or evidence-index mechanics
+  - handling security, side effects, persistence, idempotency, or retry policy
+  - managing schema single source of truth and migration
+---
+
+# LLM And Capability Boundary: Enforcement Patterns
+
+This guide is a scoped extension of
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/llm-capability-boundary.md`.
+Use it when implementing the enforcement mechanics that the boundary doctrine
+assigns to runtime/tools and the capability surface.
+
+## Structural Enforcement Patterns
+
+### Bounded Submit Tool
+
+Use a submit tool when an LLM must provide semantic content for a
+machine-consumed artifact.
+
+Pattern:
+
+1. Runtime creates a submit tool with a narrow schema.
+2. LLM submits only bounded semantic fields.
+3. Runtime rejects unknown fields and runtime-owned fields.
+4. Runtime validates enums, refs, grounding, and policy constraints.
+5. Runtime writes the canonical artifact.
+6. Downstream consumers read only the runtime artifact.
+
+This is stronger than asking the LLM to "write valid YAML." The LLM can still
+make semantic judgments, but shape, path, ids, metadata, and serialization are
+owned by runtime/tools.
+
+Illustrative implementation:
+
+```ts
+type FindingSubmitPayload = {
+  findings: Array<{
+    target: string;
+    claim: string;
+    evidence_refs: string[];
+    rationale?: string;
+  }>;
+};
+
+function submitFindings(payload: FindingSubmitPayload, ctx: RuntimeContext) {
+  rejectUnknownFields(payload, ["findings"]);
+  rejectRuntimeOwnedFieldsDeep(payload, [
+    "schema_version",
+    "session_id",
+    "lens_id",
+    "candidate_id",
+    "source_ref",
+    "output_path",
+  ]);
+
+  validateEvidenceRefs(payload.findings, ctx.allowedEvidenceRefs);
+
+  const artifact = {
+    schema_version: 1,
+    session_id: ctx.sessionId,
+    lens_id: ctx.lensId,
+    findings: payload.findings.map((finding, index) => ({
+      ...finding,
+      candidate_id: stableCandidateId(ctx, finding, index),
+      source_ref: `${ctx.outputPath}#candidate-${index + 1}`,
+    })),
+  };
+
+  atomicWriteYaml(ctx.outputPath, validateFindingArtifact(artifact));
+}
+```
+
+### Runtime-Owned Deterministic Fields
+
+Keep deterministic fields outside LLM authority when runtime/tools can derive
+them.
+
+Common runtime-owned fields:
+
+- `schema_version`
+- `session_id`
+- `lens_id`
+- `issue_id` when unit identity already determines it
+- `candidate_id`, `finding_id`, `cause_id` when stable runtime assignment is
+  available
+- `source_ref` when it can be derived from artifact path and local id
+- `output_path`
+- validation scaffolds
+- artifact envelope and serialization
+- source snapshot id, source hash, trust tier, permission scope, and staleness
+  metadata
+
+The LLM may select a known id only when selection is the semantic task. If the
+runtime already knows the id, the LLM should not submit it.
+
+Stable ordering alone can break under retry, batching, dedupe, or parallelism.
+Use normalized hashes, idempotency keys, persisted sequence tables, or prior-run
+mappings when ids must remain stable across runs.
+
+### Accepted Output Channel Lock
+
+When structured output matters, make the submit path the only accepted path.
+
+Examples:
+
+- Canonical artifact writes happen only through runtime submit handling.
+- Text output can be captured for diagnostics, but does not become artifact
+  truth.
+- A text-only executor is rejected when the contract requires a tool-capable
+  structured-output path.
+- Runtime-owned canonical paths are isolated from LLM-written scratch paths.
+
+This turns "please use the right format" into "only this channel is accepted."
+A read-only filesystem route is one implementation. The deeper rule is that the
+canonical artifact truth is writable only through runtime-controlled paths.
+
+### Provider Strict Schema For Short Closed Values
+
+Provider strict schema is useful for short, stable, closed vocabularies. It is
+not the artifact authority.
+
+Good strict-schema candidates:
+
+- `severity`
+- `stance`
+- `issue_role`
+- `judgment_state`
+- `impact_kind`
+- `timing_class`
+- `closure_class`
+- short bounded `issue_id` values when the LLM must select one
+- confidence or relation enums
+
+Keep runtime enum validation too. Provider support depends on model, route,
+schema subset, schema size, and refusal/incomplete behavior. Probe the route
+before relying on strict schema, and fail or downgrade deliberately when support
+is unavailable.
+
+Keep sensitive data, long source text, private refs, and user-specific secrets
+out of schema names, enum values, const values, and regex patterns. Schema text
+itself is data.
+
+### Runtime Allowed-Set Validation For Long Refs
+
+Long refs, source-derived refs, quoted snippets, and path-heavy strings are
+better handled as strings in provider schema plus runtime allowed-set
+validation.
+
+Good runtime allowed-set candidates:
+
+- `evidence_refs`
+- source refs containing quotes
+- refs that include line text
+- generated artifact anchors
+- source snippets
+- long path-like values
+- user- or tenant-scoped ids
+
+This keeps provider schemas robust while preserving fail-loud validation. The
+LLM can emit a string, but runtime rejects strings outside the computed allowed
+set.
+
+### Grounding And Provenance
+
+Use grounding as a hard gate only when source truth is decidable.
+
+Good grounding-blocked candidates:
+
+- evidence anchor resolves to a known source span
+- quoted source text exists in the cited file
+- ref belongs to a known artifact and anchor set
+- count, id, or relation coverage can be deterministically checked
+
+Keep warning-style audits for free prose when false positives are likely. A
+free-text synthesis citation audit may be useful, but it should not become a
+hard gate until the verifier is reliable.
+
+Grounding is not provenance. A quote can match a source span while the source is
+stale, unauthorized, poisoned, incomplete, or low-trust. Track provenance
+separately:
+
+- `source_snapshot_id`
+- source hash or version
+- ingest time
+- permission scope
+- trust tier
+- retrieval policy
+- staleness policy
+- poisoning or integrity checks where relevant
+
+Use robust quote checks in production: normalize whitespace and Unicode, use
+stable offsets or line anchors, disambiguate duplicate spans, and record source
+snapshot ids.
+
+### Deterministic Projection
+
+When an artifact is a direct projection from upstream artifacts, make it
+runtime-owned.
+
+Examples:
+
+- Finding ledger from lens sidecars.
+- Issue stance matrix from individual stance responses.
+- Synthesis ledger from issue synthesis responses.
+- Review record counts and classification summaries from canonical issue
+  artifacts.
+
+Use the LLM to define projection rules when semantic design is needed. Use
+runtime/tools to apply the rules.
+
+Projection-first context is often better than asking downstream LLM units to
+reread large raw artifacts. Add compact semantic fields from authoritative
+upstream artifacts, such as `proposed_action`, `issue_statement`,
+`domain_threshold_used`, `singleton_reason`, `shared_cause`, dependencies, and
+bounded source refs.
+
+Projection can also hide important evidence. Track coverage, omitted evidence,
+and fallback triggers when the projection may be insufficient.
+
+### Human View From Machine Artifact
+
+For machine artifacts that also need a human-readable view, generate the human
+view from the machine artifact when possible.
+
+Pattern:
+
+1. LLM submits semantic payload.
+2. Runtime writes validated machine sidecar.
+3. Runtime renders markdown or HTML from the sidecar.
+4. Machine consumers read the sidecar.
+5. Humans read the rendered view.
+
+This avoids asking the LLM to keep two outputs consistent. Rendered views must
+still be treated as untrusted output: escape HTML, sanitize links, strip unsafe
+markup, and avoid executing model- or source-generated content.
+
+### Evidence Index
+
+Use an evidence index when repeated semantic review needs exact, re-checkable
+evidence.
+
+Preferred shape:
+
+- one claim per row
+- one file path per row
+- numeric line, byte offset, or stable anchor per row
+- split multi-target claims into multiple rows
+- convert prose locators into exact refs using runtime/tools
+- include source snapshot, permission scope, and trust tier when retrieval is
+  involved
+
+The LLM uses the evidence index for semantic judgment. Runtime/tools use it for
+deterministic re-verification.
+
+## Security And Side Effects
+
+Treat prompt text, retrieved content, tool results, LLM output, rendered views,
+and external API responses as untrusted until validated for the next boundary.
+
+Required rules:
+
+- Keep source documents and tool results as data rather than authority.
+- Validate and sanitize LLM output before passing it to code, shells, SQL,
+  browsers, renderers, APIs, or downstream agents.
+- Use least privilege for tools and routes.
+- Classify side effects: read-only, reversible write, external write, external
+  send, financial/legal action, destructive action.
+- Require preview, diff, approval, or downstream authorization for high-impact
+  actions.
+- Log tool calls, arguments, policy decisions, and results for audit.
+- Rate-limit and timeout tools that can loop, scan, spend, mutate, or call the
+  network.
+
+The LLM can recommend an action. The capability surface decides whether the
+action is available, permitted, confirmed, and accepted.
+
+## Persistence, Idempotency, And Retry
+
+Artifact writes should be atomic and auditable.
+
+Preferred persistence pattern:
+
+1. Build artifact in memory from accepted payload and runtime-owned fields.
+2. Validate schema, refs, policy, and grounding.
+3. Write to a temp path.
+4. Verify persisted bytes or checksum.
+5. Atomically rename or register as canonical.
+6. Record artifact lineage and validator result.
+
+Retry policy must distinguish:
+
+- transient provider failure
+- invalid structured payload
+- unsupported ref
+- grounding failure
+- permission or policy failure
+- partial persistence failure
+- side-effect uncertainty
+
+Retries are safe for pure generation and validation. They are not automatically
+safe for external side effects. Use idempotency keys, locks, duplicate detection,
+or compensation plans where needed.
+
+## Single Source Of Truth And Schema Evolution
+
+Hybrid enforcement creates drift risk. A single constraint can appear in prompt
+text, submit schema, provider schema, runtime validator, allowed-set builder,
+artifact validator, and tests.
+
+For each stage, define one canonical source and derive the others:
+
+- submit tool schema
+- provider schema
+- runtime validator
+- allowed-set validator
+- artifact validator
+- prompt contract
+- tests
+- migration sample artifacts
+
+When this is not possible yet, mark the authoritative source explicitly and add
+tests that catch schema/validator drift.
+
+Versioned artifacts need a migration policy:
+
+- what requires a schema version bump
+- backward and forward compatibility expectations
+- migration scripts or readers for old artifacts
+- consumer contract tests
+- deprecation window
+- sample artifact updates