261006_01_ENH: 에이전트 참조 문서 합성 및 검증 기능 추가

This commit is contained in:
2026-10-06 10:19:14 +09:00
parent 74d8ec48d2
commit 4ec2ef8bb7
17 changed files with 1435 additions and 66 deletions

View File

@@ -47,6 +47,7 @@ async function createFixture(t) {
path.join(packageRoot, "schemas", "workspace.schema.json"),
path.join(harnessRoot, "schemas", "workspace.schema.json"),
);
await cp(path.join(packageRoot, "skills"), path.join(harnessRoot, "skills"), { recursive: true });
await writeText(
path.join(harnessRoot, "workspace.yml"),
@@ -70,6 +71,7 @@ contracts:
- id: kri-ui-registry
provider_project_id: kri-ui-registry
consumer_file: .agent/consumer.md
consumer_references_dir: .agent/consumer-references
order: 100
required_layers:
- frontend
@@ -94,7 +96,11 @@ contracts:
await writeText(
path.join(providerRoot, ".agent", "consumer.md"),
"## KRI UI Consumer Rule\n",
"## KRI UI Consumer Rule\n\n- Read `.agent-harness/references/kri-ui-registry/components.md` before component work.\n",
);
await writeText(
path.join(providerRoot, ".agent", "consumer-references", "components.md"),
"# Shared component contract\n",
);
await writeText(
path.join(providerRoot, ".agent", "profile.yml"),
@@ -113,7 +119,7 @@ shared_contracts:
- kri-ui-registry
`,
);
await writeText(path.join(providerRoot, ".agent", "project.md"), "## Registry Project Rule\n");
await writeText(path.join(providerRoot, ".agent", "project.md"), "## Registry Project Rule\n\n## Required Project References\n\n- No additional project references are required.\n");
await writeText(
path.join(appRoot, ".agent", "profile.yml"),
`schema_version: 1
@@ -144,7 +150,7 @@ migration:
strategy: staged
`,
);
await writeText(path.join(appRoot, ".agent", "project.md"), "## Project Rule\n");
await writeText(path.join(appRoot, ".agent", "project.md"), "## Project Rule\n\n## Required Project References\n\n- No additional project references are required.\n");
await writeText(
path.join(anotherAppRoot, ".agent", "profile.yml"),
@@ -164,7 +170,7 @@ shared_contracts:
- kri-ui-registry
`,
);
await writeText(path.join(anotherAppRoot, ".agent", "project.md"), "## Another Project Rule\n");
await writeText(path.join(anotherAppRoot, ".agent", "project.md"), "## Another Project Rule\n\n## Required Project References\n\n- No additional project references are required.\n");
await writeText(
path.join(unrelatedRoot, ".agent", "profile.yml"),
@@ -179,7 +185,7 @@ stack:
- typescript
`,
);
await writeText(path.join(unrelatedRoot, ".agent", "project.md"), "## Unrelated Rule\n");
await writeText(path.join(unrelatedRoot, ".agent", "project.md"), "## Unrelated Rule\n\n## Required Project References\n\n- No additional project references are required.\n");
return { temporaryRoot, harnessRoot, appRoot, anotherAppRoot, providerRoot, unrelatedRoot };
}
@@ -204,17 +210,95 @@ test("composes fragments in deterministic order and verifies byte-for-byte outpu
);
assert.equal(plan.output.agents, "missing");
assert.equal(plan.output.claude, "missing");
assert.deepEqual(
plan.skills.map((skill) => skill.state),
["missing", "missing", "missing", "missing", "missing", "missing", "missing", "missing"],
);
assert.deepEqual(plan.managedReferences.map((reference) => reference.state), ["missing"]);
const result = await composeProject(harnessRoot, "sample-front");
assert.deepEqual(result.changed, ["AGENTS.md", "CLAUDE.md"]);
assert.deepEqual(result.changed, [
"AGENTS.md",
"CLAUDE.md",
".agents/skills/attention-aware-communication/SKILL.md",
".claude/skills/attention-aware-communication/SKILL.md",
".agents/skills/karpathy-guidelines/SKILL.md",
".claude/skills/karpathy-guidelines/SKILL.md",
".agents/skills/project-reference-loader/SKILL.md",
".claude/skills/project-reference-loader/SKILL.md",
".agents/skills/verification-before-completion/SKILL.md",
".claude/skills/verification-before-completion/SKILL.md",
".agent-harness/references/kri-ui-registry/components.md",
]);
assert.equal(await readFile(path.join(appRoot, "AGENTS.md"), "utf8"), result.agentsContent);
assert.equal(await readFile(path.join(appRoot, "CLAUDE.md"), "utf8"), "@AGENTS.md\n");
for (const skill of result.skills) {
assert.equal(await readFile(skill.targetPath, "utf8"), skill.content);
assert.match(skill.content, /GENERATED BY KRI AGENT HARNESS/);
}
for (const reference of result.managedReferences) {
assert.equal(await readFile(reference.targetPath, "utf8"), reference.content);
assert.match(reference.content, /GENERATED BY KRI AGENT HARNESS/);
}
const verified = await verifyProject(harnessRoot, "sample-front");
assert.deepEqual(verified.output, { agents: "current", claude: "current" });
assert.deepEqual(
verified.skills.map((skill) => skill.state),
["current", "current", "current", "current", "current", "current", "current", "current"],
);
assert.deepEqual(verified.managedReferences.map((reference) => reference.state), ["current"]);
assert.deepEqual((await composeProject(harnessRoot, "sample-front")).changed, []);
});
test("refuses to overwrite an unmanaged skill", async (t) => {
const { harnessRoot, appRoot } = await createFixture(t);
await writeText(
path.join(appRoot, ".agents", "skills", "karpathy-guidelines", "SKILL.md"),
"# Hand-written skill\n",
);
await assert.rejects(
() => composeProject(harnessRoot, "sample-front"),
/Refusing to overwrite unmanaged skill \.agents\/skills\/karpathy-guidelines\/SKILL\.md/,
);
});
test("validates routed project references and rejects unreferenced files", async (t) => {
const { harnessRoot, appRoot } = await createFixture(t);
await writeText(
path.join(appRoot, ".agent", "references", "api-contract.md"),
"# API contract\n",
);
await assert.rejects(
() => planProject(harnessRoot, "sample-front"),
/Project reference is not routed from \.agent\/project\.md/,
);
await writeText(
path.join(appRoot, ".agent", "project.md"),
"## Project Rule\n\n## Required Project References\n\n- Before API work, read `.agent/references/api-contract.md`.\n",
);
const plan = await planProject(harnessRoot, "sample-front");
assert.deepEqual(
plan.projectReferences.map((reference) => reference.relativePath),
[".agent/references/api-contract.md"],
);
});
test("refuses to overwrite an unmanaged shared reference", async (t) => {
const { harnessRoot, appRoot } = await createFixture(t);
await writeText(
path.join(appRoot, ".agent-harness", "references", "kri-ui-registry", "components.md"),
"# Hand-written shared reference\n",
);
await assert.rejects(
() => composeProject(harnessRoot, "sample-front"),
/Refusing to overwrite unmanaged shared reference/,
);
});
test("rejects nextjs without react", async (t) => {
const { harnessRoot, appRoot } = await createFixture(t);
const profilePath = path.join(appRoot, ".agent", "profile.yml");
@@ -333,7 +417,7 @@ stack:
);
await writeText(
path.join(projectRoot, ".agent", "project.md"),
"## Legacy Korean Path Rule\n",
"## Legacy Korean Path Rule\n\n## Required Project References\n\n- No additional project references are required.\n",
);
const registration = await registerProject(
@@ -345,19 +429,23 @@ stack:
const plan = await planProject(harnessRoot, "legacy-korean-path");
assert.equal(path.normalize(plan.repositoryPath), path.normalize(projectRoot));
assert.deepEqual((await composeProject(harnessRoot, "legacy-korean-path")).changed, [
"AGENTS.md",
"CLAUDE.md",
]);
const composed = await composeProject(harnessRoot, "legacy-korean-path");
assert.deepEqual(composed.changed.slice(0, 2), ["AGENTS.md", "CLAUDE.md"]);
assert.equal(composed.changed.length, 10);
assert.deepEqual((await verifyProject(harnessRoot, "legacy-korean-path")).output, {
agents: "current",
claude: "current",
});
assert.ok(
(await verifyProject(harnessRoot, "legacy-korean-path")).skills.every(
(skill) => skill.state === "current",
),
);
});
test("fails instead of truncating output above the hard size limit", async (t) => {
const { harnessRoot, appRoot } = await createFixture(t);
await writeText(path.join(appRoot, ".agent", "project.md"), `## Project Rule\n\n${"x".repeat(33_000)}\n`);
await writeText(path.join(appRoot, ".agent", "project.md"), `## Project Rule\n\n${"x".repeat(33_000)}\n\n## Required Project References\n\n- No additional project references are required.\n`);
await assert.rejects(
() => planProject(harnessRoot, "sample-front"),
@@ -399,6 +487,19 @@ test("selects a contract provider first, sorts consumers, and composes only affe
for (const affectedRoot of [providerRoot, anotherAppRoot, appRoot]) {
assert.match(await readFile(path.join(affectedRoot, "AGENTS.md"), "utf8"), /GENERATED BY KRI AGENT HARNESS/);
assert.equal(await readFile(path.join(affectedRoot, "CLAUDE.md"), "utf8"), "@AGENTS.md\n");
assert.match(
await readFile(
path.join(
affectedRoot,
".agents",
"skills",
"verification-before-completion",
"SKILL.md",
),
"utf8",
),
/GENERATED BY KRI AGENT HARNESS/,
);
}
assert.equal(
await readFile(path.join(unrelatedRoot, "AGENTS.md"), "utf8").catch(() => null),