@apptoolkit/harness 1.0.4 → 1.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apptoolkit/harness",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A portable harness for configuring AI coding agents and engineering workflows.",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,7 @@
     "payload/author-style/spacing.llm.md",
     "payload/author-style/spacing.test.ts",
     "payload/author-style/spacing.ts",
+    "payload/harness/LEARNING.md",
     "payload/harness/POLICY.md",
     "payload/harness/PROJECT.md",
     "payload/harness/REVIEW.md",

package/payload/HARNESS.md

@@ -2,6 +2,12 @@
 
 Use this index when adopting a project or opening a fresh agent session. Resolve the project, read its applicable rules, and open the smallest workflow that matches the request.
 
+## Every session
+
+1. Resolve the active repository and its rules with the [project guide](harness/PROJECT.md) and [operating policy](harness/POLICY.md). Use the workflow index for the task. The native setup command is for init and update.
+2. Look up relevant prior work in [project knowledge](harness-local/KNOWLEDGE.md). Use the matching record and bounded evidence. Prefer tested [project tools](harness-local/TOOLS.md) for deterministic work.
+3. At each decision, correction, useful discovery, repeated operation or handoff, follow the [learning and improvement procedure](harness/LEARNING.md). Maintain applicable sibling source maps after code changes and verify the latest links before handoff.
+
 | Need | Start here |
 | --- | --- |
 | Find the procedure for a natural request | [Workflow index](harness/WORKFLOWS.md) |
@@ -9,6 +15,7 @@ Use this index when adopting a project or opening a fresh agent session. Resolve
 | Adopt, initialize or update this installation | [W20 Adoption](harness/workflows/W20.md) |
 | Resolve repositories, services and project conventions | [Project guide](harness/PROJECT.md) |
 | Check permissions, engineering rules and learning | [Operating policy](harness/POLICY.md) |
+| Apply a lesson, preserve research or improve a check | [Learning and improvement](harness/LEARNING.md) |
 | Audit a claim or independently review code | [Independent review](harness/REVIEW.md) |
 | Prepare a decision, work unit or checkpoint | [Templates](harness/TEMPLATES.md) |
 | Verify coverage against an explicit source inventory | [W23 Verification](harness/workflows/W23.md) |

package/payload/author-style/README.md

