okstra 0.226.0 → 0.228.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +2 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/wizard.mjs +12 -15
  5. package/dist/commands/execute/wizard.mjs.map +1 -1
  6. package/docs/architecture/storage-model.md +77 -0
  7. package/docs/cli.md +43 -7
  8. package/docs/project-structure-overview.md +13 -3
  9. package/package.json +1 -1
  10. package/runtime/BUILD.json +2 -2
  11. package/runtime/agents/operations/code-review.json +1 -1
  12. package/runtime/prompts/duties/code-reviewer.json +1 -0
  13. package/runtime/prompts/lead/convergence.md +5 -19
  14. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  15. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  16. package/runtime/prompts/wizard/prompts.ko.json +44 -0
  17. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  18. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
  19. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
  20. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
  21. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  22. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  23. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  24. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  25. package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
  26. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  27. package/runtime/python/okstra_ctl/code_review_target.py +115 -55
  28. package/runtime/python/okstra_ctl/conformance.py +9 -3
  29. package/runtime/python/okstra_ctl/correction_cli.py +6 -5
  30. package/runtime/python/okstra_ctl/correction_round.py +1 -1
  31. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  32. package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
  33. package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
  34. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  35. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  36. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  37. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  38. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  39. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  40. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  41. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  42. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  43. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  44. package/runtime/python/okstra_ctl/paths.py +4 -0
  45. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  46. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  47. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  48. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  49. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
  50. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
  51. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
  53. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  54. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  55. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  57. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
  58. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
  59. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  60. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  61. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  62. package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
  63. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  64. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  65. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  66. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  67. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  68. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  69. package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
  70. package/runtime/python/okstra_ctl/render.py +10 -0
  71. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  72. package/runtime/python/okstra_ctl/run.py +123 -6
  73. package/runtime/python/okstra_ctl/stage_done.py +5 -4
  74. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  75. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  76. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  77. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  78. package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
  79. package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
  80. package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
  81. package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
  82. package/runtime/python/okstra_ctl/wizard/render.py +2 -2
  83. package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
  84. package/runtime/python/okstra_ctl/wizard/state.py +55 -14
  85. package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
  86. package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
  87. package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
  88. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  89. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  90. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  91. package/runtime/python/okstra_ctl/write_policy.py +33 -18
  92. package/runtime/python/okstra_project/dirs.py +22 -0
  93. package/runtime/python/okstra_project/resolver.py +10 -0
  94. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  95. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  96. package/runtime/skills/okstra-code-review/SKILL.md +59 -63
  97. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  98. package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
  99. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  100. package/runtime/skills/okstra-run/SKILL.md +21 -1
  101. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  102. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  103. package/runtime/validators/validate-brief.py +21 -5
@@ -1,17 +1,18 @@
1
1
  """Project an approved implementation-planning report onto one stage.
2
2
 
3
- An implementation executor owns exactly one stage, but its prompt pointed it at
4
- the whole plan record. Measured 2026-10-30 (fontradar-v2-api dev-11562 stage 1):
5
- that record was 7,465 lines / 385 KB, 94 KB of it the planning phase's own
6
- verification ledger, and a codex executor reported `contract-violated` because
7
- its reads overran the CLI's tool-output limit before it made an edit.
3
+ An implementation executor owns exactly one stage, while the whole plan record
4
+ also carries every other stage, the planning phase's verification ledger and the
5
+ approver's presentation. Reading that record end-to-end can overrun a CLI's
6
+ tool-output limit before the executor makes an edit.
8
7
 
9
8
  The extract keeps everything the stage can act on and drops only what is named
10
9
  in `OMITTED`, each with the reason, so a reader can tell an omission from a gap.
11
- Rows of a row family keep the stage's rows plus every row that names no stage
12
- (`plan_items._stage_scope` reads that as "applies to every stage"), and every
13
- row carries the `P-*` id the plan-body verification and lead directives cite it
14
- by. The full record stays the source of record behind `sourcePlanPath`.
10
+ Requirement-coverage and validation rows, the two families whose rows carry
11
+ `stageRefs`, keep the stage's rows plus every row that names no stage
12
+ (`plan_items.stage_scope` reads that as "applies to every stage"). Every row of
13
+ a plan-item family carries the `P-*` id the plan-body verification and lead
14
+ directives cite it by. The full record stays the source of record behind
15
+ `sourcePlanPath`.
15
16
  """
