T28 — AGENTS.md / CLAUDE.md cascading (findUp)

{`
const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]

/**
 * Walk up từ cwd đến worktree root, tìm file instruction đầu tiên.
 * Boundary: không vượt quá worktree root (tránh đọc ~/CLAUDE.md của user).
 */
export async function findProjectInstructions(
  cwd:      string,
  worktree: string,
): Promise<{ path: string; content: string } | null> {
  let dir       = path.resolve(cwd)
  const stop    = path.resolve(worktree)

  while (dir.startsWith(stop)) {
    for (const name of INSTRUCTION_FILES) {
      const candidate = path.join(dir, name)
      if (await fs.pathExists(candidate)) {
        return {
          path:    candidate,
          content: await fs.readFile(candidate, "utf8"),
        }
      }
    }

    // Bước lên 1 level
    const parent = path.dirname(dir)
    if (parent === dir) break   // đã reach filesystem root
    dir = parent
  }

  return null   // không tìm thấy file instruction nào
}
`}

{`
// Claims tracking: per-session Set, ngăn re-attach cùng file
const attachedFiles = new Set<string>()

export function attachInstructionIfNew(
  file: { path: string; content: string },
): string | null {
  // Nếu file đã được attach trong session này → skip
  if (attachedFiles.has(file.path)) return null

  // Mark as attached
  attachedFiles.add(file.path)

  // Trả về XML block để inject vào system prompt
  return `<project-instruction src="${file.path}">
${file.content}
</project-instruction>`
}

// Caller (buildSystem):
const instructionFile = await findProjectInstructions(ctx.cwd, ctx.worktree)
const projectBlock    = instructionFile
  ? (attachInstructionIfNew(instructionFile) ?? "")
  : ""
`}

{`
// Boundary check: dir.startsWith(stop)
// stop = worktree root (git repo root)

// SAFE: chỉ tìm trong repo
dir = "/Users/nghia/monorepo/packages/api"
stop = "/Users/nghia/monorepo"
→ "/Users/nghia/monorepo/packages/api".startsWith("/Users/nghia/monorepo") === true ✓

// STOP: không đọc file ngoài repo
dir = "/Users/nghia"   (sau khi bước ra khỏi worktree)
stop = "/Users/nghia/monorepo"
→ "/Users/nghia".startsWith("/Users/nghia/monorepo") === false → exit loop

// Tránh: ~/CLAUDE.md (global user config) leak vào project context
`}

{`
import path from "path"
import fs   from "fs/promises"

const INSTRUCTION_FILES = ["AGENTS.md", "CLAUDE.md", "CONTEXT.md"]

// 1. findUp — walk from cwd to repo root
async function findProjectInstructions(cwd: string, repoRoot: string) {
  // Normalize to real paths to handle symlinks
  let dir  = await fs.realpath(path.resolve(cwd)).catch(() => path.resolve(cwd))
  const stop = await fs.realpath(path.resolve(repoRoot)).catch(() => path.resolve(repoRoot))

  while (dir.startsWith(stop)) {
    for (const name of INSTRUCTION_FILES) {
      try {
        const candidate = path.join(dir, name)
        const content   = await fs.readFile(candidate, "utf8")
        return { path: candidate, content }
      } catch {
        // not found, continue
      }
    }

    const parent = path.dirname(dir)
    if (parent === dir) break   // filesystem root
    dir = parent
  }

  return null
}

// 2. Claims tracking — per SESSION (not module-level)
class InstructionTracker {
  private attached = new Set<string>()

  attach(file: { path: string; content: string }): string | null {
    if (this.attached.has(file.path)) return null
    this.attached.add(file.path)
    return \`<project-instruction src="\${file.path}">\n\${file.content}\n</project-instruction>\`
  }

  reset() {
    this.attached.clear()
  }
}

// 3. Usage in buildSystem
async function buildSystem(model: string, ctx: Ctx, tracker: InstructionTracker) {
  const instructionFile = await findProjectInstructions(ctx.cwd, ctx.worktree)
  const projectBlock    = instructionFile
    ? (tracker.attach(instructionFile) ?? "")
    : ""

  return [getTemplate(model), buildEnvBlock(ctx), buildSkillsBlock(ctx), projectBlock]
    .filter(Boolean)
}
`}