From 360f449738012914b69d429492c7ae5704e70c61 Mon Sep 17 00:00:00 2001 From: "K. Hodges" Date: Sun, 17 May 2026 01:54:22 -0700 Subject: [PATCH] next steps --- .gitignore | 5 +- docs/next_steps.md | 204 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 208 insertions(+), 1 deletion(-) create mode 100644 docs/next_steps.md diff --git a/.gitignore b/.gitignore index dd15ec4..19c24e3 100644 --- a/.gitignore +++ b/.gitignore @@ -178,4 +178,7 @@ cython_debug/ # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data # refer to https://docs.cursor.com/context/ignore-files .cursorignore -.cursorindexingignore \ No newline at end of file +.cursorindexingignore + +# Local NightShift operator notes +local_log.md diff --git a/docs/next_steps.md b/docs/next_steps.md new file mode 100644 index 0000000..30a6cfc --- /dev/null +++ b/docs/next_steps.md @@ -0,0 +1,204 @@ +# Next Steps: Editing Agent Support + +NightShift currently orchestrates agent prompts, command execution, artifacts, reports, retries, and context. It does not yet apply code changes by itself. + +To make NightShift actually edit code, add an implementation application layer between agent output and test execution. + +Current behavior: + +```text +prompt -> model/command -> implementation-log.md +``` + +Desired editing behavior: + +```text +prompt -> model/command -> proposed patch -> validate patch -> apply patch -> capture diff -> run tests +``` + +## 1. Define an Edit Contract + +The implementer needs to output a machine-usable edit format rather than freeform prose. + +Best first contract: + +```text +unified diff patch +``` + +NightShift should accept one clear patch format and reject everything else. This matters because model output often includes commentary, markdown fences, partial files, or invalid patches. + +## 2. Add Patch Extraction and Validation + +NightShift needs to extract a proposed edit from implementer output and validate it before touching the repository. + +Validation should check: + +- patch is present +- patch only touches paths inside the project root +- patch only touches configured scoped paths +- patch does not touch `.git/`, `.nightshift/`, secrets, or config unless allowed +- patch does not delete large unrelated files +- patch applies cleanly +- patch size is reasonable +- binary changes are rejected initially + +## 3. Add a Patch Applier + +Once a patch passes validation, NightShift applies it. + +Practical first option: + +```text +git apply --check +git apply +``` + +This is easier than writing a patch engine, but it means editing mode depends on git. + +Artifacts should include: + +```text +proposed.patch +patch-apply-output.txt +diff.patch +``` + +## 4. Separate Implementation Generation From Patch Application + +Do not make the agent executor silently edit files. + +Better pipeline shape: + +```text +plan +review_plan +implement +apply_patch +test +static +review +``` + +The implementer generates an artifact. A deterministic NightShift stage validates and applies it. This keeps model output separate from repository mutation. + +## 5. Define Failure and Retry Behavior + +If patch application succeeds but tests fail, NightShift needs an explicit policy. + +Safest early behavior: + +```text +apply patch +run tests +if tests fail, keep changes and artifacts +retry by generating another patch against current state +``` + +More advanced behavior could reverse failed patches, but that requires stronger state tracking. + +## 6. Feed Patch and Test Failures Into Retry Context + +Retry context should include compact facts such as: + +- previous patch failed to apply because X +- tests failed with Y +- reviewer objected to Z +- files changed so far + +This makes retries useful without dumping full transcripts into prompts. + +## 7. Tighten Write Safety + +Editing needs stricter safety than logging. + +Add: + +- writable path allowlist +- protected paths +- max patch size +- max files changed +- max line count changed +- no symlink following outside root +- no writes to `.git`, `.nightshift`, virtualenvs, or lockfiles unless allowed +- optional clean-worktree requirement before editing + +The current path safety is a start, but editing needs a dedicated write policy. + +## 8. Update Prompts + +The implementer prompt should require exact patch output. + +Example: + +```text +Output only a unified diff. +Do not include markdown fences. +Do not include explanation. +Only edit files needed for the task. +Include tests when needed. +``` + +The reviewer should review the actual diff and test output, not just prose. + +## 9. Add Editing Safety Tests + +Important test cases: + +- valid patch applies +- invalid patch fails cleanly +- patch outside root is rejected +- patch touching forbidden path is rejected +- patch with no changes is rejected +- failed apply writes artifacts +- failed tests still produce reports +- retry receives patch failure context +- task is not marked complete unless patch, tests, and review pass + +## 10. Decide on Editing Modes + +There are two possible editing modes. + +### Patch Mode + +The model emits a patch. NightShift validates and applies it. + +Pros: + +- auditable +- safer +- deterministic application +- easy to review + +Cons: + +- models sometimes emit malformed patches + +### Command Editing Mode + +An agent command directly edits files. + +Pros: + +- works with tools like Codex CLI or Claude Code +- more capable + +Cons: + +- harder to sandbox +- harder to know what happened without before/after diffs +- needs stronger git and diff capture + +Recommended path: + +1. Implement patch mode first. +2. Add command editing mode later behind stricter safety and artifact capture. + +Core principle: + +```text +Agents propose. +NightShift disposes. +``` + +The agent should not be trusted to mutate the repository directly until NightShift has a strong audit and safety layer around that mutation.