16
17
  from __future__ import annotations
17
18
 
@@ -20,26 +21,22 @@ import re
20
21
  from pathlib import Path
21
22
  from typing import Any, Mapping
22
23
 
24
+ from .design_surfaces import PATH_CHARS, stages_touching_declared_path
23
25
  from .json_boundary import load_owned_object, write_owned_object_atomic
24
- from .plan_items import PLAN_ITEM_SOURCES
26
+ from .plan_items import PLAN_ITEM_SOURCES, stage_scope
25
27
 
26
28
  EXTRACT_KIND = "approved-plan-stage-extract"
27
29
  EXTRACT_SCHEMA_VERSION = 1
28
30
 
29
- # implementationPlanning row families filtered to the stage. Every other
30
- # implementationPlanning key is carried whole unless OMITTED names it.
31
- _STAGE_ROW_FAMILIES = (
32
- "requirementCoverage",
33
- "validationChecklist",
34
- "rollbackStrategy",
35
- "dependencyMigrationRisk",
36
- "crossProjectDependencies",
37
- )
31
+ # implementationPlanning row families filtered to the stage: the report schema
32
+ # gives `stageRefs` to these rows only. Every other implementationPlanning key
33
+ # is carried whole unless OMITTED names it.
34
+ _STAGE_ROW_FAMILIES = ("requirementCoverage", "validationChecklist")
38
35
  # plan_items numbers a row family by position (`P-Val-4` is the fourth
39
36
  # validation row); a filtered list loses the position, so the id travels on the row.
40
37
  _PLAN_ITEM_PREFIX = {
41
38
  family: prefix for family, prefix, _ in PLAN_ITEM_SOURCES
42
- if family in _STAGE_ROW_FAMILIES
39
+ if family in (*_STAGE_ROW_FAMILIES, "rollbackStrategy", "dependencyMigrationRisk")
43
40
  }
44
41
  # Top-level report keys an executor acts on. Everything else at the top level is
45
42
  # report presentation, audit, or accounting and is listed in OMITTED.
@@ -59,20 +56,30 @@ OMITTED = {
59
56
  "the stage-scoped effective decision is inlined in the executor prompt "
60
57
  "under Effective design preparation"
61
58
  ),
62
- "implementationPlanning.userNarrative": "plain-language explanation for the human reader",
63
- "implementationPlanning.stages[other]": "stages this run does not own; their Stage Map rows stay",
59
+ "implementationPlanning.userNarrative": (
60
+ "plain-language explanation for the human reader"
61
+ ),
62
+ "implementationPlanning.stages[other]": (
63
+ "stages this run does not own; their Stage Map rows stay"
64
+ ),
64
65
  "implementationPlanning.directionRealization.fileStructure[other]": (
65
- "file rows whose path this stage's entry never names"
66
+ "file rows whose path or id this stage's entry never names and that the "
67
+ "planning gate's path mapping assigns to no step of this stage"
66
68
  ),
67
69
  "<rows of another stage>": (
68
- "requirementCoverage / validationChecklist / rollbackStrategy / "
69
- "dependencyMigrationRisk / crossProjectDependencies rows whose stageRefs "
70
- "exclude this stage and whose id this stage's entry never cites"
70
+ "requirementCoverage / validationChecklist rows whose stageRefs exclude "
71
+ "this stage and whose id this stage's entry never cites"
71
72
  ),