@@ -5,7 +5,7 @@ Use this profile whenever an agent writes or changes authored TypeScript in a pr
 - [Writing rules](#writing-rules): Read before editing code.
 - [Deterministic checks](#deterministic-checks): Select an appropriate profile.
 - [Install and run](#install-and-run): Run after each code edit batch and before handoff. See the [checker map](check.llm.md) when maintaining the tool.
-- [Evidence and precedence](#evidence-and-precedence): Determine what is personal, historical or specific to a project.
+- [Evidence and precedence](#evidence-and-precedence): Apply the target project rules and verify changes.
 
 ## Writing rules
 
@@ -49,6 +49,8 @@ For an existing project, follow its own rules and tools first. The verifier refu
 
 Record the selected paths and result in the normal verification evidence. Add this instruction to the adopting agent's entry point or shared verification instructions. Every agent should run the same command after a code edit batch and before delivery. The package installs no editor, Git, CI or model-specific hook.
 
+For an agent-only rule confirmed by project review, keep its configuration in a project-owned path such as `llm/harness-local/biome-agent.json`. Set `linter.rules.recommended` to false and add the scoped rules and project-owned plugins. Run the same checker with `--project-config llm/harness-local/biome-agent.json` and explicit authored paths. The checker runs the pinned profile first, followed by a separate lint pass for the local configuration. Use the corresponding `--profile` when its supplementary checks apply. A project-wide Biome configuration keeps its native command.
+
 > After each code edit batch and before handoff, run the project's applicable Biome checks. When no applicable Biome configuration exists, run the compatible profile in `llm/author-style/README.md` on the edited TypeScript files. Use the project's established formatter and lint policy first. Record the result with the other verification evidence.
 
 ## Evidence and precedence

package/payload/author-style/check.test.ts

@@ -84,6 +84,32 @@ test('uses the isolated formatter and linter on exact paths outside the harness
   assert.match(success.stdout, /Checked 1 file/);
 });
 
+test('checks learned project rules in isolation and keeps adjacent unselected files out of scope', (context) => {
+  const root = mkdtempSync(join(tmpdir(), 'harness-style-'));
+  const directory = join(root, 'llm');
+  const profile = fileURLToPath(new URL('biome-core.json', import.meta.url));
+
+  context.after(() => rmSync(root, { recursive: true, force: true }));
+  mkdirSync(directory);
+  writeFileSync(
+    join(directory, 'review.json'),
+    JSON.stringify({ linter: { rules: { recommended: false, suspicious: { noConsole: 'error' } } } }),
+  );
+  writeFileSync(join(root, 'good.ts'), 'export const value = 1;\n');
+  writeFileSync(join(root, 'bad.ts'), "console.log('noise');\n");
+
+  const good = execute(root, '--project-config', 'llm/review.json', 'good.ts');
+  const bad = execute(root, '--project-config', 'llm/review.json', 'bad.ts');
+
+  assert.equal(good.status, 0, good.stderr);
+  assert.equal(bad.status, 1);
+  assert.match(bad.stderr, /noConsole/u);
+  assert.equal(execute(root, 'bad.ts').status, 0);
+  assert.match(execute(root, '--project-config', profile, 'good.ts').stderr, /inside/u);
+  symlinkSync('review.json', join(directory, 'alias.json'));
+  assert.match(execute(root, '--project-config', 'llm/alias.json', 'good.ts').stderr, /project-owned/u);
+});
+
 test('enforces core types, explicit updates, braces, branches and class layout', (context) => {
   const root = mkdtempSync(join(tmpdir(), 'harness-style-'));
 

package/payload/author-style/check.ts

@@ -14,6 +14,7 @@ const requestSchema = z.object({
   root: z.string().refine(isAbsolute, 'Supply the absolute project directory with --root.'),
   profile: z.enum(['core', 'react', 'sql']),
   lintOnly: z.boolean(),
+  projectConfig: z.string().endsWith('.json').optional(),
   files: z.array(z.string().min(1)).min(1, 'Supply the files you changed.'),
 });
 
@@ -63,12 +64,14 @@ function checkFiles(argumentsList: string[]): number {
       root: { type: 'string' },
       profile: { type: 'string', default: 'core' },
       'lint-only': { type: 'boolean', default: false },
+      'project-config': { type: 'string' },
     },
   });
   const request = requestSchema.parse({
     root: parsed.values.root,
     profile: parsed.values.profile,
     lintOnly: parsed.values['lint-only'],
+    projectConfig: parsed.values['project-config'],
     files: parsed.positionals,
   });
   const requestedRoot = resolve(request.root);
@@ -120,36 +123,52 @@ function checkFiles(argumentsList: string[]): number {
   }
 
   const config = fileURLToPath(new URL(configurations[request.profile], import.meta.url));
+  const checks = [{ config, command: request.lintOnly ? 'lint' : 'check' }];
+
+  if (request.projectConfig) {
+    const localConfig = resolve(root, request.projectConfig);
+
+    targetRelativePath(root, localConfig);
+
+    if (realpathSync(localConfig) !== localConfig || !statSync(localConfig).isFile()) {
+      throw new Error(`Use a regular project-owned Biome configuration: ${localConfig}`);
+    }
+
+    checks.push({ config: localConfig, command: 'lint' });
+  }
+
   const biome = requireFromProfile.resolve('@biomejs/biome/bin/biome');
   const runtimeArguments = process.versions.bun ? ['--no-env-file', '--no-install'] : [];
   const environment = { ...process.env };
 
   delete environment.BIOME_BINARY;
 
-  const result = spawnSync(
-    process.execPath,
-    [
-      ...runtimeArguments,
-      biome,
-      request.lintOnly ? 'lint' : 'check',
-      `--config-path=${config}`,
-      '--error-on-warnings',
-      '--',
-      ...sources.keys(),
-    ],
-    { cwd: root, env: environment, stdio: 'inherit' },
-  );
-
-  if (result.error) {
-    throw new Error(`Cannot launch Biome in ${root}: ${result.error.message}`, { cause: result.error });
-  }
+  for (const check of checks) {
+    const result = spawnSync(
+      process.execPath,
+      [
+        ...runtimeArguments,
+        biome,
+        check.command,
+        `--config-path=${check.config}`,
+        '--error-on-warnings',
+        '--',
+        ...sources.keys(),
+      ],
+      { cwd: root, env: environment, stdio: 'inherit' },
+    );
+
+    if (result.error) {
+      throw new Error(`Cannot launch Biome in ${root}: ${result.error.message}`, { cause: result.error });
+    }
 
-  if (result.status === null) {
-    throw new Error(`Biome did not complete in ${root}${result.signal ? ` (${result.signal})` : ''}.`);
-  }
+    if (result.status === null) {
+      throw new Error(`Biome did not complete in ${root}${result.signal ? ` (${result.signal})` : ''}.`);
+    }
 
-  if (result.status !== 0) {
-    return result.status;
+    if (result.status !== 0) {
+      return result.status;
+    }
   }
 
   let count = 0;

package/payload/harness/LEARNING.md

@@ -0,0 +1,18 @@
+# Project learning and improvement
+
+## Find prior work
+
+Open `llm/harness-local/KNOWLEDGE.md` when a task involves a project rule, domain question, feedback or investigation. Match by repository, feature, ticket vocabulary and related systems. Use `rtk proxy rg -in -- <topic> llm/harness-local/KNOWLEDGE.md` when the index grows. Read the smallest relevant record with the installed `context` command and reuse its verified findings. Check the authority, evidence revision and revalidation trigger before relying on a conclusion. Open original sources when resolving gaps, changes or contradictions.
+
+## Capture a durable finding
+
+Capture important user decisions, human explanations, PR feedback, and findings from documentation or ticket research at the point of discovery. Use the project's established authority and record type. Where a project does not have one, add a topical note under `llm/harness-local/` and link it from the knowledge index. Give each record a short topical title, search terms, repository and version scope, observed or decided date, compact finding, source locator, authority, confidence or approval status, owner and revalidation trigger. Include a usable example when it disambiguates behavior. Link to the source revision, comment, message, email or document section through the approved route. Keep restricted detail and raw excerpts in the approved private store. Record a discoverable pointer only when its visibility is authorized.
+
+Keep hypotheses and proposed standards visibly pending. Capture conflicting evidence with its applicable scopes and ask the decision owner when precedence is unresolved. When a finding changes, preserve the older record or its history and link to the decision that supersedes it.
+
+## Improve tools and rules
+
+1. When work repeats, fails in a preventable way or consumes context through noisy stdout, inspect the project tool catalog and existing runner. Prefer native commands or a tested utility. Extend the smallest suitable implementation or add a parameterized TypeScript utility under the project-owned `llm/` tools area. Quote arguments independently, keep warnings and failure details, preserve exit status, and offer a native unfiltered mode. Test ordinary inputs, unexpected output and failures. Index the exact command, inputs, outputs, effects, recovery and limits.
+2. When human or PR review confirms a repeatable code rule, capture a passing and a failing example and check for a compatible Biome rule or Grit pattern. Apply it in the repository configuration for project-wide Biome, or in an agent-only configuration passed to the isolated checker with `--project-config`. Store that configuration with the applicable project rules and register the exact check in the tools index. Preserve the project's formatter, scope and existing rules. Verify both examples and the intended scope against the actual checker. Use a tested supplement for a mechanical rule that Biome cannot express. Index judgment-based guidance with examples and a review gate.
+3. Apply scoped, authorized corrections to project-owned harness instructions, indexes, tools, checks and workflows as part of ordinary work. Put shared harness changes under source control in its owning project through that project's workflow. In an installed project, keep local additions under `llm/harness-local/` or its established project-owned paths. Link extensions from the improvements index. Preserve evidence, tests, the scope of the change, and the recovery route. If a rule or permission would change, obtain the decision from its owner.
+4. Rerun affected checks and confirm a fresh session can reach the resulting artifact from the installed index. Use [W21](workflows/W21.md) for maps and knowledge records, [W23](workflows/W23.md) for checks and [W20](workflows/W20.md) for package updates.

package/payload/harness/POLICY.md

@@ -26,6 +26,8 @@ For a new project, account for every source family and require 100 percent measu
 
 ## Knowledge and improvement
 
+Apply the [learning and improvement procedure](LEARNING.md) during ordinary work. Follow its retrieval, capture and verification steps whenever the corresponding trigger occurs.
+
 Maintain an indexed, concise project memory. Before dependent work, capture confirmed decisions, corrections and discoveries at the right checkpoint with scope, rationale, evidence, owner and approval status. Separate observations, proposals and unresolved choices from accepted rules. Keep private source material and raw sensitive output in approved private storage outside the harness.
 
 Use a sibling `.llm.md` for authored implementation above 200 physical lines, for shorter important entry points, or where safe navigation needs a map. Apply the project's own thresholds and exemptions where established. Give each map a small index and stable heading or symbol locators for responsibilities, interfaces, dependencies, decisions, invariants, effects and tests. Link it from the relevant project or directory index and verify it against the source after changes.