diff --git a/.agent-harness/references/kri-front-common/change-and-verification.md b/.agent-harness/references/kri-front-common/change-and-verification.md new file mode 100644 index 0000000..432b04a --- /dev/null +++ b/.agent-harness/references/kri-front-common/change-and-verification.md @@ -0,0 +1,13 @@ + + +# KriFrontCommon Change and Verification + +- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes. +- Review release notes and the actual affected API before upgrading. +- Run the consumer's focused type-check, test, and build commands after an upgrade. +- Keep `.agent/project.md` near 2-3 KiB as a routing document. Move conditional schemas, endpoint inventories, examples, and issue history to routed `.agent/references/` documents instead of deleting them. +- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope. diff --git a/.agent-harness/references/kri-front-common/package-and-runtime.md b/.agent-harness/references/kri-front-common/package-and-runtime.md new file mode 100644 index 0000000..6bfad0e --- /dev/null +++ b/.agent-harness/references/kri-front-common/package-and-runtime.md @@ -0,0 +1,15 @@ + + +# KriFrontCommon Package and Runtime Contract + +- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities. +- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability. +- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary. +- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point. +- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper. +- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value. +- Prefer named public exports and retain the consumer project's current module system and bundler conventions. diff --git a/.agent-harness/references/kri-front-common/react-compiler.md b/.agent-harness/references/kri-front-common/react-compiler.md new file mode 100644 index 0000000..0aece54 --- /dev/null +++ b/.agent-harness/references/kri-front-common/react-compiler.md @@ -0,0 +1,13 @@ + + +# React Compiler and Manual Memoization + +- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration. +- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as a routine performance precaution. +- Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem. +- Preserve existing memoization unless approved and verified for removal. +- Use `"use memo"` or `"use no memo"` only for a documented compiler boundary. diff --git a/.agent/consumer-references/change-and-verification.md b/.agent/consumer-references/change-and-verification.md new file mode 100644 index 0000000..de22579 --- /dev/null +++ b/.agent/consumer-references/change-and-verification.md @@ -0,0 +1,7 @@ +# KriFrontCommon Change and Verification + +- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes. +- Review release notes and the actual affected API before upgrading. +- Run the consumer's focused type-check, test, and build commands after an upgrade. +- Keep `.agent/project.md` near 2-3 KiB as a routing document. Move conditional schemas, endpoint inventories, examples, and issue history to routed `.agent/references/` documents instead of deleting them. +- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope. diff --git a/.agent/consumer-references/package-and-runtime.md b/.agent/consumer-references/package-and-runtime.md new file mode 100644 index 0000000..e7f1a85 --- /dev/null +++ b/.agent/consumer-references/package-and-runtime.md @@ -0,0 +1,9 @@ +# KriFrontCommon Package and Runtime Contract + +- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities. +- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability. +- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary. +- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point. +- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper. +- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value. +- Prefer named public exports and retain the consumer project's current module system and bundler conventions. diff --git a/.agent/consumer-references/react-compiler.md b/.agent/consumer-references/react-compiler.md new file mode 100644 index 0000000..3e91de2 --- /dev/null +++ b/.agent/consumer-references/react-compiler.md @@ -0,0 +1,7 @@ +# React Compiler and Manual Memoization + +- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration. +- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as a routine performance precaution. +- Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem. +- Preserve existing memoization unless approved and verified for removal. +- Use `"use memo"` or `"use no memo"` only for a documented compiler boundary. diff --git a/.agent/consumer.md b/.agent/consumer.md index fea0742..aa59e41 100644 --- a/.agent/consumer.md +++ b/.agent/consumer.md @@ -1,34 +1,18 @@ ## KriFrontCommon Consumer Contract -### Package Usage - -- Consume this contract through the published `@kri/common` package and only through entry points declared in its `package.json` `exports` map. -- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities. -- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability. +- Consume the published `@kri/common` package only through entry points declared by its `package.json` `exports` map. - Do not import from `@kri/common/src/*`, `@kri/common/dist/*`, or another undeclared deep path. -- Do not copy or fork a shared utility locally merely to avoid using an available public entry point. Propose a backward-compatible library addition when the shared contract is genuinely missing. - -### Runtime and Optional Integrations - -- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary. -- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point. -- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper. -- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value. -- Prefer named public exports and retain the consumer project's current module system and bundler conventions. - -### React Compiler and Manual Memoization - -- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration. -- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as a routine performance precaution. -- Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem. -- Preserve existing memoization unless approved and verified for removal. Use `"use memo"` or `"use no memo"` only for a documented compiler boundary. - -### Project Instruction Budget - -- Keep `.agent/project.md` at or below 8 KiB (8,192 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schemas, endpoint inventories, examples, and temporary issue history to linked project documentation, and keep concise read-routing instructions here. - -### Change Safety - -- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes. -- Review release notes and the actual affected API before upgrading. Run the consumer's focused type-check, test, and build commands after an upgrade. +- Prefer a public shared helper or an approved backward-compatible library addition over copying or forking shared behavior locally. - Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope. + +### Required Shared References + +Before each related task, read the current contents of every matching reference, even if it was read earlier in the session. + +| Task scope | Required reference | +|---|---| +| Package entry points, runtime boundaries, HTTP, authentication, state, storage, environment, or optional peer integrations | `.agent-harness/references/kri-front-common/package-and-runtime.md` | +| React rendering performance, memoization, or React Compiler behavior | `.agent-harness/references/kri-front-common/react-compiler.md` | +| Package upgrade, dependency changes, lockfile, or verification | `.agent-harness/references/kri-front-common/change-and-verification.md` | + +If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead. diff --git a/.agent/project.md b/.agent/project.md index a03772e..949dabe 100644 --- a/.agent/project.md +++ b/.agent/project.md @@ -1,25 +1,18 @@ -## KriFrontCommon Repository Rules +# KriFrontCommon Project Instruction Router -### Repository Role and Public Surface +## Required Project References -- This repository publishes the ESM package `@kri/common`; the repository name and package name intentionally differ. -- Treat `package.json` `exports`, exported TypeScript declarations, entry-point behavior, and documented environment requirements as public contracts. -- Supported entry points are the package root and the explicitly declared subpaths in `package.json`. Do not create or document imports from `src`, `dist`, or another undeclared path. -- Keep runtime-specific code separated. Browser-only APIs must not leak into server entry points, and server-only behavior must not enter browser bundles. -- `src` is the source of truth. `dist` and declaration files are generated artifacts and must not be edited directly. +Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session. -### TypeScript and Dependency Rules +| Task scope | Required reference | +|---|---| +| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` | -- Preserve ESM, `NodeNext` module resolution, explicit `.js` relative import specifiers, declaration generation, and the current strict compiler options. -- Keep exported types narrow and backward-compatible. Review any changed function signature, default, thrown error, serialization shape, or type export as a consumer-facing change. -- React, TanStack Query, and Jotai integrations are optional. Do not make an optional peer mandatory for consumers that use only core utilities. -- Do not add hidden global state for configuration, authentication, HTTP error handling, or query behavior. -- Never expose secrets or server-only environment values through browser-facing configuration helpers. +If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current. -### Verification and Release Boundary +## Harness Workflow -- Install with the repository's selected package manager and lockfile. -- Run `npm run typecheck` for source changes and `npm run build` when declarations or package output may change. -- Inspect the relevant `dist` entry points and generated declarations after changing exports. -- Update `.agent/consumer.md` and human-facing documentation in the same approved change when a public contract changes. -- Version changes, publication, registry changes, and consumer-repository edits require separate explicit approval. +- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly. +- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`. +- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8. +- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source. diff --git a/.agent/references/repository-rules.md b/.agent/references/repository-rules.md new file mode 100644 index 0000000..a03772e --- /dev/null +++ b/.agent/references/repository-rules.md @@ -0,0 +1,25 @@ +## KriFrontCommon Repository Rules + +### Repository Role and Public Surface + +- This repository publishes the ESM package `@kri/common`; the repository name and package name intentionally differ. +- Treat `package.json` `exports`, exported TypeScript declarations, entry-point behavior, and documented environment requirements as public contracts. +- Supported entry points are the package root and the explicitly declared subpaths in `package.json`. Do not create or document imports from `src`, `dist`, or another undeclared path. +- Keep runtime-specific code separated. Browser-only APIs must not leak into server entry points, and server-only behavior must not enter browser bundles. +- `src` is the source of truth. `dist` and declaration files are generated artifacts and must not be edited directly. + +### TypeScript and Dependency Rules + +- Preserve ESM, `NodeNext` module resolution, explicit `.js` relative import specifiers, declaration generation, and the current strict compiler options. +- Keep exported types narrow and backward-compatible. Review any changed function signature, default, thrown error, serialization shape, or type export as a consumer-facing change. +- React, TanStack Query, and Jotai integrations are optional. Do not make an optional peer mandatory for consumers that use only core utilities. +- Do not add hidden global state for configuration, authentication, HTTP error handling, or query behavior. +- Never expose secrets or server-only environment values through browser-facing configuration helpers. + +### Verification and Release Boundary + +- Install with the repository's selected package manager and lockfile. +- Run `npm run typecheck` for source changes and `npm run build` when declarations or package output may change. +- Inspect the relevant `dist` entry points and generated declarations after changing exports. +- Update `.agent/consumer.md` and human-facing documentation in the same approved change when a public contract changes. +- Version changes, publication, registry changes, and consumer-repository edits require separate explicit approval. diff --git a/.agents/skills/attention-aware-communication/SKILL.md b/.agents/skills/attention-aware-communication/SKILL.md new file mode 100644 index 0000000..e27dde4 --- /dev/null +++ b/.agents/skills/attention-aware-communication/SKILL.md @@ -0,0 +1,41 @@ +--- +name: attention-aware-communication +description: Shape substantive answers, progress updates, and completion reports for fast, accurate reading without reducing the underlying work. +--- + + +# Attention-Aware Communication + +This skill changes presentation only. Investigate, implement, and verify as deeply as the task requires. + +## Default: Attention-kind + +- Put the bottom line in the first sentence and use plain Korean. +- Say the least that fully answers, then stop. Remove preambles, padding, repetition, and closing restatements. +- Never omit a number, scope condition, risk, prerequisite, uncertainty, or other fact that could cause the user to act incorrectly. +- For genuine breadth, explain the one or two most important points first, name the remaining areas, and let the user choose whether to expand them. Do not use this to defer required caveats or a complete focused answer. +- When the user asks for a detailed explanation, walkthrough, rationale, or full picture, suspend brevity and provide the necessary detail in scannable sections. +- When asked for a deliverable such as a command, message, snippet, or commit text, return the deliverable without unnecessary framing unless safety or correctness requires context. +- Ask one blocking question at a time and put it last. Keep working when a non-blocking assumption is safe. + +## Progress and Completion: Rundown + +Use Rundown formatting when a task has multiple steps or mixed states: + +- Start with a one-line outcome that includes any blocker. +- Distinguish verified completion, work in progress, work not started, and unknown state. Omit empty categories. +- Put each blocker or material risk on its own line. +- Report only observed states. Mark an unknown as unknown and state what check would resolve it. +- End with the next action or a small numbered choice only when the user must decide. + +## Explicit-Only: Spartan + +Use Spartan style only when the user explicitly asks for it: + +- Lead with the complete answer in one sentence. +- Be terse, blunt, and direct; remove warmth, hedging, transitions, narration, and summaries. +- Keep all load-bearing facts, warnings, and conditions even when they make the answer longer. +- If the user also asks for depth, provide the full detail in short, separated blocks. diff --git a/.agents/skills/karpathy-guidelines/SKILL.md b/.agents/skills/karpathy-guidelines/SKILL.md new file mode 100644 index 0000000..bbb7791 --- /dev/null +++ b/.agents/skills/karpathy-guidelines/SKILL.md @@ -0,0 +1,37 @@ +--- +name: karpathy-guidelines +description: Keep implementation, refactoring, and code review assumption-aware, simple, surgical, and tied to verifiable success criteria. +--- + + +# Karpathy Guidelines + +Use these guidelines while implementing, refactoring, or reviewing code. They refine execution quality but do not expand the approved task scope. + +## Think Before Coding + +- Inspect the relevant code and repository conventions before choosing a solution. +- Surface an assumption when different choices would materially change behavior, compatibility, data, or scope. +- Ask only when the decision cannot be discovered safely and a reasonable assumption would be risky. Otherwise proceed with the smallest reasonable assumption and report it. + +## Simplicity First + +- Implement the smallest complete solution that satisfies the observable requirement. +- Do not add speculative abstractions, extension points, configuration, fallback paths, or dependencies for hypothetical future use. +- Prefer an existing repository pattern or standard-library capability over a new local framework. + +## Surgical Changes + +- Every changed line must trace to the approved objective, required validation, or a necessary compatibility adjustment. +- Preserve existing naming, structure, public behavior, and formatting outside that boundary. +- Do not mix the task with unrelated cleanup. Remove dead code, duplication, or ceremony introduced by the current change before finishing. + +## Goal-Driven Execution + +- Translate the request into observable success criteria before implementation. +- Choose the narrowest check that can fail for the behavior being changed, then run broader repository checks when appropriate. +- Iterate only within the approved scope until the criteria pass or a concrete blocker is established. +- Before reporting completion, inspect the final diff for unnecessary code and use `verification-before-completion` for fresh evidence. diff --git a/.agents/skills/project-reference-loader/SKILL.md b/.agents/skills/project-reference-loader/SKILL.md new file mode 100644 index 0000000..febb5b7 --- /dev/null +++ b/.agents/skills/project-reference-loader/SKILL.md @@ -0,0 +1,29 @@ +--- +name: project-reference-loader +description: Load the current project-specific and shared reference documents routed by AGENTS.md before substantive repository analysis, implementation, debugging, review, or planning. +--- + + +# Project Reference Loader + +Use the repository's generated `AGENTS.md` as the routing entrypoint. + +## Workflow + +1. Find the `Required Project References` and shared-contract reference routes that match the current task. +2. Read the current contents of every matching file before relying on remembered project behavior, even when the file was read earlier in the session. +3. If the task crosses multiple scopes, read every matching reference. Do not load unrelated references merely because they exist. +4. Treat routed references as binding project instructions within their stated scope. Resolve conflicts using the precedence rules in `AGENTS.md`. +5. If a required reference is missing, unreadable, outside the repository, or internally inconsistent, stop the affected work and report the exact problem instead of guessing. + +## Change Handling + +- Edit authored project detail under `.agent/references/` when the durable rule belongs only to that repository. +- Edit the provider's `.agent/consumer-references/` when the rule is part of a shared consumer contract. +- Never edit generated `.agent-harness/references/` copies directly. +- Changing `.agent/references/` does not require recomposing `AGENTS.md` when its route is unchanged; changing routing, `project.md`, `consumer.md`, or shared reference sources does. + +Before completion, confirm that the references used still exist and that the result does not contradict them. This skill does not expand authorization to edit, commit, push, deploy, connect to external systems, or perform destructive operations. diff --git a/.agents/skills/verification-before-completion/SKILL.md b/.agents/skills/verification-before-completion/SKILL.md new file mode 100644 index 0000000..05e21ed --- /dev/null +++ b/.agents/skills/verification-before-completion/SKILL.md @@ -0,0 +1,38 @@ +--- +name: verification-before-completion +description: Require fresh, claim-specific evidence before reporting work complete, fixed, passing, ready, or safe to commit or publish. +--- + + +# Verification Before Completion + +No completion claim without fresh evidence. This workflow verifies status; it does not authorize a commit, push, deployment, database operation, or other protected action. + +## Verification Gate + +Before making a success claim: + +1. State the exact claim internally and identify which observable check can prove or disprove it. +2. Run the relevant command or inspection fresh after the final change. Use repository-defined commands; do not invent a substitute that proves a different property. +3. Read the complete result needed for the claim, including the exit code, failure count, skipped checks, and generated changes. +4. Compare the evidence with the claim and the approved acceptance criteria. +5. Report only the status supported by that evidence. + +## Evidence Rules + +- A passing lint does not prove compilation, a passing build does not prove runtime behavior, and a passing narrow test does not prove unrelated requirements. +- For a regression test, establish that it is capable of detecting the defect when practical; do not treat an always-passing test as proof. +- Recheck the worktree or final diff after generators, formatters, tests, or builds that may create or alter files. +- Separate verified results, failures, checks not run, and pre-existing failures. Never quietly merge them into a success statement. +- For delegated work, inspect the returned changes and run the relevant verification yourself before accepting the completion claim. +- For absence or universal claims such as “no occurrences” or “all projects,” use a check whose scope actually covers the claim. + +## Reporting + +- Cite the commands or inspections actually run and summarize their observed results. +- If a required check cannot run, state the actual incomplete or blocked status and the exact reason. +- Do not use “should work,” “probably passes,” “seems correct,” or similar language as a substitute for verification. +- Do not claim completion while a required check is failing or while known correctness, encoding, security, or generated-output drift remains unresolved. diff --git a/.claude/skills/attention-aware-communication/SKILL.md b/.claude/skills/attention-aware-communication/SKILL.md new file mode 100644 index 0000000..e27dde4 --- /dev/null +++ b/.claude/skills/attention-aware-communication/SKILL.md @@ -0,0 +1,41 @@ +--- +name: attention-aware-communication +description: Shape substantive answers, progress updates, and completion reports for fast, accurate reading without reducing the underlying work. +--- + + +# Attention-Aware Communication + +This skill changes presentation only. Investigate, implement, and verify as deeply as the task requires. + +## Default: Attention-kind + +- Put the bottom line in the first sentence and use plain Korean. +- Say the least that fully answers, then stop. Remove preambles, padding, repetition, and closing restatements. +- Never omit a number, scope condition, risk, prerequisite, uncertainty, or other fact that could cause the user to act incorrectly. +- For genuine breadth, explain the one or two most important points first, name the remaining areas, and let the user choose whether to expand them. Do not use this to defer required caveats or a complete focused answer. +- When the user asks for a detailed explanation, walkthrough, rationale, or full picture, suspend brevity and provide the necessary detail in scannable sections. +- When asked for a deliverable such as a command, message, snippet, or commit text, return the deliverable without unnecessary framing unless safety or correctness requires context. +- Ask one blocking question at a time and put it last. Keep working when a non-blocking assumption is safe. + +## Progress and Completion: Rundown + +Use Rundown formatting when a task has multiple steps or mixed states: + +- Start with a one-line outcome that includes any blocker. +- Distinguish verified completion, work in progress, work not started, and unknown state. Omit empty categories. +- Put each blocker or material risk on its own line. +- Report only observed states. Mark an unknown as unknown and state what check would resolve it. +- End with the next action or a small numbered choice only when the user must decide. + +## Explicit-Only: Spartan + +Use Spartan style only when the user explicitly asks for it: + +- Lead with the complete answer in one sentence. +- Be terse, blunt, and direct; remove warmth, hedging, transitions, narration, and summaries. +- Keep all load-bearing facts, warnings, and conditions even when they make the answer longer. +- If the user also asks for depth, provide the full detail in short, separated blocks. diff --git a/.claude/skills/karpathy-guidelines/SKILL.md b/.claude/skills/karpathy-guidelines/SKILL.md new file mode 100644 index 0000000..bbb7791 --- /dev/null +++ b/.claude/skills/karpathy-guidelines/SKILL.md @@ -0,0 +1,37 @@ +--- +name: karpathy-guidelines +description: Keep implementation, refactoring, and code review assumption-aware, simple, surgical, and tied to verifiable success criteria. +--- + + +# Karpathy Guidelines + +Use these guidelines while implementing, refactoring, or reviewing code. They refine execution quality but do not expand the approved task scope. + +## Think Before Coding + +- Inspect the relevant code and repository conventions before choosing a solution. +- Surface an assumption when different choices would materially change behavior, compatibility, data, or scope. +- Ask only when the decision cannot be discovered safely and a reasonable assumption would be risky. Otherwise proceed with the smallest reasonable assumption and report it. + +## Simplicity First + +- Implement the smallest complete solution that satisfies the observable requirement. +- Do not add speculative abstractions, extension points, configuration, fallback paths, or dependencies for hypothetical future use. +- Prefer an existing repository pattern or standard-library capability over a new local framework. + +## Surgical Changes + +- Every changed line must trace to the approved objective, required validation, or a necessary compatibility adjustment. +- Preserve existing naming, structure, public behavior, and formatting outside that boundary. +- Do not mix the task with unrelated cleanup. Remove dead code, duplication, or ceremony introduced by the current change before finishing. + +## Goal-Driven Execution + +- Translate the request into observable success criteria before implementation. +- Choose the narrowest check that can fail for the behavior being changed, then run broader repository checks when appropriate. +- Iterate only within the approved scope until the criteria pass or a concrete blocker is established. +- Before reporting completion, inspect the final diff for unnecessary code and use `verification-before-completion` for fresh evidence. diff --git a/.claude/skills/project-reference-loader/SKILL.md b/.claude/skills/project-reference-loader/SKILL.md new file mode 100644 index 0000000..febb5b7 --- /dev/null +++ b/.claude/skills/project-reference-loader/SKILL.md @@ -0,0 +1,29 @@ +--- +name: project-reference-loader +description: Load the current project-specific and shared reference documents routed by AGENTS.md before substantive repository analysis, implementation, debugging, review, or planning. +--- + + +# Project Reference Loader + +Use the repository's generated `AGENTS.md` as the routing entrypoint. + +## Workflow + +1. Find the `Required Project References` and shared-contract reference routes that match the current task. +2. Read the current contents of every matching file before relying on remembered project behavior, even when the file was read earlier in the session. +3. If the task crosses multiple scopes, read every matching reference. Do not load unrelated references merely because they exist. +4. Treat routed references as binding project instructions within their stated scope. Resolve conflicts using the precedence rules in `AGENTS.md`. +5. If a required reference is missing, unreadable, outside the repository, or internally inconsistent, stop the affected work and report the exact problem instead of guessing. + +## Change Handling + +- Edit authored project detail under `.agent/references/` when the durable rule belongs only to that repository. +- Edit the provider's `.agent/consumer-references/` when the rule is part of a shared consumer contract. +- Never edit generated `.agent-harness/references/` copies directly. +- Changing `.agent/references/` does not require recomposing `AGENTS.md` when its route is unchanged; changing routing, `project.md`, `consumer.md`, or shared reference sources does. + +Before completion, confirm that the references used still exist and that the result does not contradict them. This skill does not expand authorization to edit, commit, push, deploy, connect to external systems, or perform destructive operations. diff --git a/.claude/skills/verification-before-completion/SKILL.md b/.claude/skills/verification-before-completion/SKILL.md new file mode 100644 index 0000000..05e21ed --- /dev/null +++ b/.claude/skills/verification-before-completion/SKILL.md @@ -0,0 +1,38 @@ +--- +name: verification-before-completion +description: Require fresh, claim-specific evidence before reporting work complete, fixed, passing, ready, or safe to commit or publish. +--- + + +# Verification Before Completion + +No completion claim without fresh evidence. This workflow verifies status; it does not authorize a commit, push, deployment, database operation, or other protected action. + +## Verification Gate + +Before making a success claim: + +1. State the exact claim internally and identify which observable check can prove or disprove it. +2. Run the relevant command or inspection fresh after the final change. Use repository-defined commands; do not invent a substitute that proves a different property. +3. Read the complete result needed for the claim, including the exit code, failure count, skipped checks, and generated changes. +4. Compare the evidence with the claim and the approved acceptance criteria. +5. Report only the status supported by that evidence. + +## Evidence Rules + +- A passing lint does not prove compilation, a passing build does not prove runtime behavior, and a passing narrow test does not prove unrelated requirements. +- For a regression test, establish that it is capable of detecting the defect when practical; do not treat an always-passing test as proof. +- Recheck the worktree or final diff after generators, formatters, tests, or builds that may create or alter files. +- Separate verified results, failures, checks not run, and pre-existing failures. Never quietly merge them into a success statement. +- For delegated work, inspect the returned changes and run the relevant verification yourself before accepting the completion claim. +- For absence or universal claims such as “no occurrences” or “all projects,” use a check whose scope actually covers the claim. + +## Reporting + +- Cite the commands or inspections actually run and summarize their observed results. +- If a required check cannot run, state the actual incomplete or blocked status and the exact reason. +- Do not use “should work,” “probably passes,” “seems correct,” or similar language as a substitute for verification. +- Do not claim completion while a required check is failing or while known correctness, encoding, security, or generated-output drift remains unresolved. diff --git a/AGENTS.md b/AGENTS.md index 664c21c..2b28406 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,13 @@ Later and more specific instructions may override earlier general instructions o - Lead with the result or decision, then provide only the detail needed to verify it. - Do not create or retain a full session transcript. +### Attention-Aware Response Style + +- Use `attention-aware-communication` for substantive answers, progress updates, and completion reports. +- Default to concise, bottom-line-first Korean without omitting a condition, risk, number, or uncertainty needed for a correct decision. +- Give full detail when the user requests depth. Use Spartan style only when explicitly requested. +- Presentation rules never reduce investigation, implementation, validation, or reporting obligations. + ## Work Authorization - The default workflow is discussion first and explicit execution approval second. @@ -152,6 +159,13 @@ Preferred human-facing tools: - If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action. - Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized. +## Workflow Skills + +- Use `project-reference-loader` before substantive repository analysis, planning, implementation, debugging, or review. Read only the current project and shared references routed for that task, and reread them for each related task even if they were loaded earlier in the session. +- Use `karpathy-guidelines` when implementing, refactoring, or reviewing code. It keeps assumptions visible, changes surgical, and success criteria verifiable. +- Use `verification-before-completion` before claiming that work is complete, fixed, passing, ready, or safe to commit or publish. +- A skill does not expand task scope or authorize Git publication, database execution, deployment, destructive actions, or external communication. + ## Validation - Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands. @@ -222,61 +236,38 @@ When implementation is complete, report in Korean: ## KriFrontCommon Consumer Contract -### Package Usage - -- Consume this contract through the published `@kri/common` package and only through entry points declared in its `package.json` `exports` map. -- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities. -- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability. +- Consume the published `@kri/common` package only through entry points declared by its `package.json` `exports` map. - Do not import from `@kri/common/src/*`, `@kri/common/dist/*`, or another undeclared deep path. -- Do not copy or fork a shared utility locally merely to avoid using an available public entry point. Propose a backward-compatible library addition when the shared contract is genuinely missing. - -### Runtime and Optional Integrations - -- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary. -- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point. -- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper. -- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value. -- Prefer named public exports and retain the consumer project's current module system and bundler conventions. - -### React Compiler and Manual Memoization - -- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration. -- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as a routine performance precaution. -- Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem. -- Preserve existing memoization unless approved and verified for removal. Use `"use memo"` or `"use no memo"` only for a documented compiler boundary. - -### Project Instruction Budget - -- Keep `.agent/project.md` at or below 8 KiB (8,192 bytes) as the normal target. Do not delete material rules merely to meet the budget; move schemas, endpoint inventories, examples, and temporary issue history to linked project documentation, and keep concise read-routing instructions here. - -### Change Safety - -- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes. -- Review release notes and the actual affected API before upgrading. Run the consumer's focused type-check, test, and build commands after an upgrade. +- Prefer a public shared helper or an approved backward-compatible library addition over copying or forking shared behavior locally. - Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope. -## KriFrontCommon Repository Rules +### Required Shared References -### Repository Role and Public Surface +Before each related task, read the current contents of every matching reference, even if it was read earlier in the session. -- This repository publishes the ESM package `@kri/common`; the repository name and package name intentionally differ. -- Treat `package.json` `exports`, exported TypeScript declarations, entry-point behavior, and documented environment requirements as public contracts. -- Supported entry points are the package root and the explicitly declared subpaths in `package.json`. Do not create or document imports from `src`, `dist`, or another undeclared path. -- Keep runtime-specific code separated. Browser-only APIs must not leak into server entry points, and server-only behavior must not enter browser bundles. -- `src` is the source of truth. `dist` and declaration files are generated artifacts and must not be edited directly. +| Task scope | Required reference | +|---|---| +| Package entry points, runtime boundaries, HTTP, authentication, state, storage, environment, or optional peer integrations | `.agent-harness/references/kri-front-common/package-and-runtime.md` | +| React rendering performance, memoization, or React Compiler behavior | `.agent-harness/references/kri-front-common/react-compiler.md` | +| Package upgrade, dependency changes, lockfile, or verification | `.agent-harness/references/kri-front-common/change-and-verification.md` | -### TypeScript and Dependency Rules +If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead. -- Preserve ESM, `NodeNext` module resolution, explicit `.js` relative import specifiers, declaration generation, and the current strict compiler options. -- Keep exported types narrow and backward-compatible. Review any changed function signature, default, thrown error, serialization shape, or type export as a consumer-facing change. -- React, TanStack Query, and Jotai integrations are optional. Do not make an optional peer mandatory for consumers that use only core utilities. -- Do not add hidden global state for configuration, authentication, HTTP error handling, or query behavior. -- Never expose secrets or server-only environment values through browser-facing configuration helpers. +# KriFrontCommon Project Instruction Router -### Verification and Release Boundary +## Required Project References -- Install with the repository's selected package manager and lockfile. -- Run `npm run typecheck` for source changes and `npm run build` when declarations or package output may change. -- Inspect the relevant `dist` entry points and generated declarations after changing exports. -- Update `.agent/consumer.md` and human-facing documentation in the same approved change when a public contract changes. -- Version changes, publication, registry changes, and consumer-repository edits require separate explicit approval. +Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session. + +| Task scope | Required reference | +|---|---| +| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` | + +If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current. + +## Harness Workflow + +- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly. +- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`. +- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8. +- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source. diff --git a/package-lock.json b/package-lock.json index 131b724..b5ffe03 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@kri/common", - "version": "0.18.1", + "version": "0.18.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@kri/common", - "version": "0.18.1", + "version": "0.18.5", "license": "UNLICENSED", "dependencies": { "clsx": "^2.1.1", diff --git a/package.json b/package.json index 5cbd087..05a46d2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kri/common", - "version": "0.18.4", + "version": "0.18.5", "description": "KRI 프런트엔드 공통 유틸리티", "type": "module", "main": "./dist/index.js",