72
- "humanSummary, verdictCard, rationale, summary, finalVerdict, recommendedNextSteps": (
73
+ (
74
+ "humanSummary, verdictCard, rationale, summary, finalVerdict, "
75
+ "recommendedNextSteps"
76
+ ): (
73
77
  "report presentation for the approver"
74
78
  ),
75
- "crossVerification, agentActivity, evidence, executionStatus, executionRoles, tokenUsage": (
79
+ (
80
+ "crossVerification, agentActivity, evidence, executionStatus, "
81
+ "executionRoles, tokenUsage"
82
+ ): (
76
83
  "planning-run audit and accounting"
77
84
  ),
78
85
  "meta, frontmatter, header": "report identity",
@@ -101,8 +108,12 @@ def stage_extract_payload(
101
108
  carried_planning[key] = [stage_entry]
102
109
  elif key in _STAGE_ROW_FAMILIES:
103
110
  carried_planning[key] = _stage_rows(value, key, stage_number, cited_text)
111
+ elif key in _PLAN_ITEM_PREFIX:
112
+ carried_planning[key] = _numbered_rows(value, key)
104
113
  elif key == "directionRealization" and isinstance(value, Mapping):
105
- carried_planning[key] = _direction_realization(value, cited_text)
114
+ carried_planning[key] = _direction_realization(
115
+ value, stage_number, stage_entry, cited_text
116
+ )
106
117
  else:
107
118
  carried_planning[key] = value
108
119
  payload: dict[str, Any] = {
@@ -123,24 +134,23 @@ def stage_extract_payload(
123
134
  return payload
124
135
 
125
136
 
126
- def materialize_stage_extract(
127
- plan_path: Path,
128
- stage_number: int,
129
- output_path: Path,
130
- ) -> bool:
131
- """Write the extract for a `.data.json` plan; False when the plan is not one.
137
+ def load_stage_extract(plan_path: Path, stage_number: int) -> dict[str, Any] | None:
138
+ """The extract of a `.data.json` plan; None when the plan is not one.
132
139
 
133
140
  A Markdown plan predates the report record and has no structure to project,
134
141
  and a missing file is reported by the prompt's own plan anchor, so neither
135
142
  is an error here — the executor reads the plan as it did before.
136
143
  """
137
144
  if not plan_path.name.endswith(".data.json") or not plan_path.is_file():
138
- return False
145
+ return None
139
146
  report = load_owned_object(plan_path, artifact="approved implementation plan")
140
- payload = stage_extract_payload(report, stage_number, str(plan_path))
141
- output_path.parent.mkdir(parents=True, exist_ok=True)
142
- write_owned_object_atomic(output_path, payload, artifact="approved plan stage extract")
143
- return True
147
+ return stage_extract_payload(report, stage_number, str(plan_path))
148
+
149
+
150
+ def write_stage_extract(output_path: Path, payload: Mapping[str, Any]) -> None:
151
+ write_owned_object_atomic(
152
+ output_path, payload, artifact="approved plan stage extract"
153
+ )
144
154
 
145
155
 
146
156
  def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str, Any]:
@@ -153,42 +163,41 @@ def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str,
153
163
  raise StageExtractError(f"approved plan has no stage {stage_number}")
154
164
 
155
165
 
156
- def _stage_rows(
157
- rows: Any,
158
- family: str,
159
- stage_number: int,
160
- cited_text: str,
161
- ) -> list[Any]:
166
+ def _numbered_rows(rows: Any, family: str) -> Any:
162
167
  if not isinstance(rows, list):
163
168
  return rows
164
- kept = []
165
- for position, row in enumerate(rows, start=1):
166
- if not isinstance(row, Mapping):
167
- kept.append(row)
168
- continue
169
- if not _row_applies(row, stage_number, cited_text):
170
- continue
171
- prefix = _PLAN_ITEM_PREFIX.get(family)
172
- kept.append(
173
- {"planItemId": f"{prefix}-{position}", **row} if prefix else dict(row)
174
- )
175
- return kept
169
+ prefix = _PLAN_ITEM_PREFIX[family]
170
+ return [
171
+ {"planItemId": f"{prefix}-{position}", **row}
172
+ if isinstance(row, Mapping)
173
+ else row
174
+ for position, row in enumerate(rows, start=1)
175
+ ]
176
+
177
+
178
+ def _stage_rows(rows: Any, family: str, stage_number: int, cited_text: str) -> Any:
179
+ numbered = _numbered_rows(rows, family)
180
+ if not isinstance(numbered, list):
181
+ return numbered
182
+ return [
183
+ row for row in numbered
184
+ if not isinstance(row, Mapping) or _row_applies(row, stage_number, cited_text)
185
+ ]
176
186
 
177
187
 
178
188
  def _row_applies(row: Mapping[str, Any], stage_number: int, cited_text: str) -> bool:
179
- refs = row.get("stageRefs")
180
- stages = (
181
- [value for value in refs if isinstance(value, int) and not isinstance(value, bool)]
182
- if isinstance(refs, list) else []
183
- )
184
- if not stages or stage_number in stages:
189
+ scope = stage_scope(row)
190
+ if scope is None or stage_number in scope:
185
191
  return True
186
192
  row_id = row.get("id")
187
193
  return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
188
194
 
189
195
 
190
196
  def _direction_realization(
191
- realization: Mapping[str, Any], cited_text: str
197
+ realization: Mapping[str, Any],
198
+ stage_number: int,
199
+ stage_entry: Mapping[str, Any],
200
+ cited_text: str,
192
201
  ) -> dict[str, Any]:
193
202
  carried = dict(realization)
194
203
  rows = realization.get("fileStructure")
@@ -197,10 +206,35 @@ def _direction_realization(
197
206
  row for row in rows
198
207
  if not isinstance(row, Mapping)
199
208
  or not isinstance(row.get("path"), str)
200
- or row["path"] in cited_text
209
+ or _file_row_applies(row, stage_number, stage_entry, cited_text)
201
210
  ]
202
211
  return carried
203
212
 
204
213
 
214
+ def _file_row_applies(
215
+ row: Mapping[str, Any],
216
+ stage_number: int,
217
+ stage_entry: Mapping[str, Any],
218
+ cited_text: str,
219
+ ) -> bool:
220
+ path = row["path"]
221
+ if _names_path(cited_text, path):
222
+ return True
223
+ if stage_number in stages_touching_declared_path(path, {stage_number: stage_entry}):
224
+ return True
225
+ row_id = row.get("id")
226
+ return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
227
+
228
+
229
+ def _names_path(text: str, path: str) -> bool:
230
+ # The stage entry is prose in the report language, unlike the gate's path
231
+ # cells: a path may carry a `./` prefix, end a sentence or touch a non-ASCII
232
+ # particle, but must not sit inside a longer path.
233
+ pattern = (
234
+ rf"(?<![{PATH_CHARS}])(?:\./)?{re.escape(path)}(?=\.?(?![{PATH_CHARS}]))"
235
+ )
236
+ return re.search(pattern, text, flags=re.ASCII) is not None
237
+
238
+
205
239
  def _cites(text: str, identifier: str) -> bool:
206
240
  return re.search(rf"(?<![\w-]){re.escape(identifier)}(?![\w-])", text) is not None
@@ -10,20 +10,37 @@ task worktree 는 체크아웃이라 프로젝트 루트의 git 미추적 파일
10
10
  from __future__ import annotations
11
11
 
12
12
  import argparse
13
+ import bisect
13
14
  import datetime as dt
15
+ import itertools
16
+ import os
14
17
  import re
15
18
  import subprocess
16
19
  import sys
17
20
  from pathlib import Path
18
21
 
19
- from .analysis_packet import BY_REFERENCE_FORMAT, _fence_mask, _section_map, file_source_entries
22
+ from .analysis_packet import (
23
+ BY_REFERENCE_FORMAT,
24
+ MAX_CITED_DOCUMENT_BYTES,
25
+ _fence_mask,
26
+ _section_map,
27
+ exceeds_cited_document_limit,
28
+ file_source_entries,
29
+ project_relative_ref,
30
+ )
20
31
 
21
32
  SOURCE_MATERIAL = "Source Material"
22
33
  ATTACH_FETCHED_VIA = "okstra brief-sources attach"
23
34
  _HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
24
35
  _FRONTMATTER_RE = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
25
36
  _TOKEN_RE = re.compile(r"[^\s`'\"()\[\]<>{},;|*]+")
26
- _LINE_SUFFIX_RE = re.compile(r"(?::\d+(?:-\d+)?|#L\d+(?:-L?\d+)?)\Z")
37
+ # Inline code, a double-quoted string and a Markdown link target can hold a path with
38
+ # spaces. A link target needs no closing `)`: requiring one made every unclosed `](`
39
+ # rescan the rest of the line. Code and quotes keep their closers, so a stray `"`
40
+ # (an inch mark) does not swallow the span after it.
41
+ _SPAN_RE = re.compile(r"`([^`\n]+)`|\"([^\"\n]+)\"|\]\(<?([^)>\n]*)")
42
+ _FRAGMENT_RE = re.compile(r"[#?].*\Z")
43
+ _LINE_SUFFIX_RE = re.compile(r":\d+(?:-\d+)?\Z")
27
44
  _SOURCE_NUMBER_RE = re.compile(r"\A### Source (\d+)\b")
28
45
  # okstra 자신의 산출물(브리프, 그룹 맥락, 보고서)은 okstra 가 직접 운반한다.
29
46
  _OKSTRA_HOME = ".okstra"
@@ -38,19 +55,17 @@ def _body_lines(text: str) -> list[str]:
38
55
 
39
56
  def _project_file(token: str, root: Path) -> str | None:
40
57
  """토큰이 프로젝트 루트 아래 파일을 가리키면 루트 기준 posix 경로를 돌려준다."""
41
- if "/" not in token or "://" in token:
58
+ if "://" in token:
42
59
  return None
43
- token = _LINE_SUFFIX_RE.sub("", token.rstrip(".:"))
44
- candidate = Path(token).expanduser()
45
- path = (candidate if candidate.is_absolute() else root / candidate).resolve()
46
- try:
47
- relative = path.relative_to(root)
48
- except ValueError:
60
+ token = _LINE_SUFFIX_RE.sub("", _FRAGMENT_RE.sub("", token.strip().rstrip(".:")))
61
+ relative = project_relative_ref(token, root)
62
+ if relative is None:
49
63
  return None
50
- if (not relative.parts or relative.parts[0] == _OKSTRA_HOME
64
+ path = root / relative
65
+ if (relative == "." or Path(relative).parts[0] == _OKSTRA_HOME
51
66
  or path.suffix.lower() not in DOCUMENT_SUFFIXES or not path.is_file()):
52
67
  return None
53
- return relative.as_posix()
68
+ return relative
54
69
 
55
70
 
56
71
  def _cited_in_body(text: str, root: Path) -> list[str]:
@@ -58,46 +73,92 @@ def _cited_in_body(text: str, root: Path) -> list[str]:
58
73
  lines = _body_lines(text)
59
74
  section = ""
60
75
  for line, fenced in zip(lines, _fence_mask(lines)):
61
- if fenced:
62
- continue
63
- if line.startswith("## "):
76
+ # A fenced `## ` line is quoted text, not a section boundary; fenced
77
+ # commands still cite paths.
78
+ if not fenced and line.startswith("## "):
64
79
  section = line[3:].strip()
65
80
  continue
66
81
  if section == SOURCE_MATERIAL:
67
82
  continue
68
- for token in _TOKEN_RE.findall(line):
69
- if (relative := _project_file(token, root)) is not None:
70
- paths.setdefault(relative)
83
+ for relative in _line_citations(line, root):
84
+ paths.setdefault(relative)
71
85
  return list(paths)
72
86
 
73
87
 
88
+ def _line_citations(line: str, root: Path) -> list[str]:
89
+ """Project documents one body line cites, in order of appearance.
90
+
91
+ A word inside a span that names a document is part of that path, not a
92
+ citation of its own (`spaces.md` in `` `docs/spec with spaces.md` ``).
93
+ """
94
+ found: list[tuple[int, str]] = []
95
+ covered: list[tuple[int, int]] = []
96
+ for match in _SPAN_RE.finditer(line):
97
+ for group_index, group in enumerate(match.groups(), 1):
98
+ if group and (relative := _project_file(group, root)) is not None:
99
+ found.append((match.start(group_index), relative))
100
+ covered.append((match.start(group_index), match.end(group_index)))
101
+ # Spans and tokens both come in line order, so one forward pointer finds the span
102
+ # that could cover each token.
103
+ span = 0
104
+ for match in _TOKEN_RE.finditer(line):
105
+ while span < len(covered) and covered[span][1] <= match.start():
106
+ span += 1
107
+ if span < len(covered) and covered[span][0] <= match.start():
108
+ continue
109
+ if (relative := _project_file(match.group(), root)) is not None:
110
+ found.append((match.start(), relative))
111
+ return [relative for _, relative in sorted(found)]
112
+
113
+
74
114
  def _sourced(text: str, root: Path) -> set[str]:
115
+ """Project files that Source Material file entries name, as prepare reads them."""
75
116
  source_material = _section_map(_HTML_COMMENT_RE.sub("", text)).get(SOURCE_MATERIAL, "")
76
117
  return {
77
118
  relative
78
119
  for ref, _ in file_source_entries(source_material)
79
- for token in _TOKEN_RE.findall(ref)
80
- if (relative := _project_file(token, root)) is not None
120
+ if (relative := project_relative_ref(ref, root)) is not None
81
121
  }
82
122
 
83
123
 
84
- def _git_tracked(root: Path, paths: list[str]) -> set[str] | None:
85
- """`paths` 중 git 이 추적하는 것. git 저장소가 아니면 None — worktree 가 없으니 검사할 것도 없다."""
86
- proc = subprocess.run(
87
- ["git", "-C", str(root), "ls-files", "-z", "--", *paths],
124
+ class GitQueryError(RuntimeError):
125
+ """git could not report which cited paths it tracks, inside a git work tree."""
126
+
127
+
128
+ def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
129
+ # LC_ALL=C keeps the "not a git repository" message matchable in any locale.
130
+ return subprocess.run(
131
+ ["git", "-C", str(root), *args],
88
132
  capture_output=True,
89
133
  text=True,
90
134
  check=False,
135
+ env={**os.environ, "LC_ALL": "C"},
91
136
  )
92
- if proc.returncode != 0:
137
+
138
+
139
+ def _git_tracked(root: Path, paths: list[str]) -> set[str] | None:
140
+ """`paths` 중 git 이 추적하는 것. git 저장소가 아니면 None — worktree 가 없으니 검사할 것도 없다."""
141
+ inside = _git(root, "rev-parse", "--is-inside-work-tree")
142
+ if inside.returncode != 0:
143
+ if "not a git repository" in inside.stderr:
144
+ return None
145
+ raise GitQueryError(
146
+ f"git rev-parse --is-inside-work-tree in {root} failed: "
147
+ f"{inside.stderr.strip()}"
148
+ )
149
+ if inside.stdout.strip() != "true":
93
150
  return None
151
+ proc = _git(root, "ls-files", "-z", "--", *paths)
152
+ if proc.returncode != 0:
153
+ raise GitQueryError(f"git ls-files in {root} failed: {proc.stderr.strip()}")
94
154
  return {name for name in proc.stdout.split("\0") if name}
95
155
 
96
156
 
97
157
  def uncited_local_documents(text: str, project_root: Path) -> list[str]:
98
158
  """본문이 이름을 댄 git 미추적 프로젝트 파일 중 Source Material 의 file 항목이 없는 것."""
99
159
  root = project_root.resolve()
100
- cited = [path for path in _cited_in_body(text, root) if path not in _sourced(text, root)]
160
+ sourced = _sourced(text, root)
161
+ cited = [path for path in _cited_in_body(text, root) if path not in sourced]
101
162
  if not cited:
102
163
  return []
103
164
  tracked = _git_tracked(root, cited)
@@ -106,12 +167,26 @@ def uncited_local_documents(text: str, project_root: Path) -> list[str]:
106
167
  return [path for path in cited if path not in tracked]
107
168
 
108
169
 
109
- def _source_entry(index: int, ref: str, fetched_at: str) -> list[str]:
170
+ def too_large_to_cite(root: Path, relative: str) -> bool:
171
+ """Whether prepare refuses to copy this project file into the analysis packet."""
172
+ return exceeds_cited_document_limit((root / relative).stat().st_size)
173
+
174
+
175
+ TOO_LARGE_REASON = (
176
+ f"over {MAX_CITED_DOCUMENT_BYTES} bytes, which prepare does not copy into the "
177
+ "analysis packet; capture the cited part as-is in Source Material instead"
178
+ )
179
+
180
+
181
+ def by_reference_source_entry(
182
+ index: int, ref: str, fetched_via: str, fetched_at: str
183
+ ) -> list[str]:
184
+ """Lines of one `### Source N — file` entry that points at `ref`."""
110
185
  return [
111
186
  f"### Source {index} — file",
112
187
  "",
113
188
  f"- ref: {ref}",
114
- f"- fetched-via: {ATTACH_FETCHED_VIA}",
189
+ f"- fetched-via: {fetched_via}",
115
190
  f"- fetched-at: {fetched_at}",
116
191
  f"- format: {BY_REFERENCE_FORMAT}",
117
192
  "",
@@ -127,39 +202,82 @@ def attach_missing_sources(brief_path: Path, project_root: Path, *, now: dt.date
127
202
  missing = uncited_local_documents(text, project_root)
128
203
  if not missing:
129
204
  return []
205
+ root = project_root.resolve()
206
+ if large := [ref for ref in missing if too_large_to_cite(root, ref)]:
207
+ raise ValueError(f"{brief_path}: {', '.join(large)} {TOO_LARGE_REASON}")
130
208
  lines = text.split("\n")
131
- mask = _fence_mask(lines)
209
+ visible = _blank_html_comments(text).split("\n")
210
+ start, end = _source_material_bounds(visible, brief_path)
211
+ after = _insertion_line(text, visible, start, end)
212
+ first = _last_source_number(visible, start, end) + 1
213
+ entries = [""]
214
+ for number, ref in enumerate(missing, first):
215
+ entries.extend(by_reference_source_entry(
216
+ number, ref, ATTACH_FETCHED_VIA, now.strftime("%Y-%m-%d %H:%M")))
217
+ tail = lines[after + 1:]
218
+ if tail and not tail[0].strip():
219
+ entries.pop()
220
+ brief_path.write_text(
221
+ "\n".join([*lines[:after + 1], *entries, *tail]), encoding="utf-8"
222
+ )
223
+ return missing
224
+
225
+
226
+ def _blank_html_comments(text: str) -> str:
227
+ """`text` with comment characters replaced by spaces and its newlines kept.
228
+
229
+ Its lines align with the brief's, and its headings are the ones the
230
+ detector sees after it strips comments.
231
+ """
232
+ return _HTML_COMMENT_RE.sub(lambda m: re.sub(r"[^\n]", " ", m.group()), text)
233
+
234
+
235
+ def _source_material_bounds(visible: list[str], brief_path: Path) -> tuple[int, int]:
236
+ """Lines of the `## Source Material` heading and the next `## ` heading (or EOF)."""
237
+ mask = _fence_mask(visible)
132
238
  start = next(
133
- (i for i, (line, fenced) in enumerate(zip(lines, mask))
239
+ (i for i, (line, fenced) in enumerate(zip(visible, mask))
134
240
  if not fenced and line.strip() == f"## {SOURCE_MATERIAL}"),
135
241
  None,
136
242
  )
137
243
  if start is None:
138
244
  raise ValueError(f"{brief_path}: no `## {SOURCE_MATERIAL}` section to attach to")
139
245
  end = next(
140
- (i for i in range(start + 1, len(lines)) if not mask[i] and lines[i].startswith("## ")),
141
- len(lines),
246
+ (i for i in range(start + 1, len(visible))
247
+ if not mask[i] and visible[i].startswith("## ")),
248
+ len(visible),
142
249
  )
250
+ return start, end
251
+
252
+
253
+ def _last_source_number(visible: list[str], start: int, end: int) -> int:
254
+ mask = _fence_mask(visible)
143
255
  numbers = [int(m.group(1)) for i in range(start + 1, end) if not mask[i]
144
- if (m := _SOURCE_NUMBER_RE.match(lines[i]))]
145
- while end > start + 1 and not lines[end - 1].strip():
146
- end -= 1
147
- stamp = now.strftime("%Y-%m-%d %H:%M")
148
- entries: list[str] = [""]
149
- for offset, ref in enumerate(missing, max(numbers, default=0) + 1):
150
- entries.extend(_source_entry(offset, ref, stamp))
151
- tail = lines[end:]
152
- while tail and not tail[0].strip():
153
- tail.pop(0)
154
- brief_path.write_text("\n".join([*lines[:end], *entries, *tail]), encoding="utf-8")
155
- return missing
256
+ if (m := _SOURCE_NUMBER_RE.match(visible[i]))]
257
+ return max(numbers, default=0)
258
+
259
+
260
+ def _insertion_line(text: str, visible: list[str], start: int, end: int) -> int:
261
+ """The section line after which new entries go.
262
+
263
+ It is the last line with visible text, or the line where a comment opened
264
+ on that line closes, so the entry neither enters the comment nor precedes
265
+ text the line still carries.
266
+ """
267
+ line = next((i for i in range(end - 1, start, -1) if visible[i].strip()), start)
268
+ offsets = itertools.accumulate(len(row) + 1 for row in visible)
269
+ newlines = [offset - 1 for offset in offsets]
270
+ for match in _HTML_COMMENT_RE.finditer(text):
271
+ if match.start() <= newlines[line] < match.end():
272
+ line = bisect.bisect_left(newlines, match.end() - 1)
273
+ return line
156
274
 
157
275
 
158
276
  def _attach_command(args: argparse.Namespace) -> int:
159
277
  brief = Path(args.brief).resolve()
160
278
  try:
161
279
  added = attach_missing_sources(brief, Path(args.project_root), now=dt.datetime.now())
162
- except ValueError as exc:
280
+ except (OSError, ValueError, GitQueryError) as exc:
163
281
  print(f"brief-sources: {exc}", file=sys.stderr)
164
282
  return 2
165
283
  if not added: